Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

beneficiaries

Bulk Import Beneficiary

post
/payments/beneficiaries/import

The Bulk Import Beneficiary API used to perform a bulk import of beneficiary data. This API allows developers to import multiple beneficiaries in a single request, managing their bank details and personal information through a batch processing job.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
update_paymentsbooleanOptional

When set to true, will update the beneficiary details for all pending payments created for the same beneficiary.

signaturestringOptional

A string field, used for digital signatures or verification purposes.

Responses
200

Successful response

application/json
post/payments/beneficiaries/import
POST /payments/beneficiaries/import HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 174

{
  "update_payments": true,
  "signature": "text",
  "items": [
    {
      "id": "text",
      "entity_type": "INDIVIDUAL",
      "bank_details": {
        "account_country": "text",
        "account_currency": "text"
      },
      "entity": {}
    }
  ]
}
200

Successful response

Get Import Beneficiary Status

get
/payments/beneficiaries/import/{job_id}

The Bulk Import Beneficiary Status API used to retrieve the status of a bulk import operation for beneficiaries. This API allows developers to check the status of a bulk import operation for beneficiaries, including details on any errors encountered during the process.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
job_idstringRequired

The unique identifier for the bulk import job. This parameter is used to fetch the status of the specific import job.

Example: TPy4DcQATiqZRRzTMEXt2Q
Responses
200

Successful response

application/json
job_idstringOptional

The unique identifier for the bulk import job.

started_atstring · date-timeOptional

The date and time when the bulk import started.

completed_atstring · date-timeOptional

The date and time when the bulk import completed.

processedintegerOptional

The number of records that have been processed.

totalintegerOptional

The total number of records in the import.

processingintegerOptional

The number of records currently being processed.

failedintegerOptional

The number of records that failed to import.

statusstring · enumOptional

The overall status of the bulk import (e.g., DONE, IN_PROGRESS).

Possible values:
get/payments/beneficiaries/import/{job_id}
GET /payments/beneficiaries/import/{job_id} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "completed_at": "2024-03-04T10:56:53.396911923Z",
  "processed": 2,
  "total": 3,
  "job_id": "TPy4DcQATiqZRRzTMEXt2Q",
  "started_at": "2024-03-04T10:56:51.126587470Z",
  "processing": 0,
  "progress": [
    {
      "row": 0,
      "error": {
        "error_info": {
          "valid": false,
          "warnings": [],
          "errors": [
            {
              "description": "Missing property bank_name",
              "properties": [
                "$.bank_details"
              ]
            }
          ]
        },
        "error_code": 422,
        "error": "unprocessable_entity",
        "message": "Payload object is invalid"
      },
      "status": "FAILED"
    },
    {
      "row": 1,
      "status": "SUCCESS"
    },
    {
      "row": 2,
      "status": "SUCCESS"
    }
  ],
  "failed": 1,
  "status": "DONE"
}

Bulk Validate Beneficiary

post
/payments/beneficiaries/validate

The Bulk Validate Beneficiary API is used to perform validations on multiple beneficiaries at once. It allows developers to validate multiple beneficiaries in a single request. This API is crucial for ensuring that the beneficiary information provided is correct and adheres to the required standards before proceeding with further operations such as payments or onboarding.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
Responses
200

Successful response

application/json
post/payments/beneficiaries/validate
POST /payments/beneficiaries/validate HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "items": [
    {
      "entity_type": "INDIVIDUAL",
      "bank_details": {
        "account_country": "text",
        "account_currency": "text"
      },
      "entity": {}
    }
  ]
}
200

Successful response

{
  "valid": [
    {
      "entity_type": "INDIVIDUAL",
      "currency": "text",
      "country": "text"
    }
  ],
  "invalid": [
    {
      "entity_type": "INDIVIDUAL",
      "currency": "text",
      "country": "text",
      "issues": [
        {
          "field": "text",
          "message": "text"
        }
      ]
    }
  ],
  "totals": {
    "valid": 1,
    "count": 1,
    "schemas": 1,
    "invalid": 1
  }
}

standalone.api.beneficiary.collect.link

get
/payments/beneficiaries/{id}/collect
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

id of beneficiary to edit, if does not exist will be created

Query parameters
countrystringOptional

2 letter ISO country code

Pattern: ^[A-Z]{2}$
currencystringOptional

3 letter ISO currency code

Pattern: ^[A-Z]{3}$
entity_typestring · enumOptional

entity_type

Default: INDIVIDUALPossible values:
Responses
200

Successful response

application/json
idstringOptional

Beneficiary id

countrystringOptional

2 letter ISO country code

Pattern: ^[A-Z]{2}$
currencystringOptional

3 letter ISO currency code

Pattern: ^[A-Z]{3}$
entity_typestring · enumOptionalDefault: INDIVIDUALPossible values:
expiresstring · date-timeOptional

time when this link will expire

urlstringOptional

the link to redirect the user to

get/payments/beneficiaries/{id}/collect
GET /payments/beneficiaries/{id}/collect HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "id": "text",
  "country": "text",
  "currency": "text",
  "entity_type": "INDIVIDUAL",
  "expires": "2026-01-01T00:00:00.000Z",
  "url": "text"
}

Update Beneficiary Details

put
/payments/beneficiaries/{id}

The Update Beneficiary Details API is used to modify the details of an existing beneficiary. It allows developers to update the details of an existing beneficiary. This API is crucial for maintaining accurate and up-to-date beneficiary information, which is essential for smooth payment processing and compliance with financial regulations.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

the unique id of the beneficiary

Body
namestringOptional

A custom name to apply to beneficiary.

entity_typestring · enumOptional

The type of entity, e.g., INDIVIDUAL or BUSINESS.

Default: INDIVIDUALPossible values:
countrystring · enumRequired

The country code (ISO 3166-1 alpha-2) where the bank account is held.

Pattern: ^[A-Z]{2,2}$Possible values:
currencystring · enumRequired

The currency code (ISO 4217) of the bank account.

Pattern: ^[A-Z]{3,3}$Possible values:
entityobjectRequired

An object containing the beneficiary’s personal or business information.

bank_detailsobjectRequired

An object containing the beneficiary’s bank details.

Responses
200

Successful response

application/json
put/payments/beneficiaries/{id}
PUT /payments/beneficiaries/{id} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 151

{
  "name": "text",
  "entity_type": "INDIVIDUAL",
  "country": "AF",
  "currency": "AED",
  "user_tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "entity": {},
  "bank_details": {}
}
200

Successful response

Get Beneficiary Details

get
/payments/beneficiaries/{id}

The Get Beneficiary Details API is used to retrieve all the details associated with a specific beneficiary, identified by their unique beneficiary_id. It allows developers to retrieve detailed information about a specific beneficiary. This API is essential for obtaining the latest data on a beneficiary, which can be used for review, compliance, and processing purposes.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired

The unique identifier of the beneficiary whose details are being retrieved.

Responses
200

Successful response

application/json
namestringOptional

Display name of beneficiary

typestring · enumOptional

The legal type of the entity, e.g., contact.

Possible values:
idstringOptional

The unique identifier of the beneficiary.

bank_detailsobjectOptional

An object containing the beneficiary’s bank details.

entityobjectOptional

An object containing the beneficiary’s personal or business information.

entity_typestring · enumOptional

The type of entity, e.g., INDIVIDUAL or BUSINESS.

Possible values:
currencystringOptional

The currency code (ISO 4217) of the bank account.

statusstring · enumOptional

The current status of the beneficiary

Possible values:
activebooleanOptional

true when the beneficiary is active for payments

get/payments/beneficiaries/{id}
GET /payments/beneficiaries/{id} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "name": "text",
  "type": "contact",
  "id": "text",
  "bank_details": {},
  "entity": {},
  "entity_type": "INDIVIDUAL",
  "currency": "text",
  "status": "ACTIVE",
  "active": true,
  "user_tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "payments": {
    "total": 1,
    "next": {
      "date": "2026-01-01T00:00:00.000Z",
      "amount": 1,
      "currency": "text"
    },
    "last": {
      "date": "2026-01-01T00:00:00.000Z",
      "amount": 1,
      "currency": "text"
    },
    "history": {
      "total": 1,
      "amount": 1
    }
  },
  "issues": [
    {
      "description": "text",
      "hint": "text",
      "action": "text",
      "code": "text",
      "severity": "ERROR"
    }
  ]
}

Create Beneficiary

post
/payments/beneficiaries

The Create A Beneficiary API is used to create a beneficiary on the platform. This API allows developers to create a new beneficiary within an account. Once registered(The beneficiary ID returned upon successful creation), the beneficiary ID can be used to send payment instructions. This API is essential for setting up beneficiaries for subsequent payment transactions.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
namestringOptional

A custom display name for the beneficiary.

idstringOptional

The beneficiary ID serves as the unique identifier for this beneficiary on the platform.

entity_typestring · enumOptional

The beneficiary’s type, either BUSINESS or INDIVIDUAL.

Default: INDIVIDUALPossible values:
countrystring · enumRequired

The Bank country code (2-letter ISO 3166-2 country code).

Pattern: ^[A-Z]{2,2}$Possible values:
currencystring · enumRequired

The Account currency (3-letter ISO 4217 currency code).

Pattern: ^[A-Z]{3,3}$Possible values:
entityobjectRequired

The entity object contains the details of the beneficiary, such as name, address, and other personal or business details.

bank_detailsobjectRequired

The bank details object contains information about the beneficiary’s bank account, including account number, bank code, and bank name.

Responses
200

Successful response

application/json
post/payments/beneficiaries
POST /payments/beneficiaries HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "name": "text",
  "id": "text",
  "entity_type": "INDIVIDUAL",
  "country": "AF",
  "currency": "AED",
  "user_tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "entity": {},
  "bank_details": {}
}
200

Successful response

Get Beneficiaries List

get
/payments/beneficiaries

The Get Beneficiaries List API is used to fetch a list of all beneficiaries associated with an account. It allows developers to retrieve a list of all beneficiaries associated with an account. This API is essential for managing and reviewing the beneficiaries that have been created, enabling users to access comprehensive information about each beneficiary.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
countryany ofOptional

Filter the beneficiaries by the country code (2-letter ISO 3166-2 country code).

Pattern: /^[A-Z]{2}$/
stringOptional
or
string[]Optional
currencyany ofOptional

Filter beneficiaries by the currency code (3-letter ISO 4217 currency code).

Pattern: /^[A-Z]{3}$/
stringOptional
or
string[]Optional
idany ofOptional

The unique identifier of the beneficiary.

stringOptional
or
string[]Optional
ownerany ofOptional

owner

stringOptional
or
string[]Optional
skipintegerOptional

The number of items to skip from the result set (e.g., ?skip=3).

Default: 0
takeintegerOptional

The maximum number of items to return in the result set (e.g., ?take=50).

Default: 50
Responses
200

Successful response

application/json
get/payments/beneficiaries
GET /payments/beneficiaries HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

{
  "facets": {
    "countries": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "currencies": {
      "ANY_ADDITIONAL_PROPERTY": 1
    },
    "user_tags": {
      "ANY_ADDITIONAL_PROPERTY": 1
    }
  },
  "items": [
    {
      "name": null,
      "type": "contact",
      "id": "text",
      "entity_type": "INDIVIDUAL",
      "account_country": "text",
      "currency": "text",
      "active": true,
      "status": "ACTIVE",
      "user_tags": {}
    }
  ],
  "paging": {
    "skip": 1,
    "take": 50,
    "total": 1
  }
}

Get Schema Information

get
/payments/beneficiaries/schema/{type}/{country}/{currency}

The Get Schema Information API is used to retrieve the specific schema requirements for beneficiaries, which may vary depending on factors like the beneficiary’s country, entity type (e.g., Individual, Business), and other relevant attributes. This API allows developers to retrieve schema information for beneficiaries, providing details on the required fields and structure for different types of beneficiaries based on country, entity type, and other parameters. This API is essential for understanding the data requirements when creating or updating beneficiaries.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
countrystringRequired

The 2 letter ISO country code of the target bank.

Pattern: ^[A-Z]{2,2}$
currencystringRequired

The 3 letter ISO code of the target bank account currency.

Pattern: ^[A-Z]{3,3}$
typestring · enumRequired

The type of beneficiary for which to retrieve schema information, either INDIVIDUAL or BUSINESS.

Default: INDIVIDUALPossible values:
Query parameters
entity_countrystringOptional

The 2 letter ISO code of the target beneficiary country (e.g., ?entity_country=US).

Pattern: ^[A-Z]{2,2}$
Responses
200

Successful response

application/json
get/payments/beneficiaries/schema/{type}/{country}/{currency}
GET /payments/beneficiaries/schema/{type}/{country}/{currency} HTTP/1.1
Host: api.cust1.papaya-sandbox.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful response

Last updated