Perform a cross-border payment using an existing beneficiary
Learn the standard process for executing a cross-border transfer to a saved beneficiary profile. This guide shows you how to use a previously generated quote to send funds to a known recipient.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to execute a cross-border payment transaction to a defined recipient.
- You want to implement a feature that will allow individual users to perform cross-border payments to defined individual recipients (C2C remittance mode).
- You want to implement a feature that will allow business users to perform cross-border payments to defined individual recipients (B2C remittance mode).
- You want to implement a feature that will allow business users to perform cross-border payments to defined business recipients (B2B remittance mode).
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. - The user's virtual account must be in an
activestatus. - The user account's current
deduct_limitsandtransfer_out_limitsmust have enough buffer to accommodate the incoming debit amount. - At least one cross-border payout capability {
LOCAL, SWIFT} is enabled in your program. - The user account must have a balance that is equal to or higher than the payment amount.
- A valid recipient must have already been defined and must be in an
activatedstatus. - The selected recipient ID of the individual or business to whom the user wants to send funds.
- The selected quotation ID of the remittance quotation that the user wishes to use to send funds.
- The quotation and quotation ID are still active and have not yet expired before initiating the payment transaction.
API Workflow
1
Initiate a remittance transaction (with a recipient ID)
Before initiating a new remittance transaction, the sender must read and agree to the Remittance Terms of Service (TOS).
A link/view to the full terms and conditions page, along with a checkbox requiring confirmation of acceptance, must be presented in the application.
This must be done every time a new remittance transaction is about to be sent. The TOS acceptance timestamp and details must be recorded, and the details sent in the Send Remittance Transaction request.
Call the Send Remittance Transaction (POST /users/wallets/payouts/remittances/transactions) and pass the selected recipient ID and quotation ID.
Send Remittance Transaction API-related field enumerations:
user_recipient_relationshipallowed values are listed in the Mobile Country Code Enumeration (GET /users/enumerations/mobile_country_code).user_source_of_incomeallowed values are listed in the Source of Income Enumeration (GET /users/enumerations/main_income_source).user_occupationallowed values are listed in the Occupation Enumeration (GET /users/enumerations/occupations).
Send Remittance Transaction request (with quotation ID and recipient ID)
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"quote_id": "CVEMKp0MwkzM3gTN2cTMtUFRTVVTNd0Ut8UVRB",
"recipient_id": "f3dc5d8578a14603bab94f51943a53a3",
"user_recipient_relationship": "FATHER",
"user_source_of_income":"SALARY",
"tos_acceptance": {
"date": "2023-07-23T10:59:12+08:00",
"ip": "8.8.8.8",
"service_agreement": "string",
"user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1",
"device_id": "string"
},
"remarks": "Remittance comments here"
}'Send Remittance Transaction response (with quotation ID and recipient ID)
{
"id": "OVERBt0NwEDN3gTN2cTMtUFRTVVTNd0Ut4EWUB",
"status": "INITIATED",
"sub_status": "TRANSACTION_INITIATED",
"message": "Request received, processing started",
"source": [],
"user": {
"id": "1d2f696095bfe563058484b66d0a25fa",
"email": "johnsmith@matchmove.com",
"mobile_country_code": "91",
"mobile": "8054042741",
"country": "SGP",
"currency": "USD",
"type": "INDIVIDUAL"
},
"recipient": {
"id": "f3dc5d8578a14603bab94f51943a53a3",
"country": "USA",
"currency": "USD",
"type": "INDIVIDUAL"
},
"receiving_institution": {
"receiving_institution_type": "BANK",
"receiving_institution": "1ST SECURITY BANK OF WASHINGTON",
"receiving_institution_code": "123456789",
"account_name": "Steven Smith",
"account_number": "2988638169",
"account_type": "Savings Account"
},
"quote": {
"id": "CVEMKp0MwkzM3gTN2cTMtUFRTVVTNd0Ut8UVRB",
"type": "REVERSE",
"status": "CONFIRMED",
"fees": {
"included": false,
"fixed_amount": {
"currency": "USD",
"amount": "6.00"
},
"percentage_value": "0.250000000",
"percentage_amount": {
"currency": "USD",
"amount": "0.75"
},
"total": {
"currency": "USD",
"amount": "6.75"
},
"details": {
"platform_charge": {
"fixed_amount": {
"currency": "USD",
"amount": "5.00"
},
"percentage_value": "0.050000000",
"percentage_amount": {
"currency": "USD",
"amount": "0.15"
},
"total": {
"currency": "USD",
"amount": "5.15"
}
},
"markup": {
"program": {
"fixed_amount": {
"currency": "USD",
"amount": "1.00"
},
"percentage_value": "0.200000000",
"percentage_amount": {
"currency": "USD",
"amount": "0.60"
},
"total": {
"currency": "USD",
"amount": "1.60"
}
},
"total_markup": {
"fixed_amount": {
"currency": "USD",
"amount": "1.00"
},
"percentage_value": "0.200000000",
"percentage_amount": {
"currency": "USD",
"amount": "0.60"
}
}
}
}
},
"fx_rate": {
"value": "1.000000000",
"details": {
"platform_rate": "1.000000000",
"markup": {
"partner": "0.000000000",
"total": "0.000000000"
},
"net_markup": "0.000000000"
}
}
},
"charged_amount": {
"currency": "USD",
"amount": "306.75"
},
"converted_amount": {
"currency": "USD",
"amount": "300.00"
},
"recipient_amount": {
"currency": "USD",
"amount": "300.00"
},
"additional_data": {
"purpose_of_payment": "Family Maintenance",
"user_occupation": "",
"user_recipient_relationship": "Father",
"user_source_of_income": "Salary"
},
"tos": {
"tos_acceptance_date": "2023-07-23 02:59:12",
"tos_acceptance_device_id": "string",
"tos_acceptance_ip": "8.8.8.8",
"tos_acceptance_user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1",
"tos_acceptance_service_agreement": "string"
},
"remarks": "Any String",
"created_by": "1d2f696095bfe563058484b66d0a25fa",
"created_at": "2025-12-16T16:35:07 +08:00",
"updated_at": "2025-12-16T16:35:07 +08:00"
}The initiated remittance transaction will be set to the INITIATED status upon transaction confirmation, and this transaction will be queued for processing.
2
[SWIFT] Upload supplementary documents for high-value transactions
For SWIFT cross-border payments, a supporting document such as an invoice will be mandatory when:
- the transfer amount is greater than the review threshold*; and,
- the document requirement is enabled for selected transfer mode: (
user_typetorecipient_type) combination
*review threshold — is not a fixed value, it may adjust following compliance and risk reviews.
This requirement will block the processing of the transaction until the requirement is satisfied.
An additional indicator field will be added in the payment response for transaction amounts that have breached the threshold.
Failure to upload the required document within the quote expiry period will move the transaction state to EXPIRED and remove the transaction from the processing queue.
Send Remittance Transaction response (with quotation ID and recipient ID) with high-value transaction amount
{
"id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB",
"status": "INITIATED",
"sub_status": "DOCUMENT_REQUIRED",
"document_required_types": [
"INVOICE"
],
"document_requirements": {
"types": [
"INVOICE"
],
"accepted_formats": [
"pdf",
"jpg",
"png"
],
"max_file_size": "5MB"
},
"message": "Documents are required for this high-value transfer. Upload and confirm to proceed.",
"source": [],
"user": {
"id": "7b61722fb9f94a232a6dbe5df53d6d49",
"email": "testqa0711122023@matchmove.com",
"mobile_country_code": "65",
"mobile": "2076071232",
"country": "SGP",
"currency": "USD",
"type": "INDIVIDUAL"
},
"recipient": {
"id": "3fe6e9ab35354e4a9cbd9429dcfd9560",
"country": "USA",
"currency": "USD",
"type": "INDIVIDUAL"
},
"receiving_institution": {
"receiving_institution_type": "BANK",
"receiving_institution": "1ST SECURITY BANK OF WASHINGTON",
"receiving_institution_code": "123456789",
"account_name": "Steven Smith",
"account_number": "2118639169",
"account_type": "Savings Account"
},
"quote": {
"id": "Sh1UNlzN4ETO1kTN2cTMtUFRTVVTNd0Ut8UVRB",
"type": "FORWARD",
"status": "CONFIRMED",
"fees": {
"included": false,
"fixed_amount": {
"currency": "USD",
"amount": "79.00"
},
"percentage_value": "0.150000000",
"percentage_amount": {
"currency": "USD",
"amount": "0.23"
},
"total": {
"currency": "USD",
"amount": "79.23"
},
"details": {
"platform_charge": {
"fixed_amount": {
"currency": "USD",
"amount": "76.50"
},
"percentage_value": "0.150000000",
"percentage_amount": {
"currency": "USD",
"amount": "0.23"
},
"total": {
"currency": "USD",
"amount": "76.73"
}
},
"markup": {
"program": {
"fixed_amount": {
"currency": "USD",
"amount": "2.50"
},
"percentage_value": "0.000000000",
"percentage_amount": {
"currency": "USD",
"amount": "0.00"
},
"total": {
"currency": "USD",
"amount": "2.50"
}
},
"total_markup": {
"fixed_amount": {
"currency": "USD",
"amount": "2.50"
},
"percentage_value": "0.000000000",
"percentage_amount": {
"currency": "USD",
"amount": "0.00"
}
}
}
}
},
"fx_rate": {
"value": "1.000000000",
"details": {
"platform_rate": "1.000000000",
"markup": {
"partner": "0.000000000",
"total": "0.000000000"
},
"net_markup": "0.000000000"
}
}
},
"charged_amount": {
"currency": "USD",
"amount": "100229.23"
},
"converted_amount": {
"currency": "USD",
"amount": "100000.00"
},
"recipient_amount": {
"currency": "USD",
"amount": "100000.00"
},
"additional_data": {
"purpose_of_payment": "Family Maintenance",
"user_occupation": "",
"user_recipient_relationship": "Father",
"user_source_of_income": "Salary"
},
"tos": {
"tos_acceptance_date": "2023-07-23 02:59:12",
"tos_acceptance_device_id": "string",
"tos_acceptance_ip": "8.8.8.8",
"tos_acceptance_user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1",
"tos_acceptance_service_agreement": "string"
},
"remarks": "Remittance comment here",
"created_by": "7b61722fb9f94a232a6dbe5df53d6d49",
"created_at": "2025-12-17T16:19:46 +08:00",
"updated_at": "2025-12-17T16:19:46 +08:00"
}Let's examine the indicator field for document upload requirements on high-value cross-border payment:
- "status": "INITIATED",
- "sub_status": "DOCUMENT_REQUIRED", ← The quote sub_status indicating document requirement
- "document_requirements": { "types": ["INVOICE"],"accepted_formats": ["pdf","jpg","png"],"max_file_size": "5MB"} ← List of accepted documents (New)
- "document_required_types": [ "invoice", "bank_statement"], ← List of accepted documents (Deprecated)
To upload the required supplementary document for the cross-border payment transaction, you can call Upload/Replace Transaction Documents (POST /users/wallets/payouts/remittances/transactions/{transaction_id}/files) passing in the transaction ID of the cross-border payment that was initiated and is requiring a document upload.
Document upload restrictions:
- File format: PNG, JPEG, PDF
- File size: maximum 5MB per file
- No. of files: maximum 1 file
Upload/Replace Transaction Documents request
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: •••••' \
--form 'file=@"/Users//invoice.png"' \
--form 'document_type="INVOICE"' \
--form 'category="TRANSFER_PURPOSE"'Upload/Replace Transaction Documents response
{
"submission_id": "75a7218c835043169eee5eaf32e04196",
"transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB",
"category": "TRANSFER_PURPOSE",
"status": "UPLOADED",
"documents": [
{
"id": "36xtPDySJj6jgETNx2XZZ44tNsA",
"transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB",
"created_at": "2025-12-17T16:27:03 +08:00",
"type": "INVOICE",
"category": "TRANSFER_PURPOSE",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/sgmmusdu/document/download/36xtPDySJj6jgETNx2XZZ44tNsA.png",
"link_expires_at": "2025-12-17T16:42:03 +08:00",
"status": "UPLOADED"
}
],
"count": 1
}After the document is successfully uploaded, you will need to finalize the requirement completion and put the transaction on resume the queue for processing.
You can do this by calling Confirm and Finalize Transaction Document Upload (PUT /users/wallets/payouts/remittances/transactions/{transaction_id}/files) passing the transaction ID.
Confirm and Finalize Transaction Document Upload request
curl --location --request PUT 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••'Confirm and Finalize Transaction Document Upload response
"OK"You can also call Get List of Transaction Documents (GET /users/wallets/payouts/remittances/transactions/{transaction_id}/files) to view and verify the document submitted for the high-value transaction.
Get List of Transaction Documents request
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••''Get List of Transaction Documents response
{
"data": [
{
"id": "36xtPDySJj6jgETNx2XZZ44tNsA",
"transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB",
"created_at": "2025-12-17T16:27:03 +08:00",
"type": "INVOICE",
"category": "TRANSFER_PURPOSE",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/sgmmusdu/document/download/36xtPDySJj6jgETNx2XZZ44tNsA.png",
"link_expires_at": "2025-12-17T16:42:03 +08:00",
"status": "UPLOADED"
}
]
}If during your document verification, you noticed that you have uploaded the wrong file or the file is in bad condition (such as blurry images). You will be able to replace the file using the same Upload/Replace Transaction Documents (POST /users/wallets/payouts/remittances/transactions/{transaction_id}/files) endpoint discussed above.
Related Links
On this page
- Perform a cross-border payment using an existing beneficiary