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

Beneficiary Management APIs

post

Create a beneficiary

Body
aliasstringOptional
external_referencestringOptional
first_namestringOptional
identity_referencestringOptional
last_namestringOptional
organization_namestringOptional
Responses
200

Response to /api/v1/beneficiary

application/json
aliasstringOptional
created_atstring · date-timeRequired
external_referencestringOptional
first_namestringOptional
idstring · uuidRequired
last_namestringOptional
organizationstringOptional
updated_atstring · date-timeOptional
post/api/v1/beneficiary
POST /api/v1/beneficiary HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 1201

{
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "addresses": [
    {
      "address": "text",
      "city": "text",
      "country": "text",
      "neighbourhood": "text",
      "post_code": "text",
      "state": "text"
    }
  ],
  "alias": "text",
  "contacts": [
    {
      "email": "text",
      "mobile_number": "text",
      "mobile_prefix": "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"
  },
  "external_reference": "text",
  "first_name": "text",
  "identity_reference": "text",
  "last_name": "text",
  "organization_name": "text"
}
200

Response to /api/v1/beneficiary

{
  "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 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"
}
post

Get additional attributes for a coordinate

Path parameters
identityReferencestringRequired
idRefstringRequired
Body
aliasstringOptional
currencystringRequired
first_namestringOptional
last_namestringOptional
organization_namestringOptional
Responses
200

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

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
post/api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates
POST /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 556

{
  "alias": "text",
  "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",
    "secondary_identification": "text",
    "sort_code": "text",
    "state": "text"
  },
  "currency": "text",
  "first_name": "text",
  "last_name": "text",
  "organization_name": "text"
}
200

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

{
  "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"
}
patch

Update a coordinate for a beneficiary

Path parameters
identityReferencestringRequired
idRefstringRequired
coordinateIdstring · uuidRequired
Body
aliasstringOptional
currencystringRequired
first_namestringOptional
last_namestringOptional
organization_namestringOptional
Responses
200

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

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
patch/api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates/{coordinateId}
PATCH /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates/{coordinateId} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 556

{
  "alias": "text",
  "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",
    "secondary_identification": "text",
    "sort_code": "text",
    "state": "text"
  },
  "currency": "text",
  "first_name": "text",
  "last_name": "text",
  "organization_name": "text"
}
200

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

{
  "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"
}
post

Create beneficiary with identity

Path parameters
identityReferencestringRequired
Body
aliasstringOptional
external_referencestringOptional
first_namestringOptional
identity_referencestringOptional
last_namestringOptional
organization_namestringOptional
Responses
200

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

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
post/api/v1/beneficiary/identity/{identityReference}/
POST /api/v1/beneficiary/identity/{identityReference}/ HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 1201

{
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "addresses": [
    {
      "address": "text",
      "city": "text",
      "country": "text",
      "neighbourhood": "text",
      "post_code": "text",
      "state": "text"
    }
  ],
  "alias": "text",
  "contacts": [
    {
      "email": "text",
      "mobile_number": "text",
      "mobile_prefix": "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"
  },
  "external_reference": "text",
  "first_name": "text",
  "identity_reference": "text",
  "last_name": "text",
  "organization_name": "text"
}
200

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

{
  "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"
}
post

Sync beneficiaries

Path parameters
identityReferencestringRequired
Body

Request to sync contacts of a customer phonebook with list of beneficiaries.

contact_hashesstring[]Required

The contact hashes of a customer phonebook that will be synced.

Responses
200

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

No content
post/api/v1/beneficiary/identity/{identityReference}/sync
POST /api/v1/beneficiary/identity/{identityReference}/sync HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "contact_hashes": [
    "text"
  ]
}
200

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

No content
post

Verify OTP for a beneficiary

Path parameters
identityReferencestringRequired
verificationUuidstring · uuidRequired
Body
otpstringRequired

One time passcode for beneficiary coordinate verification

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
post/api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}
POST /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "otp": "text"
}
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"
}
patch

Update beneficiary with identity

Path parameters
identityReferencestringRequired
idRefstringRequired
Body
aliasstringOptional
external_referencestringOptional
first_namestringOptional
identity_referencestringOptional
last_namestringOptional
organization_namestringOptional
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
patch/api/v1/beneficiary/identity/{identityReference}/{idRef}
PATCH /api/v1/beneficiary/identity/{identityReference}/{idRef} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 1201

{
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "addresses": [
    {
      "address": "text",
      "city": "text",
      "country": "text",
      "neighbourhood": "text",
      "post_code": "text",
      "state": "text"
    }
  ],
  "alias": "text",
  "contacts": [
    {
      "email": "text",
      "mobile_number": "text",
      "mobile_prefix": "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"
  },
  "external_reference": "text",
  "first_name": "text",
  "identity_reference": "text",
  "last_name": "text",
  "organization_name": "text"
}
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"
}
post

Add a coordinate to a beneficiary

Path parameters
identityReferencestringRequired
idRefstringRequired
Body

A standard way of transmitting account coordinates between services.

referencestringOptional
Responses
200

Response to /api/v1/beneficiary/identity/{identityReference}/{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.

post/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/
POST /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/ HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 796

{
  "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"
}
200

Response to /api/v1/beneficiary/identity/{identityReference}/{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"
  ]
}
delete

Delete a coordinate from a beneficiary

Path parameters
identityReferencestringRequired
idRefstringRequired
coordinateIdstring · uuidRequired
Responses
200

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

No content
delete/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}
DELETE /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId} HTTP/1.1
Accept: */*
200

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

No content
post

Add a category to a coordinate

Path parameters
identityReferencestringRequired
idRefstringRequired
coordinateIdstring · uuidRequired
categorystringRequired
Responses
200

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

No content
post/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/category/{category}
POST /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/category/{category} HTTP/1.1
Accept: */*
200

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

No content
delete

Delete a beneficiary

Path parameters
idRefstringRequired
Responses
200

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

No content
delete/api/v1/beneficiary/{idRef}
DELETE /api/v1/beneficiary/{idRef} HTTP/1.1
Accept: */*
200

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

No content
patch

Update a beneficiary

Path parameters
idRefstringRequired
Body
aliasstringOptional
external_referencestringOptional
first_namestringOptional
identity_referencestringOptional
last_namestringOptional
organization_namestringOptional
Responses
200

Response to /api/v1/beneficiary/{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
patch/api/v1/beneficiary/{idRef}
PATCH /api/v1/beneficiary/{idRef} HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 1201

{
  "additional_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "addresses": [
    {
      "address": "text",
      "city": "text",
      "country": "text",
      "neighbourhood": "text",
      "post_code": "text",
      "state": "text"
    }
  ],
  "alias": "text",
  "contacts": [
    {
      "email": "text",
      "mobile_number": "text",
      "mobile_prefix": "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"
  },
  "external_reference": "text",
  "first_name": "text",
  "identity_reference": "text",
  "last_name": "text",
  "organization_name": "text"
}
200

Response to /api/v1/beneficiary/{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"
}
post

Add an address to a beneficiary

Path parameters
idRefstringRequired
Body
addressstringRequired
citystringRequired
countrystringRequired
neighbourhoodstringRequired
post_codestringRequired
statestringRequired
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
post/api/v1/beneficiary/{idRef}/address
POST /api/v1/beneficiary/{idRef}/address HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "address": "text",
  "city": "text",
  "country": "text",
  "neighbourhood": "text",
  "post_code": "text",
  "state": "text"
}
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"
}
post

Validate payment creation

Path parameters
identityReferencestringRequired
Body
beneficiary_account_uuidstring · uuidRequired
beneficiary_uuidstring · uuidRequired
currencystringRequired
Responses
200

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

application/json
post/api/v1/fields/{identityReference}/payment/validate
POST /api/v1/fields/{identityReference}/payment/validate HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 187

{
  "beneficiary_account_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "beneficiary_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "currency": "text",
  "fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
200

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

{
  "violations": [
    {
      "key": "text",
      "localized_message": "text"
    }
  ]
}
post

Interrupt the synchronization process

Responses
200

Response to /api/v1/sync/interrupt

No content
post/api/v1/sync/interrupt
POST /api/v1/sync/interrupt HTTP/1.1
Accept: */*
200

Response to /api/v1/sync/interrupt

No content
post

Manually initiate the synchronization process

Responses
200

Response to /api/v1/sync/manual

No content
post/api/v1/sync/manual
POST /api/v1/sync/manual HTTP/1.1
Accept: */*
200

Response to /api/v1/sync/manual

No content
PreviousAccount Wallets APIs
NextGet Beneficiary APIs

Last updated