Get a quote for cross-border payment
Understand how to get a time-limited quote with guaranteed foreign exchange rates and a transparent breakdown of all fees. This guide explains the mandatory step of locking in the financial details of a cross-border transfer.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to retrieve a quotation (test calculation) containing the deductible amount and all fees charged for the cross-border payment transaction.
- You want to implement a feature in your application that takes in the user's desired route and amount and generates a quotation.
- You want to display the breakdown of all the deductibles from the user (sender) and the receivables of the recipient (receiver).
- You want to display the foreign exchange effect on the deductible and receivable amounts.
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.
API Workflow
1
Retrieve the available corridors (remittance routes) for the program
Before asking the user (sender) any of their intended remittance details, we need to know the available corridors or remittance routes that are enabled in the program.
Corridor enablement will be based on the program configuration (as stated in the contract) along with the remittance rail and SWIFT routes availability.
Call the Get Remittance Corridor List (GET /users/wallet/payouts/remittances/corridors) filtering only the active routes based on the user type of the customer (sender).
Get Remittance Corridor List request (filter by status and user_type [sender], recipient_type [receiver])
CURL
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallet/payouts/remittances/corridors?status=ACTIVE&recipient_type=INDIVIDUAL&user_type=INDIVIDUAL' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Get Remittance Corridor List response
JSON
{
"pagination": {
"total_records": 5,
"records_per_page": 100,
"total_pages": 1,
"links": {
"self": "https://{{server}}/{{program_code}}/v2/users/wallet/payouts/remittances/corridors?page=1&records_per_page=100&user_type=INDIVIDUAL&recipient_type=INDIVIDUAL"
}
},
"data": [
{
"id": "4b007556de30487d8fd7df0e53d07bd7",
"receiving_country": "United States",
"receiving_country_code": "USA",
"mobile_country_code": "+1",
"user_type": "INDIVIDUAL",
"recipient_type": "INDIVIDUAL",
"institute_type": "BANK",
"payment_rail": "LOCAL",
"charge_types": [],
"currency": "US Dollar",
"currency_code": "USD",
"currency_precision": "2",
"status": "ACTIVE"
},
{
"id": "0823dde9bcf847bc97723395bb7b69aa",
"receiving_country": "United States",
"receiving_country_code": "USA",
"mobile_country_code": "+1",
"user_type": "INDIVIDUAL",
"recipient_type": "INDIVIDUAL",
"institute_type": "BANK",
"payment_rail": "SWIFT",
"charge_types": [
"OUR",
"SHA"
],
"currency": "US Dollar",
"currency_code": "USD",
"currency_precision": "2",
"status": "ACTIVE"
},
{
"id": "1a65c300fe594e18bb1ad9fff831b1b7",
"receiving_country": "United States",
"receiving_country_code": "USA",
"mobile_country_code": "+1",
"user_type": "INDIVIDUAL",
"recipient_type": "INDIVIDUAL",
"institute_type": "BANK",
"payment_rail": "SWIFT",
"charge_types": [
"OUR",
"SHA"
],
"currency": "Singapore Dollar",
"currency_code": "SGD",
"currency_precision": "2",
"status": "ACTIVE"
},
{
"id": "b61d6b7ee37a4708b0c36e9c3cbb7883",
"receiving_country": "United States",
"receiving_country_code": "USA",
"mobile_country_code": "+1",
"user_type": "INDIVIDUAL",
"recipient_type": "INDIVIDUAL",
"institute_type": "BANK",
"payment_rail": "SWIFT",
"charge_types": [
"OUR",
"SHA"
],
"currency": "Euro",
"currency_code": "EUR",
"currency_precision": "2",
"status": "ACTIVE"
},
{
"id": "e6ab8a36a9ca41b7962a2e04948b74ce",
"receiving_country": "United States",
"receiving_country_code": "USA",
"mobile_country_code": "+1",
"user_type": "INDIVIDUAL",
"recipient_type": "INDIVIDUAL",
"institute_type": "BANK",
"payment_rail": "SWIFT",
"charge_types": [
"OUR",
"SHA"
],
"currency": "Pound Sterling",
"currency_code": "GBP",
"currency_precision": "2",
"status": "ACTIVE"
}
]
}You will need to display the list of active corridors available to your users in your frontend. To help the user choose, you will need to display the additional rail parameters, such as payment_rails and charge_types.
Once the user has selected a corridor, take note of the corridor ID. You can use this to call the Get Remittance Corridor Details (GET /users/wallet/payouts/remittances/corridors/{corridor_id}) by passing the chosen corridor ID of the remittance route. This will reveal more details such as corridor rates and fees, per-transaction limits, etc.
You can also display this additional corridor information for the user to help him have a more informed decision before proceeding to get a quotation.
Get Remittance Corridor Details request
CURL
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallet/payouts/remittances/corridors/{{corridor_id}}' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'Get Remittance Corridor Details response
JSON
{
"id": "0823dde9bcf847bc97723395bb7b69aa",
"receiving_country": "United States",
"receiving_country_code": "USA",
"mobile_country_code": "+1",
"user_type": "INDIVIDUAL",
"recipient_type": "INDIVIDUAL",
"institute_type": "BANK",
"payment_rail": "SWIFT",
"currency": "US Dollar",
"currency_code": "USD",
"currency_precision": "2",
"status": "ACTIVE",
"rates": {
"platform": [
{
"charge_type": "OUR",
"transfer_fee_amount": "1.50",
"transfer_fee_currency": "USD",
"transfer_fee_percentage": "0.000000000"
},
{
"charge_type": "SHA",
"transfer_fee_amount": "1.50",
"transfer_fee_currency": "USD",
"transfer_fee_percentage": "0.000000000"
}
],
"program": [
{
"charge_type": "OUR",
"exchange_rate_markup": "0.000000000",
"transfer_fee_amount": "2.50",
"transfer_fee_currency": "USD",
"transfer_fee_percentage": "0.000000000"
},
{
"charge_type": "SHA",
"exchange_rate_markup": "0.000000000",
"transfer_fee_amount": "2.50",
"transfer_fee_currency": "USD",
"transfer_fee_percentage": "0.000000000"
}
]
},
"limits": {
"transaction_limits": {
"delivery_time": "T+1",
"maximum_amount": "500000.00",
"maximum_amount_currency": "USD",
"minimum_amount": "100.00",
"minimum_amount_currency": "USD",
"transaction_cutoff": "04:00 PM",
"transaction_cutoff_timezone": "Asia/Singapore"
},
"velocity_limits": {
"max_per_transaction": "25000.00",
"transaction_limit_currency": "USD",
"transaction_rolling_in_days": 30,
"max_transaction_rolling_days_sender": "125000.00",
"max_transaction_rolling_days_receiver": "125000.00",
"max_transaction_sender_currency": "USD",
"max_transaction_receiver_currency": "USD"
}
},
"permitted_purposes": [
"FAMILY_MAINTENANCE",
"HOUSEHOLD_MAINTENANCE",
"DONATION_OR_GIFTS",
"PAYMENT_OF_LOAN",
"PURCHASE_OF_PROPERTY",
"FUNERAL_EXPENSES",
"WEDDING_EXPENSES",
"MEDICAL_EXPENSES",
"PAYMENT_OF_BILLS",
"EDUCATION",
"SAVINGS",
"EMPLOYEE_COLLEAGUE",
"BUSINESS_OR_INVESTMENT",
"SALARY",
"PAYMENT_OF_GOODS_AND_SERVICES"
]}
}}Corridor Limits
Transaction Limits
This is the transaction amount limit per transaction.
Velocity Limits
This is the transaction amount limit within a rolling period. The velocity spending is the accumulated sum of all the successful (completed) and pending (outstanding) transaction amounts within the rolling period.
2
Enquire for a quote for a remittance transaction
A quote or quotation is a detailed computation of fees, the charged amount (sender), and the recipient amount (recipient).
When all the required parameters are ready, call Enquire Quotes (POST /users/wallets/payouts/remittances/quotes) to retrieve the calculated quotation for the incoming remittance transaction of the customer. A quotation can be identified by its quotation ID.
Enquire Quotes request (LOCAL)
CURL
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/quotes' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"amount": "300",
"recipient_country": "USA",
"receiving_currency": "USD",
"recipient_type": "INDIVIDUAL",
"receiving_institution_type": "BANK",
"quote_type": "REVERSE",
"payment_rail": "LOCAL",
"fees": {
"included": false
}
}'Enquire Quotes response (LOCAL)
JSON
{
"quotes": [
{
"id": "KljS2wEM5IDM3gTN2cTMtUFRTVVTNd0Ut8UVRB",
"expiry": "2025-12-16T16:31:30 +08:00",
"delivery_time": "NEXT DAY",
"status": "CONFIRMED",
"type": "REVERSE",
"source_country": "SGP",
"source_currency": "USD",
"destination_country": "USA",
"destination_currency": "USD",
"recipient_type": "INDIVIDUAL",
"receiving_institution_type": "BANK",
"payment_rail": "LOCAL",
"charge_type": null,
"user": {
"id": "1d2f696095bfe563058484b66d0a25fa",
"email": "hinanshu@matchmove.com",
"mobile_country_code": "91",
"mobile": "8054042741",
"type": "INDIVIDUAL"
},
"charged_amount": {
"amount": "306.75",
"currency": "USD"
},
"converted_amount": {
"amount": "300.00",
"currency": "USD"
},
"recipient_amount": {
"amount": "300.00",
"currency": "USD"
},
"fees": {
"included": false,
"fixed_amount": {
"amount": "6.00",
"currency": "USD"
},
"percentage_value": "0.250000000",
"percentage_amount": {
"amount": "0.75",
"currency": "USD"
},
"total": {
"amount": "6.75",
"currency": "USD"
},
"details": {
"platform_charge": {
"fixed_amount": {
"amount": "5.00",
"currency": "USD"
},
"percentage_value": "0.050000000",
"percentage_amount": {
"amount": "0.15",
"currency": "USD"
},
"total": {
"amount": "5.15",
"currency": "USD"
}
},
"markup": {
"program": {
"fixed_amount": {
"amount": "1.00",
"currency": "USD"
},
"percentage_value": "0.200000000",
"percentage_amount": {
"amount": "0.60",
"currency": "USD"
},
"total": {
"amount": "1.60",
"currency": "USD"
}
},
"total_markup": {
"fixed_amount": {
"amount": "1.00",
"currency": "USD"
},
"percentage_value": "0.200000000",
"percentage_amount": {
"amount": "0.60",
"currency": "USD"
}
}
}
}
},
"fx_rate": {
"value": "1.000000000",
"details": {
"platform_rate": "1.000000000",
"markup": {
"partner": "0.000000000",
"total": "0.000000000"
},
"net_markup": "0.000000000"
}
},
"created_by": "1d2f696095bfe563058484b66d0a25fa",
"created_at": "2025-12-16T15:31:30 +08:00"
}
]
}Enquire Quote request (SWIFT)
CURL
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/quotes' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"amount": "300",
"recipient_country": "USA",
"receiving_currency": "USD",
"recipient_type": "INDIVIDUAL",
"receiving_institution_type": "BANK",
"quote_type": "REVERSE",
"payment_rail": "SWIFT",
"charge_type": "OUR",
"fees": {
"included": false
}
}'Enquire Quote response (SWIFT)
JSON
{
"quotes": [
{
"id": "JJlWUNTM4ADM3gTN2cTMtUFRTVVTNd0Ut8UVRB",
"expiry": "2025-12-16T16:28:01 +08:00",
"delivery_time": "NEXT DAY",
"status": "CONFIRMED",
"type": "REVERSE",
"source_country": "SGP",
"source_currency": "USD",
"destination_country": "USA",
"destination_currency": "USD",
"recipient_type": "INDIVIDUAL",
"receiving_institution_type": "BANK",
"payment_rail": "SWIFT",
"charge_type": "OUR",
"user": {
"id": "1d2f696095bfe563058484b66d0a25fa",
"email": "johnsmith@matchmove.com",
"mobile_country_code": "91",
"mobile": "8054042741",
"type": "INDIVIDUAL"
},
"charged_amount": {
"amount": "379.45",
"currency": "USD"
},
"converted_amount": {
"amount": "300.00",
"currency": "USD"
},
"recipient_amount": {
"amount": "300.00",
"currency": "USD"
},
"fees": {
"included": false,
"fixed_amount": {
"amount": "79.00",
"currency": "USD"
},
"percentage_value": "0.150000000",
"percentage_amount": {
"amount": "0.45",
"currency": "USD"
},
"total": {
"amount": "79.45",
"currency": "USD"
},
"details": {
"platform_charge": {
"fixed_amount": {
"amount": "76.50",
"currency": "USD"
},
"percentage_value": "0.150000000",
"percentage_amount": {
"amount": "0.45",
"currency": "USD"
},
"total": {
"amount": "76.95",
"currency": "USD"
}
},
"markup": {
"program": {
"fixed_amount": {
"amount": "2.50",
"currency": "USD"
},
"percentage_value": "0.000000000",
"percentage_amount": {
"amount": "0.00",
"currency": "USD"
},
"total": {
"amount": "2.50",
"currency": "USD"
}
},
"total_markup": {
"fixed_amount": {
"amount": "2.50",
"currency": "USD"
},
"percentage_value": "0.000000000",
"percentage_amount": {
"amount": "0.00",
"currency": "USD"
}
}
}
}
},
"fx_rate": {
"value": "1.000000000",
"details": {
"platform_rate": "1.000000000",
"markup": {
"partner": "0.000000000",
"total": "0.000000000"
},
"net_markup": "0.000000000"
}
},
"created_by": "1d2f696095bfe563058484b66d0a25fa",
"created_at": "2025-12-16T15:28:01 +08:00"
}
]
}Remittance Quotation Expiry
A remittance quote will only be valid for a specified period and will have an expiry time. During this period, the forex rate, converted amount, and total fees will be reserved.
Once the quote has expired, you will need to pull a fresh quotation using the Enquire Quotes API.
If the quote expiry happens while the customer is about to send the remittance transaction, an appropriate error message regarding quote expiry will be emitted.
3
[SWIFT] Prepare for supplementary document upload 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.
When a quotation is requested and the intended transaction amount breaches the threshold, an additional indicator field will be added to the payload.
You will need to prepare to collect a document from the user (sender) intending to send the cross-border payment.
Enquire Quote request (SWIFT) with high-value transaction amount
CURL
curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/quotes' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"amount": "100000",
"recipient_country": "USA",
"receiving_currency": "USD",
"recipient_type": "INDIVIDUAL",
"receiving_institution_type": "BANK",
"quote_type": "FORWARD",
"charge_type": "OUR",
"payment_rail": "SWIFT",
"fees": {
"included": false
}
}'Enquire Quote response (SWIFT) with high-value transaction amount
JSON
{
"quotes": [
{
"id": "Sh1UNlzN4ETO1kTN2cTMtUFRTVVTNd0Ut8UVRB",
"expiry": "2025-12-17T17:13:07 +08:00",
"delivery_time": "2 DAYS",
"status": "CONFIRMED",
"sub_status": "DOCUMENT_REQUIRED",
"document_required_types": [
"INVOICE"
],
"document_requirements": {
"types": [
"INVOICE"
],
"accepted_formats": [
"pdf",
"jpg",
"png"
],
"max_file_size": "5MB"
},
"type": "FORWARD",
"source_country": "SGP",
"source_currency": "USD",
"destination_country": "USA",
"destination_currency": "USD",
"recipient_type": "INDIVIDUAL",
"receiving_institution_type": "BANK",
"payment_rail": "SWIFT",
"charge_type": "OUR",
"user": {
"id": "7b61722fb9f94a232a6dbe5df53d6d49",
"email": "john.smith@matchmove.com",
"mobile_country_code": "65",
"mobile": "2076071232",
"type": "INDIVIDUAL"
},
"charged_amount": {
"amount": "100229.23",
"currency": "USD"
},
"converted_amount": {
"amount": "100000.00",
"currency": "USD"
},
"recipient_amount": {
"amount": "100000.00",
"currency": "USD"
},
"fees": {
"included": false,
"fixed_amount": {
"amount": "79.00",
"currency": "USD"
},
"percentage_value": "0.150000000",
"percentage_amount": {
"amount": "0.23",
"currency": "USD"
},
"total": {
"amount": "79.23",
"currency": "USD"
},
"details": {
"platform_charge": {
"fixed_amount": {
"amount": "76.50",
"currency": "USD"
},
"percentage_value": "0.150000000",
"percentage_amount": {
"amount": "0.23",
"currency": "USD"
},
"total": {
"amount": "76.73",
"currency": "USD"
}
},
"markup": {
"program": {
"fixed_amount": {
"amount": "2.50",
"currency": "USD"
},
"percentage_value": "0.000000000",
"percentage_amount": {
"amount": "0.00",
"currency": "USD"
},
"total": {
"amount": "2.50",
"currency": "USD"
}
},
"total_markup": {
"fixed_amount": {
"amount": "2.50",
"currency": "USD"
},
"percentage_value": "0.000000000",
"percentage_amount": {
"amount": "0.00",
"currency": "USD"
}
}
}
}
},
"fx_rate": {
"value": "1.000000000",
"details": {
"platform_rate": "1.000000000",
"markup": {
"partner": "0.000000000",
"total": "0.000000000"
},
"net_markup": "0.000000000"
}
},
"created_by": "7b61722fb9f94a232a6dbe5df53d6d49",
"created_at": "2025-12-17T16:13:07 +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)
The required document will need to be uploaded right after the cross-border payment is sent and the quotation (quotation ID) is consumed. Go to the Perform a cross-border payment using an existing beneficiary or without an existing beneficiary section to learn more.
Related Links
Was this section helpful?
On this page
- Get a quote for cross-border payment