Foreign Exchange Rate (FX) Tools enables seamless multi-currency transactions, supporting currency conversion, real-time exchange rates, and freezing (hedging) strategies. By integrating FX Tools, you can provide a localized payment experience for your customers in multiple regions, ensuring accurate currency conversion and optimized transaction rates.
Features
- Foreign exchange rates - Fetch real-time exchange rates.
- FX Freezing - Freeze exchange rates to protect against fluctuation.
Requirements
- API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
Foreign Exchange Rate (FX)
Follow the steps below to obtain a foreign exchange rate.
Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
https://sandbox.ebanx.com/ws/exchangeDefine your parameters
To retrieve exchange rates that will apply to your payment, call the
/ws/exchangeendpoint with the following parameters.Parameter Description integration_keyYour EBANX integration key currency_base_codeOriginal currency (ISO 4217 3 letter code) currency_codeTarget currency (ISO 4217 3 letter code) Example request
Use the following example to initiate a request.
curl -X POST \
--location 'https://sandbox.ebanxpay.com/ws/exchange' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data '{
"integration_key": "your_test_integration_key",
"currency_code": "USD", // Original currency
"currency_base_code": "BRL" // Target currency
}'Example response
A successful request returns a response like the example below.
{
"currency_rate": {
"code": "USD",
"base_code": "BRL",
"name": "Real to US Dollar",
"rate": "2.7731"
},
"status": "SUCCESS"
}Congratulations!
You have succesfully obtained an Foreign Exchange Rate (FX).
Freezing FX Rate
You can freeze or "lock in" an FX rate for up to 24 hours (to ensure stability against currency fluctuations).
Instructions
Follow the steps below.
Define you parameters
Generate an fx_token that secures the FX rate for multiple transactions (offering consistency in your payment process). To obtain this token, call the /ws/fxtoken/get endpoint with the following parameters.
Parameter Description integration_keyYour EBANX integration key. countryTwo letter country code currency_fromOriginal currency (ISO 4217 3 letter code) currency_toTarget currency (ISO 4217 3 letter code) Example request
Use the following example to initiate a request.
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/fxtoken/get' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"country": "co",
"currency_from": "USD", // Original currency
"currency_to": "COP" // Target currency
}'Example response
A successful request will return a JSON response similar to the one below.
{
"fx_token": "sandbox.20171025.USD.COP", // fx_token
"currency_rate": 3.6,
"currency_from": "USD",
"currency_to": "COP",
"expire_date": "2017-10-25T10:59:59+00:00",
"new_currency_rate_available_at": "2017-10-25T09:00:00+00:00"
}FX token expiration - The token includes an expiration date, after which it becomes invalid. To continue using a locked exchange rate, you'll need to renew the token with a new API call before it expires.
Create a payment using the FX token
Use the fx_token to call
/ws/directand create a payment (locking in the FX rate for the transaction).curl -X POST \
--location 'https://sandbox.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"fx_token": "sandbox.20171025.USD.COP", // Use the FX token as a parameter
"operation": "request",
"payment": {
"merchant_payment_code": "1508863196",
"amount_total": 10,
"currency_code": "USD",
"country": "co",
"email": "customer@test.co",
"payment_type_code": "efecty",
"name": "Test Customer",
"document": "12345678",
"phone_number": "99999-99999"
}
}'Payment response
A successful request will return a JSON response similar to the one below.
{
"redirect_url": null,
"payment": {
"hash": "59ef82c854a2f6fd28ff865b05dc1412eba3f110b6c19f82",
"merchant_payment_code": "1508864653",
"order_number": null,
"status": "PE",
"status_date": null,
"open_date": "2017-10-24 18:13:28",
"confirm_date": null,
"transfer_date": null,
"amount_br": "36.00",
"amount_ext": "10.00",
"amount_iof": "0.00",
"currency_rate": "3.6000",
"currency_ext": "USD",
"due_date": "2017-10-27",
"instalments": "1",
"payment_type_code": "efecty",
"notification_url": "...",
"voucher_id": "20790537",
"pre_approved": false,
"capture_available": null
},
"status": "SUCCESS"
}Congratulations!
You have succesfully created a payment using an FX Token.
Resources
Use the following resources when testing in your sandbox environment.
Sample Cards
Click here to view mock card data to validate your payment integration.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.