payments
The Approve Payment Instructions API used to authorizes one or more forthcoming payment instructions by specifying their IDs. It also enables the transfer of funds to the registered beneficiaries.
The unique identifier of the payment instruction that needs to be approved. It is a required field and must be provided in the API request. The ID ensures that the correct payment instruction is identified for approval.
Successful response
PATCH /payments/payments/approve?id=text HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful response
{
"items": [
{
"type": "text",
"id": "text",
"result": "text"
}
]
}The UnApprove Payment Instructions API is used to remove the approval of one or more forthcoming payment instructions by specifying their IDs. This action reverts the previously approved payment instructions back to a pending state, enabling further modifications or cancellations.
The unique identifier for the payment instruction that you intend to unapprove. This should be a valid payment ID that corresponds to a payment instruction that has already been approved.
Successful response
DELETE /payments/payments/approve?id=text HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful response
{
"items": [
{
"type": "text",
"id": "text",
"result": "text"
}
]
}The Create Payment Instruction API designed to initiate a new payment instruction or update an existing pending payment by specifying relevant payment id. This API allows developers to create a new payment instruction or update a pending paymen by providing the necessary payment details, such as source, target, and amount.
A description or memo for the payment instruction. This can be used for reference or for providing additional context to the payment.
A unique identifier for the payment instruction. This ID should be unique across all payment instructions within your system to avoid conflicts.
The specific purpose of the payment, such as “SALA” for salary payments. This field helps categorize the payment for reporting and compliance purposes.
SALAPattern: ^([A-Z]{4})$Indicates whether the payment is pre-approved. This flag can be used to streamline the payment process, ensuring that only approved payments are processed.
Successful response
Indicates the type of the object, which in this case is “payment”.
A description of the payment, typically detailing the purpose or nature of the transaction.
he unique identifier for the payment instruction.
Indicates whether the payment has been approved for processing.
The purpose of the payment (e.g., “SALA” for salary).the purpose of the payment as a 4 letter iso-20022 code.
SALAPattern: ^[A-Z]{4}$POST /payments/payments HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 441
{
"description": "text",
"id": "text",
"purpose": "SALA",
"source": {
"type": "group",
"id": "text"
},
"target": {
"type": "contact",
"id": "text"
},
"approved": true,
"amount": {
"type": "LAND",
"amount": 1,
"currency": "text"
},
"execution": {
"type": "SEND",
"date": "2026-01-01T00:00:00.000Z",
"margin": 1
},
"final": {
"is_final": true,
"expected": "2026-01-01T00:00:00.000Z"
},
"attachments": [
{
"title": "text",
"id": "text",
"url": "text"
}
],
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}Successful response
{
"info": {
"status": "PENDING",
"credit": {
"currency": "text",
"amount": 1
},
"funding": {
"currency": "text",
"amount": 1,
"date": "2026-01-01T00:00:00.000Z"
},
"debit": {
"currency": "text",
"amount": 1
},
"rate": 1,
"fees": 1
},
"type": "payment",
"description": "text",
"id": "text",
"amount": {
"type": "LAND",
"amount": 1,
"currency": "text"
},
"approved": true,
"attachments": [
{
"title": "text",
"id": "text",
"url": "text"
}
],
"execution": {
"type": "SEND",
"date": "2026-01-01T00:00:00.000Z",
"margin": 1
},
"final": {
"is_final": true,
"expected": "2026-01-01T00:00:00.000Z"
},
"purpose": "SALA",
"source": {
"type": "text",
"id": "text"
},
"target": {
"type": "text",
"id": "text"
},
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}The Get Payments List API is a powerful tool that allows developers to retrieve a list of payment transactions associated with their account. It supports a range of filters that can be applied to narrow down the results based on specific criteria such as payment status, currency, amount, and more. This API is crucial for tracking, managing, and reporting on payments within the system.
Refers to the way the amount is categorized or represented in the transaction (LAND/SEND).
Used to return only payment requests that are approved (true) or not approved (false), don't send to return both.
Description substring to filter by.
Filters payments based on transaction Start Date (formatted as YYYY-MM-DD_to_YYYY-MM-DD).
Filters payments based on transaction End Date (formatted as YYYY-MM-DD_to_YYYY-MM-DD).
Used to return only payment requests that are final (true) or not final (false), don't send to return both.
Used to specify the starting point for filtering payments based on their funding Start Date.
Used to specify the starting point for filtering payments based on their funding End Date.
Used to filter payments based on whether they have encountered any issues during processing. Return only payment requests that have issues (true) or have no issues (false), don't send to return both.
Used to filter and retrieve specific payments based on their unique identifiers. This filter allows you to directly query for one or more payments by their unique payment IDs.
Used to filter payments based on their intended purpose or reason for the transaction. This filter allows users to narrow down the list of payments to those that were made for a specific purpose, such as salary payments, invoice payments, refunds, etc.
the purpose of the payment as a 4 letter iso-20022 code. see: https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets
^[A-Z]{4}$the purpose of the payment as a 4 letter iso-20022 code. see: https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets
Used to narrow down the list of payments to those that were requested starting from a particular date (Start Date). This is especially useful for tracking and managing recent payment requests or generating reports for specific time periods.
Used to filter payments based on the date when the payment request was initiated, specifically allowing you to retrieve payments that were requested on or before a certain date (End Date).
Used to control which part of the result set to start retrieving data from. By skipping a certain number of records, you can effectively “move” through the data in a controlled manner, useful when displaying paginated results in a user interface. If you want to retrieve records starting from the 101st payment (skipping the first 100), you would set the skip filter to 100.
^[-]?\d+(\.\d+)?$Used to retrieve payments that originated from a specific source. This is particularly useful when you want to track payments made by a certain group, account, or other defined entity within your system.he filter typically accepts a string, which represents the unique identifier of the source (such as a group ID, account ID, or another entity ID).
Used to filter payments based on their current status. This is useful for tracking the progress of payments, generating reports based on payment outcomes, or troubleshooting specific issues.
Used to specify the maximum number of records or items to return in the API response. This filter is used for pagination, allowing you to control the size of the result set returned by the API. This is useful when dealing with large datasets, as it allows you to manage the volume of data being processed and displayed at one time.
^[-]?\d+(\.\d+)?$Used to retrieve payments that are directed to a specific target entity. This is useful for tracking payments made to a particular beneficiary, account, or any other entity that receives payments.The filter accepts a string, which represents the unique identifier of the target (such as a contact ID, account ID, or another entity ID).
Successful response
GET /payments/payments HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful response
{
"items": [
{
"info": {
"status": "PENDING",
"credit": {
"currency": "text",
"amount": 1
},
"funding": {
"currency": "text",
"amount": 1,
"date": "2026-01-01T00:00:00.000Z"
},
"debit": {
"currency": "text",
"amount": 1
},
"rate": 1,
"fees": 1
},
"type": "payment",
"description": "text",
"id": "text",
"amount": {
"type": "LAND",
"amount": 1,
"currency": "text"
},
"approved": true,
"execution": {
"type": "SEND",
"date": "2026-01-01T00:00:00.000Z",
"margin": 1
},
"final": {
"is_final": true,
"expected": "2026-01-01T00:00:00.000Z"
},
"purpose": "SALA",
"source": {
"type": "text",
"id": "text"
},
"target": {
"type": "text",
"id": "text"
},
"attachments": [
{
"title": "text",
"id": "text",
"url": "text"
}
],
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"paging": {
"skip": 1,
"take": 1
}
}The Update Payment Instructions API is used to update existing payment instructions in the system. This API is essential for modifying payment details such as the amount, date, or status before processing the payment.
The unique identifier for the payment instruction that you want to update (if none is provided, an ID will be assigned). Using an existing payment ID will update the pending payment.
A brief description or notes regarding the payment instruction (remittence info).
The unique identifier for the payment instruction that you want to update (if none is provided, an ID will be assigned). Using an existing payment ID will update the pending payment.
The purpose of the payment, represented as a 4-letter ISO 20022 code (e.g., SALA for salary). see:https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets.
SALAPattern: ^([A-Z]{4})$Indicates whether the payment has been approved for processing.Set to true to mark the payment as approved and ready to be executed.
Successful response
entity type (payment)
The remittence info to send as part of the payment
The unique id of the payment
Has this payment been approved and ready for execution.
The purpose of the payment as a 4 letter iso-20022 code.see:https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets.
SALAPattern: ^[A-Z]{4}$PUT /payments/payments/{id} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 441
{
"description": "text",
"id": "text",
"purpose": "SALA",
"source": {
"type": "group",
"id": "text"
},
"target": {
"type": "contact",
"id": "text"
},
"approved": true,
"amount": {
"type": "LAND",
"amount": 1,
"currency": "text"
},
"execution": {
"type": "SEND",
"date": "2026-01-01T00:00:00.000Z",
"margin": 1
},
"final": {
"is_final": true,
"expected": "2026-01-01T00:00:00.000Z"
},
"attachments": [
{
"title": "text",
"id": "text",
"url": "text"
}
],
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}Successful response
{
"info": {
"status": "PENDING",
"credit": {
"currency": "text",
"amount": 1
},
"funding": {
"currency": "text",
"amount": 1,
"date": "2026-01-01T00:00:00.000Z"
},
"debit": {
"currency": "text",
"amount": 1
},
"rate": 1,
"fees": 1
},
"type": "payment",
"description": "text",
"id": "text",
"amount": {
"type": "LAND",
"amount": 1,
"currency": "text"
},
"approved": true,
"attachments": [
{
"title": "text",
"id": "text",
"url": "text"
}
],
"execution": {
"type": "SEND",
"date": "2026-01-01T00:00:00.000Z",
"margin": 1
},
"final": {
"is_final": true,
"expected": "2026-01-01T00:00:00.000Z"
},
"purpose": "SALA",
"source": {
"type": "text",
"id": "text"
},
"target": {
"type": "text",
"id": "text"
},
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}The Get Payment Details API provides a comprehensive view of the payment, including its status, amounts involved, and other relevant information. This API is crucial for developers needing to access detailed information about individual payments for auditing, tracking, or processing purposes.
The unique identifier for the payment instruction that you want to update (if none is provided, an ID will be assigned). Using an existing payment ID will update the pending payment.
Successful response
Set to payment, indicating the type of the object.
A brief note or remittance information provided as part of the payment.
The unique identifier for the payment.
Indicates whether the payment has been approved for processing.
The purpose of the payment, using a 4-letter ISO 20022 code (e.g., SALA for salary).
SALAPattern: ^[A-Z]{4}$GET /payments/payments/{id} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful response
{
"info": {
"status": "PENDING",
"credit": {
"currency": "text",
"amount": 1
},
"funding": {
"currency": "text",
"amount": 1,
"date": "2026-01-01T00:00:00.000Z"
},
"debit": {
"currency": "text",
"amount": 1
},
"rate": 1,
"fees": 1
},
"type": "payment",
"description": "text",
"id": "text",
"amount": {
"type": "LAND",
"amount": 1,
"currency": "text"
},
"approved": true,
"execution": {
"type": "SEND",
"date": "2026-01-01T00:00:00.000Z",
"margin": 1
},
"final": {
"is_final": true,
"expected": "2026-01-01T00:00:00.000Z"
},
"purpose": "SALA",
"source": {
"type": "text",
"id": "text"
},
"target": {
"type": "text",
"id": "text"
},
"attachments": [
{
"title": "text",
"id": "text",
"url": "text"
}
],
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}The Bulk Import Payment Instructions API allows developers to upload and process multiple payment instructions in a single request. This API is particularly useful for handling large volumes of payments efficiently, reducing the need for multiple API calls and streamlining the payment processing workflow.
Successful response
The timestamp indicating when the bulk import process was initiated. This value is essential for tracking the start time of the process and can be useful for logging and auditing purposes (ISO 8601 format, e.g., 2024-08-29T14:19:01.782Z).
The total number of payment instructions that are part of the bulk import. This number represents the entire set of instructions that need to be processed, giving an overview of the scale of the operation.
The number of payment instructions that are currently being processed. This count indicates how many instructions are in the middle of the processing pipeline at the moment the response is generated.
The number of payment instructions that have been successfully processed so far. This count provides insight into the progress made and how many instructions have been completed.
The number of payment instructions that have failed to process. This count is critical for error handling and understanding how many instructions encountered issues during processing.
The current status of the bulk import process ("QUEUED":The process is in a queue and has not started yet. "DONE":The process has finished).
POST /payments/payments/import HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 472
{
"items": [
{
"description": "text",
"id": "text",
"signature": "text",
"purpose": "SALA",
"source": {
"type": "group",
"id": "text"
},
"target": {
"type": "contact",
"id": "text"
},
"approved": true,
"amount": {
"type": "LAND",
"amount": 1,
"currency": "text"
},
"execution": {
"type": "SEND",
"date": "2026-01-01T00:00:00.000Z",
"margin": 1
},
"final": {
"is_final": true,
"expected": "2026-01-01T00:00:00.000Z"
},
"attachments": [
{
"title": "text",
"id": "text",
"url": "text"
}
],
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}Successful response
{
"started_at": "2026-01-01T00:00:00.000Z",
"total": 1,
"processing": 1,
"processed": 1,
"failed": 1,
"status": "QUEUED",
"progress": [
{
"id": "text",
"status": "text",
"row": "text",
"error": {}
}
]
}The Bulk Import Payment Instructions Status API is used to retrieve the status of a bulk import operation for payment instructions. This allows developers to monitor the progress and see how many instructions have been processed, failed, or are still in progress.
The unique identifier for the bulk import process (job_id) you want to check the status of.
Successful response
The unique identifier for the bulk import process (job_id).
TThe timestamp indicating when the bulk import process was initiated, formatted in ISO 8601 (e.g., 2024-08-29T14:19:01.782Z).
The timestamp indicating when the bulk import process was completed, formatted in ISO 8601 (e.g., 2024-08-29T14:40:58.959Z).
The number of payment instructions that have been successfully processed.
The total number of payment instructions that are part of the bulk import process.
The number of payment instructions that are currently being processed.
The number of payment instructions that have failed to process.
The current status of the bulk import process ("QUEUED":The import process is queued and waiting to start. "DONE":The import process has finished successfully).
GET /payments/payments/import/{job_id} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful response
{
"job_id": "text",
"started_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"processed": 1,
"total": 1,
"processing": 1,
"failed": 1,
"status": "QUEUED",
"progress": [
{
"row": 1,
"error": {
"error_info": {
"valid": true,
"warnings": [
{
"description": "text",
"properties": [
"text"
]
}
],
"errors": [
{
"description": "text",
"properties": [
"text"
]
}
]
},
"error_code": 1,
"error": "text",
"message": "text"
},
"status": "FAILED"
}
]
}Successful response
POST /payments/payments/list HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 665
{
"filters": {
"description": "text",
"id": [
"text"
],
"dates": {
"request": {
"until": "2026-01-01T00:00:00.000Z",
"from": "2026-01-01T00:00:00.000Z"
},
"funding": {
"until": "2026-01-01T00:00:00.000Z",
"from": "2026-01-01T00:00:00.000Z"
},
"execution": {
"until": "2026-01-01T00:00:00.000Z",
"from": "2026-01-01T00:00:00.000Z"
}
},
"amount": {
"type": "SEND"
},
"approved": true,
"final": true,
"deleted": true,
"has_issues": true,
"issues": [
"text"
],
"purpose": [
"text"
],
"payout_types": [
"text"
],
"source": {
"type": "text",
"id": "text"
},
"status": [
"text"
],
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"target": {
"type": "text",
"id": "text"
}
},
"paging": {
"skip": 1,
"take": 1
},
"sorting": {
"status": true,
"direction": "ASC"
}
}Successful response
{
"items": [
{
"info": {
"status": "PENDING",
"credit": {
"currency": "text",
"amount": 1
},
"funding": {
"currency": "text",
"amount": 1,
"date": "2026-01-01T00:00:00.000Z"
},
"debit": {
"currency": "text",
"amount": 1
},
"rate": 1,
"fees": 1
},
"type": "payment",
"description": "text",
"id": "text",
"amount": {
"type": "LAND",
"amount": 1,
"currency": "text"
},
"approved": true,
"execution": {
"type": "SEND",
"date": "2026-01-01T00:00:00.000Z",
"margin": 1
},
"final": {
"is_final": true,
"expected": "2026-01-01T00:00:00.000Z"
},
"purpose": "SALA",
"source": {
"type": "text",
"id": "text"
},
"target": {
"type": "text",
"id": "text"
},
"attachments": [
{
"title": "text",
"id": "text",
"url": "text"
}
],
"user_tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"paging": {
"skip": 1,
"take": 1
}
}The Execute Payment Instructions API isused to execute previously approved payment instructions. This API triggers the actual payment process based on the provided payment instruction IDs, allowing funds to be transferred to the designated beneficiaries.
The unique identifiers for the payment instructions that you want to execute.
Successful response
A brief description of the payment instruction.
The unique identifier for the payment instruction.
The purpose of the payment, typically represented as a 4-letter ISO 20022 code (e.g., "SALA" for salary).
The signature of the created payment request
Additional metadata in the form of key-value pairs, allowing for custom tagging and categorization of the payment.
POST /payments/payments/{id}/send HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful response
{
"description": "text",
"id": "text",
"amount": {
"type": "SEND",
"amount": 1,
"currency": "text"
},
"approved": null,
"execution": {
"date": "text",
"margin": 1
},
"final": {
"is_final": true,
"expected": true
},
"org_id": null,
"purpose": "text",
"signature": "text",
"source": {
"type": "text",
"id": "text"
},
"target": {
"type": "text",
"id": "text"
},
"user_tags": {}
}Last updated