Perform a cross-border payment using an existing recipient
Learn the standard process for executing a cross-border transfer to a saved recipient 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 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. - 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 Cross-border Payout Transactions (POST /users/wallets/payouts/remittances/transactions) and pass the selected recipient ID and quotation ID.
Send Cross-border Payout Transactions API-related field enumerations:
user_recipient_relationshipallowed values are listed in the List Mobile Country Code Enumerations (GET /users/enumerations/mobile_country_code).user_source_of_incomeallowed values are listed in the List Source of Income Enumerations (GET /users/enumerations/main_income_source).user_occupationallowed values are listed in the List Occupation Enumerations (GET /users/enumerations/occupations).
Send Cross-border Payout Transactions 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 Cross-border Payout Transactions 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 (when required)
Document Upload Requirement
Depending on the configuration, some SWIFT cross-border payments may require a supporting document (e.g., invoices) when:
- the transfer amount is greater than the review threshold*
- the document requirement is enabled for selected transfer mode: (
user_typetorecipient_type) combination - the payment rail for the remittance route is enabled for document upload
RFI Requirement
Other high-value transactions may be issued an RFI when:
- the transactions require some additional information before the payment rail provider can process the transaction
- the transfer amount is greater than the review threshold*
- the payment rail for the remittance route is NOT enabled for document upload
These RFI will be a manual process and will require email communication between the Partner payouts team and MatchMove Finance teams for resolutions.
*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 Cross-border Payout Transactions response (with quotation ID and recipient ID) with high-value transaction amount
{
"id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB",
"status": "INITIATED",
"sub_status": "DOCUMENT_REQUIRED",
"document_required_types": [
"INVOICE".
"SOURCE_OF_FUNDS"
],
"document_requirements": {
"types": [
"INVOICE",
"SOURCE_OF_FUNDS"
],
"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, SOURCE_OF_FUNDS"],"accepted_formats": ["pdf","jpg","png"],"max_file_size": "5MB"} ← List of accepted documents (New)
To upload the required supplementary document for the cross-border payment transaction, you can call Create/Replace Cross-border Payout 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
Document types supported:
INVOICE
Verifies the underlying purpose of the transaction. It acts as proof that the funds are being sent for a legitimate reason, such as paying a vendor, settling a bill, or purchasing goods and services.
SOURCE_OF_FUNDS
Validates the legal origin of the sender's money. This typically involves documents like payslips, bank statements, or tax returns to ensure the money entering the system does not stem from illicit activities.
Create/Replace Cross-border Payout 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"'
Create/Replace Cross-border Payout 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 Cross-border Payout Transaction Documents (PUT /users/wallets/payouts/remittances/transactions/{transaction_id}/files) passing the transaction ID.
Confirm Cross-border Payout Transaction Documents 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 Cross-border Payout Transaction Documents response
"OK"
You can also call List Cross-border Payout Transaction Documents (GET /users/wallets/payouts/remittances/transactions/{transaction_id}/files) to view and verify the document submitted for the high-value transaction.
List Cross-border Payout 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: ••••••''
List Cross-border Payout 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 Create/Replace Cross-border Payout 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 recipient