Manage cross-border recipients
Learn how to create and maintain beneficiary profiles to facilitate seamless cross-border payouts. Understand the necessary recipient details required by the payout network based on the target currency, country, and remittance mode.
Use Cases
- You want to implement a feature that will allow the user to see the list of recipients associated with their accounts.
- You want to implement a feature that will allow a user to update a recipient's details, following a change in the recipient form for the receiving country.
Prerequisites
- The user profile risk assessment status must not be
risk_flagged. - The user profile must be in an
activestatus. - The user must have an
approvedKYC or KYB status - The user account or wallet must be in an
activestatus. - At least one cross-border payout capability {
LOCAL, SWIFT} is enabled in your program. - At least one cross-border recipient has already been created or defined.
API Workflow
1
Retrieve all recipients associated with a user (sender)
Call the Get Remittance Recipient List (GET /users/wallets/payouts/remittances/recipients) to retrieve all the defined recipients associated with a user (sender). Each recipient can be identified by its recipient ID.
Get Remittance Recipient List request
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/recipients?page=1&records_per_page=100&recipient_type={{recipient_type}}' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••''Get Remittance Recipient List response
{
"pagination": {
"total_records": 70,
"records_per_page": 100,
"total_pages": 1,
"links": {
"self": "https://transactions-payouts-crossborder.uat.matchmove-beta.com/{{program_code}}/v2/users/wallets/payouts/remittances/recipients?page=1&recipient_type=INDIVIDUAL&records_per_page=100"
}
},
"data": [
{
"id": "9e100879d19249389b442bb8fc730677",
"receiving_institution_type": "BANK",
"recipient_type": "INDIVIDUAL",
"receiving_currency": "THB",
"recipient_country": "THA",
"status": "UPDATE_REQUIRED",
"created_by": "892c95e28d33d59b898986430a422aeb",
"created_at": "2025-12-08T17:42:03 +08:00",
"updated_by": "SYSTEM",
"updated_at": "2025-12-08T17:42:11 +08:00",
"deleted_by": "",
"deleted_at": "",
"user": {
"id": "892c95e28d33d59b898986430a422aeb",
"type": "BUSINESS"
},
"payment_rail": "LOCAL",
"additional_data": {
"purpose_of_payment": "Family Maintenance",
"user_recipient_relationship": "Aunty"
},
"address_details": {
"address_line_1": "123",
"address_line_2": "Thani",
"address_line_3": "Street",
"address_line_4": "",
"city": "Bangkok",
"country": "THA",
"nationality": "Thai",
"postal_code": "123456",
"state": "Bangkok"
},
"bank_details": {
"account_name": "Jane Smith",
"account_number": "123456677",
"account_type": "Savings Account",
"bank_id": "1280041c4a92449a8fe9aa35075113c4",
"bank_name": "AIA COMPANY LIMITED",
"code": "BOPITHMM"
},
"identification_details": {
"country_of_issue": "Virgin Islands",
"date_of_incorporation": "2024-08-22",
"expiry_date": "3001-10-20",
"identity_number": "uy0109x",
"identity_type": "Military Id",
"issue_date": "2001-10-20"
},
"user_information": {
"date_of_birth": "2023-05-29",
"email": "john.smith@matchmove.com",
"first_name": "John",
"gender": "Male",
"last_name": "Smith",
"middle_name": "Williams",
"mobile": "9522430905",
"mobile_country_code": "63",
"occupation": "General Worker",
"preferred_name": "John Smith"
}
},
..
]
}2
Updating remittance recipient details, due to a remittance form update
A remittance recipient, though created, cannot be used for a transaction unless it has been cleared of risk. Also, a remittance recipient cannot be used if not all of its required fields are up to date. Thus, we need to manage the various states that a recipient can go through.
Recipient Form Updates
Since the recipient forms are dependent on the remittance transaction regulatory requirements of any given region. When these requirements change, an existing recipient impacted by the change must also be updated before it can be used for a transaction.
If a recipient requires updating, its status will be changed to UPDATE_REQUIRED. It will only be reactivated again once the necessary changes are made to the recipient profile.
To get the updated requirements, the partner must call the Get Remittance Recipient Form (GET /users/wallets/payouts/remittances/recipients/forms) to reveal the new and updated fields. These new and updated fields must be filled up and the updates pushed to the recipient profile.
In this example, the recipient form, where a recipient was defined, has a field trading_name that was previously not mandatory. Then this recipient form was updated to require trading_name as a mandatory field.
Example remittance form change/update
{..
- "field_key": "trading_name",
- "field_label": "Trading Name",
- "field_type": "string",
- "is_mandatory": false, —> "is_mandatory": true
- "is_editable": true ..}
Call the Update Remittance Recipient (POST /users/wallets/payouts/remittances/recipients) to pass the updated fields.
Update Remittance Recipient request
curl --location --request PUT 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/recipients/<recipient_id>' \
--header 'X-Auth-User-ID: <user_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"recipient_data": {
"business_information" : {
"trading_name" : "XYZ Corp"
}
}
}'Update Remittance Recipient response
{
"id": "3795fb24fa81485ebf014206d2e1383c",
"receiving_institution_type": "BANK",
"recipient_type": "BUSINESS",
"receiving_currency": "EUR",
"recipient_country": "AND",
"status": "ACTIVE",
"created_by": "705392daffe8b3f554ee02f31979c114",
"created_at": "2025-08-12T18:36:17 +08:00",
"updated_by": "705392daffe8b3f554ee02f31979c114",
"updated_at": "2025-08-13T15:05:37 +08:00",
"deleted_by": "",
"deleted_at": "",
"user": {
"id": "705392daffe8b3f554ee02f31979c114",
"type": "BUSINESS"
},
"additional_data": {
"purpose_of_payment": "Donation or Gifts",
"user_recipient_relationship": ""
},
"address_details": {
"address_line_1": "123",
"address_line_2": "Grove St",
"address_line_3": "",
"address_line_4": "",
"city": "Andorra la Vella",
"country": "AND",
"postal_code": "12345",
"state": "Andorra"
},
"bank_details": {
"account_name": "Juan Smith",
"account_type": "Savings Account",
"bank_id": "c925e488e6734d0a9a55845bcaca28d3",
"bank_name": "ANDORRA BANC AGRICOL REIG S.A.",
"iban": "AD3456789012345678901234"
},
"business_information": {
"business_email": "contactus@xyz.com",
"registered_org_name": "XYZ Corp",
"registration_number": "",
"tax_id": "",
"trading_name": "XYZ Corp"
},
"identification_details": {
"country_of_issue": "",
"date_of_incorporation": "",
"expiry_date": "",
"identity_number": "",
"identity_type": "",
"issue_date": ""
},
"representative_info": {
"first_name": "Juan",
"last_name": "Smith",
"middle_name": "",
"mobile": "333333",
"mobile_country_code": "376",
"preferred_name": ""
}
}3
Ad hoc recipient information updates
In cases where a recipient's information requires an update that is not demanded by a remittance recipient form update, the update can still be pushed using the same Update Remittance Recipient (POST /users/wallets/payouts/remittances/recipients) method.
However, only the fields marked "is_editable": true are allowed to be updated.
If the information that the recipient wants to update is not marked as editable, then the only way to push those updates is through a new recipient creation. For this, we will need to delete the existing recipient and recreate it using the updated details.
We can delete an existing recipient using the Update Recipient Status (PUT users/wallets/payouts/remittances/recipients/{id}/statuses). This API can also be used to deactivate or reactivate a recipient.
Update Recipient Status request
curl --location --request PUT 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/recipients/{{recipient_id}}/statuses' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"status": "DELETE"
}'Update Recipient Status response
{
"id": "3795fb24fa81485ebf014206d2e1383c",
"message": "Recipient has been deleted successfully.",
"status": "DELETED",
"updated_by": "705392daffe8b3f554ee02f31979c114",
"updated_at": "2025-08-13T15:35:10 +08:00"
}
On this page
- Manage cross-border recipients