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

Get Beneficiary APIs

get

Get a beneficiary by idRef

Path parameters
idRefstringRequired
Responses
200

Response to /api/v1/beneficiary/{idRef}

application/json
aliasstringOptional
created_atstring · date-timeRequired
external_referencestringOptional
first_namestringOptional
idstring · uuidRequired
last_namestringOptional
organizationstringOptional
updated_atstring · date-timeOptional
get/api/v1/beneficiary/{idRef}
GET /api/v1/beneficiary/{idRef} HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/{idRef}

{
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "alias": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "external_reference": "text",
  "first_name": "text",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "last_name": "text",
  "organization": "text",
  "updated_at": "2026-01-01T00:00:00.000Z"
}
get

Get additional attributes for a beneficiary

Path parameters
idRefstringRequired
Responses
200

Response to /api/v1/beneficiary/{idRef}/additional-attributes

application/json
Other propertiesstringOptional
get/api/v1/beneficiary/{idRef}/additional-attributes
GET /api/v1/beneficiary/{idRef}/additional-attributes HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/{idRef}/additional-attributes

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}
get

Get contact account field specifications

Path parameters
identityReferencestringRequired
Responses
200

Response to /api/v1/fields/{identityReference}/contact-account

application/json
get/api/v1/fields/{identityReference}/contact-account
GET /api/v1/fields/{identityReference}/contact-account HTTP/1.1
Accept: */*
200

Response to /api/v1/fields/{identityReference}/contact-account

{
  "spec": {
    "ANY_ADDITIONAL_PROPERTY": {
      "field_groups": [
        {
          "fields": [
            {
              "additional_info": {
                "link": "text",
                "localized_text": "text"
              },
              "input": {
                "constraints": [
                  {
                    "key": "text",
                    "value": "text"
                  }
                ],
                "key": "text",
                "options": [
                  {
                    "key": "text",
                    "properties": {
                      "ANY_ADDITIONAL_PROPERTY": "text"
                    }
                  }
                ],
                "required_conditions": [
                  {
                    "depends_on": "text",
                    "selected_option": "text",
                    "selected_options": [
                      "text"
                    ],
                    "type": "text"
                  }
                ],
                "tags": [
                  "text"
                ],
                "type": "text"
              },
              "input_pattern": "text",
              "localized_hint": "text",
              "localized_name": "text",
              "option_decorations": [
                {
                  "key": "text",
                  "localized_name": "text"
                }
              ],
              "tags": [
                "text"
              ],
              "visibility_conditions": [
                {
                  "depends_on": "text",
                  "selected_option": "text",
                  "selected_options": [
                    "text"
                  ],
                  "type": "text"
                }
              ]
            }
          ],
          "localized_name": "text"
        }
      ],
      "field_order": [
        "text"
      ]
    }
  }
}
get

Get payment creation field specifications

Path parameters
identityReferencestringRequired
Query parameters
beneficiaryAccountIdOptionalstring · uuidOptional
Responses
200

Response to /api/v1/fields/{identityReference}/payment

application/json
get/api/v1/fields/{identityReference}/payment
GET /api/v1/fields/{identityReference}/payment HTTP/1.1
Accept: */*
200

Response to /api/v1/fields/{identityReference}/payment

{
  "spec": {
    "ANY_ADDITIONAL_PROPERTY": {
      "field_groups": [
        {
          "fields": [
            {
              "additional_info": {
                "link": "text",
                "localized_text": "text"
              },
              "input": {
                "constraints": [
                  {
                    "key": "text",
                    "value": "text"
                  }
                ],
                "key": "text",
                "options": [
                  {
                    "key": "text",
                    "properties": {
                      "ANY_ADDITIONAL_PROPERTY": "text"
                    }
                  }
                ],
                "required_conditions": [
                  {
                    "depends_on": "text",
                    "selected_option": "text",
                    "selected_options": [
                      "text"
                    ],
                    "type": "text"
                  }
                ],
                "tags": [
                  "text"
                ],
                "type": "text"
              },
              "input_pattern": "text",
              "localized_hint": "text",
              "localized_name": "text",
              "option_decorations": [
                {
                  "key": "text",
                  "localized_name": "text"
                }
              ],
              "tags": [
                "text"
              ],
              "visibility_conditions": [
                {
                  "depends_on": "text",
                  "selected_option": "text",
                  "selected_options": [
                    "text"
                  ],
                  "type": "text"
                }
              ]
            }
          ],
          "localized_name": "text"
        }
      ],
      "field_order": [
        "text"
      ]
    }
  }
}
get

Get addresses for a beneficiary

Path parameters
idRefstringRequired
Responses
200

Response to /api/v1/beneficiary/{idRef}/address

application/json
addressstringOptional
citystringOptional
countrystringOptional
created_atstring · date-timeOptional
idstring · uuidRequired
neighbourhoodstringOptional
post_codestringOptional
statestringOptional
updated_atstring · date-timeOptional
get/api/v1/beneficiary/{idRef}/address
GET /api/v1/beneficiary/{idRef}/address HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/{idRef}/address

[
  {
    "address": "text",
    "city": "text",
    "country": "text",
    "created_at": "2026-01-01T00:00:00.000Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "neighbourhood": "text",
    "post_code": "text",
    "state": "text",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
]
get

Get contacts for a beneficiary

Path parameters
idRefstringRequired
Responses
200

Response to /api/v1/beneficiary/{idRef}/contact

application/json
created_atstring · date-timeRequired
emailstringRequired
idstring · uuidRequired
mobile_numberstringRequired
mobile_prefixstringRequired
updated_atstring · date-timeOptional
get/api/v1/beneficiary/{idRef}/contact
GET /api/v1/beneficiary/{idRef}/contact HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/{idRef}/contact

[
  {
    "created_at": "2026-01-01T00:00:00.000Z",
    "email": "text",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "mobile_number": "text",
    "mobile_prefix": "text",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
]
get

Get all beneficiaries by identity

Path parameters
identityReferencestringRequired
Responses
200

Response to /api/v1/beneficiary/identity/{identityReference}/list

application/json

Details of a beneficiary with list of external and internal coordinates.

aliasstringOptional
contact_hash_liststring[]Optional
created_atstring · date-timeRequired
external_referencestringOptional
first_namestringOptional
idstring · uuidRequired
last_namestringOptional
organization_namestringOptional
updated_atstring · date-timeOptional
get/api/v1/beneficiary/identity/{identityReference}/list
GET /api/v1/beneficiary/identity/{identityReference}/list HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/identity/{identityReference}/list

[
  {
    "additional_fields": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "alias": "text",
    "beneficiary_internal_coordinates": [
      {
        "account_uuid": "123e4567-e89b-12d3-a456-426614174000",
        "currencies": [
          "text"
        ],
        "is_verified": true,
        "last_payment_date": "2026-01-01T00:00:00.000Z"
      }
    ],
    "contact_hash_list": [
      "text"
    ],
    "created_at": "2026-01-01T00:00:00.000Z",
    "dynamic_beneficiary_coords": [
      {
        "alias": "text",
        "bank_name": "text",
        "beneficiary_coordinate_id": "123e4567-e89b-12d3-a456-426614174000",
        "coordinates": {
          "aba": "text",
          "account_code": "text",
          "account_number": "text",
          "address": "text",
          "bank_code": "text",
          "bank_name": "text",
          "beneficiary_verification_type": "text",
          "bic": "text",
          "branch_code": "text",
          "bsb": "text",
          "city": "text",
          "country": "text",
          "country_code": "text",
          "curp": "text",
          "iban": "text",
          "ifsc": "text",
          "neighbourhood": "text",
          "post_code": "text",
          "purpose_code": "text",
          "rfc": "text",
          "sort_code": "text",
          "state": "text"
        },
        "currency": "text",
        "first_name": "text",
        "is_verified": true,
        "last_name": "text",
        "last_payment_date": "2026-01-01T00:00:00.000Z",
        "organization_name": "text",
        "payment_type": "text",
        "primary_coordinate_formats": [
          "text"
        ],
        "primary_coordinates": [
          "text"
        ]
      }
    ],
    "external_reference": "text",
    "first_name": "text",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "last_name": "text",
    "organization_name": "text",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
]
get

Get recently paid beneficiaries

Path parameters
identityReferencestringRequired
Responses
200

Response to /api/v1/beneficiary/identity/{identityReference}/payments

application/json
beneficiary_coordinate_idstring · uuidOptional

Beneficiary coordinate id related to this payment

beneficiary_idstring · uuidRequired

Beneficiary id related to this payment

created_atstring · date-timeRequired
payment_keystringRequired

A unique identifier payment

get/api/v1/beneficiary/identity/{identityReference}/payments
GET /api/v1/beneficiary/identity/{identityReference}/payments HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/identity/{identityReference}/payments

[
  {
    "beneficiary_coordinate_id": "123e4567-e89b-12d3-a456-426614174000",
    "beneficiary_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2026-01-01T00:00:00.000Z",
    "payment_key": "text"
  }
]
get

Get a beneficiary by idRef

Path parameters
identityReferencestringRequired
idRefstringRequired
Responses
200

Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}

application/json

Details of a beneficiary with list of external and internal coordinates.

aliasstringOptional
contact_hash_liststring[]Optional
created_atstring · date-timeRequired
external_referencestringOptional
first_namestringOptional
idstring · uuidRequired
last_namestringOptional
organization_namestringOptional
updated_atstring · date-timeOptional
get/api/v1/beneficiary/identity/{identityReference}/{idRef}
GET /api/v1/beneficiary/identity/{identityReference}/{idRef} HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}

{
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "alias": "text",
  "beneficiary_internal_coordinates": [
    {
      "account_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "currencies": [
        "text"
      ],
      "is_verified": true,
      "last_payment_date": "2026-01-01T00:00:00.000Z"
    }
  ],
  "contact_hash_list": [
    "text"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "dynamic_beneficiary_coords": [
    {
      "alias": "text",
      "bank_name": "text",
      "beneficiary_coordinate_id": "123e4567-e89b-12d3-a456-426614174000",
      "coordinates": {
        "aba": "text",
        "account_code": "text",
        "account_number": "text",
        "address": "text",
        "bank_code": "text",
        "bank_name": "text",
        "beneficiary_verification_type": "text",
        "bic": "text",
        "branch_code": "text",
        "bsb": "text",
        "city": "text",
        "country": "text",
        "country_code": "text",
        "curp": "text",
        "iban": "text",
        "ifsc": "text",
        "neighbourhood": "text",
        "post_code": "text",
        "purpose_code": "text",
        "rfc": "text",
        "sort_code": "text",
        "state": "text"
      },
      "currency": "text",
      "first_name": "text",
      "is_verified": true,
      "last_name": "text",
      "last_payment_date": "2026-01-01T00:00:00.000Z",
      "organization_name": "text",
      "payment_type": "text",
      "primary_coordinate_formats": [
        "text"
      ],
      "primary_coordinates": [
        "text"
      ]
    }
  ],
  "external_reference": "text",
  "first_name": "text",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "last_name": "text",
  "organization_name": "text",
  "updated_at": "2026-01-01T00:00:00.000Z"
}
get

Get a coordinate by id

Path parameters
idstring · uuidRequired
Responses
200

Response to /api/v1/beneficiary/coordinates/{id}

application/json
idstring · uuidRequired

A globally unique identifier for the beneficiary coordinates, generated on creation.

get/api/v1/beneficiary/coordinates/{id}
GET /api/v1/beneficiary/coordinates/{id} HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/coordinates/{id}

{
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "coordinates": {
    "acceptor": {
      "acquirer_id": "text",
      "facilitator_id": "text",
      "id": "text",
      "mcc": "text",
      "terminal_id": "text"
    },
    "banking": {
      "account_code": "text",
      "account_number": "text",
      "account_type": "text",
      "balance_account_number": "text",
      "bank_code": "text",
      "bic": "text",
      "bic_bank_code": "text",
      "bic_branch_code": "text",
      "bic_location_code": "text",
      "branch_code": "text",
      "country_code": "text",
      "currency": "text",
      "iban": "text",
      "national_id": "text",
      "owner_account_number": "text",
      "routing_code": "text"
    },
    "external": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "internal": {
      "account_id": "123e4567-e89b-12d3-a456-426614174000",
      "account_reference": "text",
      "card_id": "123e4567-e89b-12d3-a456-426614174000",
      "contact_account_id": "text",
      "currency_code": "text",
      "legacy_account_id": 1,
      "wallet_address": "text",
      "wallet_code": "text"
    },
    "reference": "text"
  },
  "entity": {
    "affiliation": "CUSTOMER",
    "aspects": [
      {
        "aspect": {},
        "identifier": "123e4567-e89b-12d3-a456-426614174000",
        "relation": "text"
      }
    ],
    "reference": "text",
    "type": "INDIVIDUAL"
  },
  "id": "123e4567-e89b-12d3-a456-426614174000"
}
get

Get coordinates for a beneficiary

Path parameters
idRefstringRequired
Responses
200

Response to /api/v1/beneficiary/{idRef}/coordinates

application/json
idstring · uuidRequired

A globally unique identifier for the account, generated on creation.

tagsstring[]Optional

Strictly optional application-scoped tags for the account coordinates.

get/api/v1/beneficiary/{idRef}/coordinates
GET /api/v1/beneficiary/{idRef}/coordinates HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/{idRef}/coordinates

[
  {
    "coordinates": {
      "acceptor": {
        "acquirer_id": "text",
        "facilitator_id": "text",
        "id": "text",
        "mcc": "text",
        "terminal_id": "text"
      },
      "banking": {
        "account_code": "text",
        "account_number": "text",
        "account_type": "text",
        "balance_account_number": "text",
        "bank_code": "text",
        "bic": "text",
        "bic_bank_code": "text",
        "bic_branch_code": "text",
        "bic_location_code": "text",
        "branch_code": "text",
        "country_code": "text",
        "currency": "text",
        "iban": "text",
        "national_id": "text",
        "owner_account_number": "text",
        "routing_code": "text"
      },
      "external": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "internal": {
        "account_id": "123e4567-e89b-12d3-a456-426614174000",
        "account_reference": "text",
        "card_id": "123e4567-e89b-12d3-a456-426614174000",
        "contact_account_id": "text",
        "currency_code": "text",
        "legacy_account_id": 1,
        "wallet_address": "text",
        "wallet_code": "text"
      },
      "reference": "text"
    },
    "external": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "tags": [
      "text"
    ]
  }
]
get

Resend verification OTP to a beneficiary

Path parameters
identityReferencestringRequired
verificationUuidstring · uuidRequired
Responses
200

Response to /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}

application/json
beneficiary_coordinate_uuidstring · uuidRequired
beneficiary_uuidstring · uuidRequired
statusstring · enumRequiredPossible values:
verification_uuidstring · uuidRequired
get/api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}
GET /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid} HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}

{
  "beneficiary_coordinate_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "beneficiary_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "status": "VERIFIED",
  "verification_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
get

Send verification OTP to a beneficiary

Path parameters
identityReferencestringRequired
idRefstringRequired
coordinateIdstring · uuidRequired
Responses
200

Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification

application/json
beneficiary_coordinate_uuidstring · uuidRequired
beneficiary_uuidstring · uuidRequired
statusstring · enumRequiredPossible values:
verification_uuidstring · uuidRequired
get/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification
GET /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification HTTP/1.1
Accept: */*
200

Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification

{
  "beneficiary_coordinate_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "beneficiary_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "status": "VERIFIED",
  "verification_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
PreviousBeneficiary Management APIs

Last updated