Here are some resources and examples for creating a payment request with FX. This is important for accepting any cross-boarder payments, and allowing your customers to pay in their preferred currency while you accept your local currency.
Create FX Payment via API
Using the Rapyd API to create an FX payment allows white label customization for your fintech or payment application for your customers.
Create Payment with FX and Fees (4 Minutes)
Create Payment with FX and Fees (15 Minutes Long)
Create Payment with FX
Request
POST https://sandboxapi.rapyd.net/v1/payments
{
"amount": 1000,
"currency": "USD",
"requested_currency": "SGD",
"fixed_side": "buy",
"expiration": 1688194081,
"ewallets": [{
"ewallet": "ewallet_aae2950a42c497c12397ad998c60e71c",
"percentage": 100
}
],
"payment_fees": {
"transaction_fee": {
"calc_type": "gross",
"fee_type": "absolute",
"value": 2
},
"fx_fee": {
"calc_type": "gross",
"fee_type": "percentage",
"value": 2.5
}
},
"payment_method": {
"type": "sg_ocbcpao_bank",
"fields": {
"app_id":"12345677",
"url_scheme":"https://test.org"
}
}
}
Response
{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "7fa9d97b-1366-4f26-be5d-726e237dac02"
},
"data": {
"id": "payment_e4bb87cceb80b95bed12f54797c2eb11",
"amount": 0,
"original_amount": 1431.34,
"is_partial": false,
"currency_code": "SGD",
"country_code": "SG",
"status": "ACT",
"description": "",
"merchant_reference_id": "",
"customer_token": "cus_844c359dd1265e9f7cd5abf75a604d11",
"payment_method": "other_e9c84642f0b306422d574e5464f701d9",
"payment_method_data": {
"id": "other_e9c84642f0b306422d574e5464f701d9",
"type": "sg_ocbcpao_bank",
"category": "bank_redirect",
"metadata": {},
"image": "",
"webhook_url": "",
"supporting_documentation": "",
"next_action": "not_applicable",
"bic_swift": "",
"account_last4": "",
"app_id": "12345677",
"url_scheme": "https://test.org"
},
"auth_code": null,
"expiration": 1680207715,
"captured": true,
"refunded": false,
"refunded_amount": 0,
"receipt_email": "",
"redirect_url": "https://sandboxcheckout.rapyd.net/complete-bank-payment?token=payment_e4bb87cceb80b95bed12f54797c2eb11&complete_payment_url=&error_payment_url=",
"complete_payment_url": "",
"error_payment_url": "",
"receipt_number": "",
"flow_type": "",
"address": null,
"statement_descriptor": "Test Business",
"transaction_id": "",
"created_at": 1678998115,
"metadata": {},
"failure_code": "",
"failure_message": "",
"paid": false,
"paid_at": 0,
"dispute": null,
"refunds": null,
"order": null,
"outcome": null,
"visual_codes": {},
"textual_codes": {},
"instructions": {},
"ewallet_id": null,
"ewallets": [
{
"ewallet_id": "ewallet_aae2950a42c497c12397ad998c60e71c",
"amount": 1000,
"percent": 100,
"refunded_amount": 0
},
{
"ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
"amount": 27,
"percent": 2.7,
"refunded_amount": 0
}
],
"payment_method_options": {},
"payment_method_type": "sg_ocbcpao_bank",
"payment_method_type_category": "bank_redirect",
"fx_rate": 0.71750997,
"merchant_requested_currency": "USD",
"merchant_requested_amount": 1027,
"fixed_side": "buy",
"payment_fees": {
"transaction_fee": {
"calc_type": "gross",
"value": 2,
"fee_type": "absolute"
},
"fx_fee": {
"calc_type": "gross",
"value": 2.5
},
"gross_fees": 27,
"net_fees": 0,
"total_merchant_fees": 1.44
},
"invoice": "",
"escrow": null,
"group_payment": "",
"cancel_reason": null,
"initiation_type": "customer_present",
"mid": "",
"next_action": "pending_confirmation",
"error_code": "",
"remitter_information": {},
"save_payment_method": true
}
}
Complete the Payment
Creating any payment with a third party action like bank redirect, bank transfer, cash payment, or card with 3DS will require an additional action by the customer to complete the payment.
Here is a simulation of what a completed payment will look like.
Request
POST https://sandboxapi.rapyd.net/v1/payments/completePayment
{
"token": "payment_e4bb87cceb80b95bed12f54797c2eb11",
"param1": "rapyd",
"param2": "success"
}
Response
{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "7aff6f8d-b001-45e2-8bd9-4fe62066a0e6"
},
"data": {
"id": "payment_e4bb87cceb80b95bed12f54797c2eb11",
"amount": 1431.34,
"original_amount": 1431.34,
"is_partial": false,
"currency_code": "SGD",
"country_code": "SG",
"status": "CLO",
"description": "",
"merchant_reference_id": "",
"customer_token": "cus_844c359dd1265e9f7cd5abf75a604d11",
"payment_method": "other_e9c84642f0b306422d574e5464f701d9",
"payment_method_data": {
"id": "other_e9c84642f0b306422d574e5464f701d9",
"type": "sg_ocbcpao_bank",
"category": "bank_redirect",
"metadata": {},
"image": "",
"webhook_url": "",
"supporting_documentation": "",
"next_action": "not_applicable",
"bic_swift": "",
"account_last4": "",
"app_id": "12345677",
"url_scheme": "https://test.org"
},
"auth_code": null,
"expiration": 1680207715,
"captured": true,
"refunded": false,
"refunded_amount": 0,
"receipt_email": "",
"redirect_url": "https://sandboxcheckout.rapyd.net/complete-bank-payment?token=payment_e4bb87cceb80b95bed12f54797c2eb11&complete_payment_url=&error_payment_url=",
"complete_payment_url": "",
"error_payment_url": "",
"receipt_number": "",
"flow_type": "",
"address": null,
"statement_descriptor": "Test Business",
"transaction_id": "",
"created_at": 1678998115,
"metadata": {},
"failure_code": "",
"failure_message": "",
"paid": true,
"paid_at": 1678998198,
"dispute": null,
"refunds": null,
"order": null,
"outcome": null,
"visual_codes": {},
"textual_codes": {},
"instructions": {},
"ewallet_id": null,
"ewallets": [
{
"ewallet_id": "ewallet_aae2950a42c497c12397ad998c60e71c",
"amount": 1000,
"percent": 100,
"refunded_amount": 0
},
{
"ewallet_id": "ewallet_db4ad4a76278f94c4a83dd9b28b483ed",
"amount": 27,
"percent": 2.7,
"refunded_amount": 0
}
],
"payment_method_options": {},
"payment_method_type": "sg_ocbcpao_bank",
"payment_method_type_category": "bank_redirect",
"fx_rate": 0.71750997,
"merchant_requested_currency": "USD",
"merchant_requested_amount": 1027,
"fixed_side": "buy",
"payment_fees": {
"transaction_fee": {
"calc_type": "gross",
"value": 2,
"fee_type": "absolute"
},
"fx_fee": {
"calc_type": "gross",
"value": 2.5
},
"gross_fees": 27,
"net_fees": 0,
"total_merchant_fees": 0
},
"invoice": "",
"escrow": null,
"group_payment": "",
"cancel_reason": null,
"initiation_type": "customer_present",
"mid": "",
"next_action": "not_applicable",
"error_code": "",
"remitter_information": {},
"save_payment_method": true
}
}
Create Checkout Page with FX
Creating a checkout page with FX allows you to accept a cross-boarder payment without the PCI-DSS Level 1 requirements.
Request
POST https://sandboxapi.rapyd.net/v1/payments/completePayment
{
"amount": 400,
"complete_payment_url": "http://example.com/complete",
"country": "GB",
"currency": "EUR",
"error_payment_url": "http://example.com/error",
"payment_method": {
"type":"gb_sepadirectdebit_bank"
},
"ewallets": [
{
"ewallet": "ewallet_1ee1b7bf161a56fdd793ca227f050bd9",
"percentage": 100
}
],
"expiration": 1679251684,
"fixed_side": "buy",
"metadata": {
"merchant_defined": true
},
"requested_currency": "MXN"
}
Response
{
"status": {
"error_code": "",
"status": "SUCCESS",
"message": "",
"response_code": "",
"operation_id": "5718d455-64b3-4097-95d7-4ab1e93aee1a"
},
"data": {
"id": "checkout_108d0c5e110afbd228e39aeb1c4df490",
"status": "NEW",
"language": null,
"org_id": "d1e61d7a-99fc-46cd-9785-33c47e000b30",
"merchant_color": "323fff",
"merchant_logo": null,
"merchant_website": "http://rapyd.net",
"merchant_customer_support": {
"url": "http://support.rapyd.net",
"email": "support@rapyd.net",
"phone_number": "555-555-5555"
},
"merchant_alias": "Test Business",
"merchant_terms": null,
"merchant_privacy_policy": null,
"page_expiration": 1680208066,
"redirect_url": "https://sandboxcheckout.rapyd.net?token=checkout_108d0c5e110afbd228e39aeb1c4df490",
"merchant_main_button": "pay_now",
"cancel_checkout_url": "http://rapyd.net",
"complete_checkout_url": "http://rapyd.net",
"country": "GB",
"currency": "MXN",
"amount": 8279.88,
"payment": {
"id": null,
"amount": 8279.88,
"original_amount": 0,
"is_partial": false,
"currency_code": "MXN",
"country_code": "GB",
"status": null,
"description": "Payment via Checkout",
"merchant_reference_id": null,
"customer_token": null,
"payment_method": {
"type": "gb_sepadirectdebit_bank"
},
"payment_method_data": {},
"expiration": 1679251684,
"captured": false,
"refunded": false,
"refunded_amount": 0,
"receipt_email": null,
"redirect_url": null,
"complete_payment_url": "http://example.com/complete",
"error_payment_url": "http://example.com/error",
"receipt_number": null,
"flow_type": null,
"address": null,
"statement_descriptor": null,
"transaction_id": null,
"created_at": 0,
"updated_at": 0,
"metadata": {
"merchant_defined": true
},
"failure_code": null,
"failure_message": null,
"paid": false,
"paid_at": 0,
"dispute": null,
"refunds": null,
"order": null,
"outcome": null,
"visual_codes": {},
"textual_codes": {},
"instructions": {},
"ewallets": [
{
"ewallet": "ewallet_1ee1b7bf161a56fdd793ca227f050bd9",
"amount": 400,
"percent": 100
}
],
"payment_method_options": {},
"payment_method_type": null,
"payment_method_type_category": null,
"fx_rate": 0.048309,
"merchant_requested_currency": "EUR",
"merchant_requested_amount": 400,
"fixed_side": "buy",
"payment_fees": null,
"invoice": null,
"escrow": null,
"group_payment": null,
"cancel_reason": null,
"initiation_type": "customer_present",
"mid": null,
"next_action": "not_applicable"
},
"payment_method_type": null,
"payment_method_type_categories": null,
"payment_method_types_include": null,
"payment_method_types_exclude": null,
"account_funding_transaction": null,
"customer": null,
"custom_elements": {
"save_card_default": false,
"display_description": false,
"payment_fees_display": true,
"merchant_currency_only": false,
"billing_address_collect": false,
"dynamic_currency_conversion": false
},
"timestamp": 1678998467,
"payment_expiration": null,
"cart_items": [],
"escrow": null,
"escrow_release_days": null
}
}
