Perform a cross-border payment without an existing beneficiary
Understand how to execute a one-time cross-border payment without first creating a recipient profile. This guide covers transfers where beneficiary details are provided at the time of the transaction, rather than selected from a saved profile.
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 without a predefined recipient.
- You want to implement a feature that will allow individual users to perform cross-border payments to ad hoc individual recipients (C2C remittance mode).
- You want to implement a feature that will allow business users to perform cross-border payments to ad hoc individual recipients (B2C remittance mode).
- You want to implement a feature that will allow business users to perform cross-border payments to ad hoc 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.
- 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 (without 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 sent in the Send Remittance Transaction request.
Call the Send Remittance Transaction (POST /users/wallets/payouts/remittances/transactions) and passing the selected quotation ID and the recipient details based on the remittance form requirement of the recipient country, payment_rail, and remittance mode.
You can call Get Remittance Recipient Form (GET /users/wallets/payouts/remittances/recipients/forms) to get the list of information required for a recipient for a specific remittance route. You can go to the Create a recipient for cross-border payment to know more about how to construct a recipient based on the remittance form requirements.
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 (without a recipient ID)
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions' \
--header 'X-Auth-User-ID: 1d2f696095bfe563058484b66d0a25fa' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
"quote_id": "UNUMYhUO5UDN3gTN2cTMtUFRTVVTNd0Ut8UVRB",
"user_recipient_relationship": "FATHER",
"user_source_of_income": "SALARY",
"recipient_details": {
"receiving_institution_type": "BANK",
"recipient_type": "INDIVIDUAL",
"receiving_currency": "USD",
"recipient_country": "USA",
"payment_rail": "SWIFT",
"recipient_data": {
"user_information": {
"first_name": "James",
"last_name": "Smith",
"email": "jamesmith@matchmove.com",
"mobile_country_code": "1",
"mobile": "2145520123"
},
"address_details": {
"address_line_1": "1500",
"address_line_2": "Broadway",
"city": "New York",
"state": "NY",
"postal_code": "10036",
"country": "USA"
},
"bank_details": {
"account_type": "SAVINGS_ACCOUNT",
"account_name": "Steven Smith",
"account_number": "2118639169",
"code": "123456789",
"bank_id": "786bbfd4344a489391582eb8ba931604"
},
"additional_data": {
"purpose_of_payment": "FAMILY_MAINTENANCE"
}
}
},
"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 comment here"
}'Send Remittance Transaction response (without a recipient ID)
{
"id": "00kRIBzM2cDN3gTN2cTMtUFRTVVTNd0Ut4EWUB",
"status": "INITIATED",
"sub_status": "TRANSACTION_INITIATED",
"message": "Request received, processing started",
"source": [],
"user": {
"id": "1d2f696095bfe563058484b66d0a25fa",
"email": "hinanshu@matchmove.com",
"mobile_country_code": "91",
"mobile": "8054042741",
"country": "SGP",
"currency": "USD",
"type": "INDIVIDUAL"
},
"recipient": {
"id": "cdd9f88ca7794da8bf3ccbf5ae0a2bcc",
"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": "UNUMYhUO5UDN3gTN2cTMtUFRTVVTNd0Ut8UVRB",
"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": "Remittance comment here",
"created_by": "1d2f696095bfe563058484b66d0a25fa",
"created_at": "2025-12-16T16:46:03 +08:00",
"updated_at": "2025-12-16T16:46:03 +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 without an existing beneficiary