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 must have an
approvedKYC status. - The user profile must be in an
activestatus. - The user profile risk assessment status must not be
risk_flagged(v1). This is not applicable in v2. - 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 List Cross-border Payout Recipients (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.
List Cross-border Payout Recipients 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: ••••••''
List Cross-border Payout Recipient 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 List Cross-border Payout Recipient Forms (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 Cross-border Payout Recipients (POST /users/wallets/payouts/remittances/recipients) to pass the updated fields.
Update Cross-border Payout Recipients 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 Cross-border Payout Recipients 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 Cross-border Payout Recipients (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 Cross-border Payout Recipient Statuses (PUT users/wallets/payouts/remittances/recipients/{id}/statuses). This API can also be used to deactivate or reactivate a recipient.
Update Cross-border Payout Recipient Statuses 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 Cross-border Payout Recipient Statuses 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