Payment with FX

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
    }
}

Checkout Page with FX Example

1 Like