FX Tools

About this guide

This guide quickly demonstrates the operations related with Foreign Exchange (FX) Rate in EBANX, how it works and how it can be integrated into your e-commerce. We will walk you through all possible flows to allow you to better deal with FX Rate in your EBANX integration.

We will quicly describe how to:

• Get FX rate;
• Freeze FX rate;

info

FX operations are only available in EBANX Direct API Integration. Are you not integrated yet? Please take a look in this basic guide about it.

Getting FX Rate

How it works

With EBANX Direct API, you can get the current FX rate that will be used in your payment. To get the current FX rate, you just need to call the end-point /ws/exchange (from your server) with the following required fields.

Field	Description
integration_key	Your unique and secret integration key
currency_base_code	Original currency code to be converted (ISO 4217 3 letter code)
currency_code	Target currency code (ISO 4217 3 letter code)

API Reference

You can check the complete API reference here

Here is an example:

curl -X GET -G 'https://sandbox.ebanxpay.com/ws/exchange' \

-d 'integration_key=your_test_integration_key' \

-d 'currency_code=USD'

-d 'currency_base_code=BRL'

The response would be:

{

"currency_rate": {

"code": "USD",

"base_code": "BRL",

"name": "Real to US Dollar",

"rate": "2.7731"

},

"status": "SUCCESS"

}

Freezing FX Rate

With EBANX Direct API, you are able to "freeze" the FX rate up to 24 hours with two API calls.

What you will need

Before start your integration, please make sure that you have:

1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
2. Integration with EBANX Direct API to process your payments;
3. Fixed FX feature enabled to your account. If it is not the case, you can require it to our support team

How it works

To freeze the FX rate using EBANX Direc API, please follow the steps below.

1. Generate the FX token

   The very first step to freeze the FX rate is to generate a fx_token that will be used in all your following payments. To generate this token, you just need to call the end-point ws/fxtoken/get (POST request from your server) with the following required fields.

   Parameter	What is
   integration_key	Your unique and secret integration key.
   country	Two letter country country code
   currency_from	Original currency code (ISO 4217 3 letter code)
   currency_to	Target currency code (ISO 4217 3 letter code)

   API Reference

   You can check the complete API reference here

   Check the example:

   curl -X POST 'https://sandbox.ebanxpay.com/ws/fxtoken/get'

   -d '{

   "integration_key": INTEGRATION_KEY,

   "country": "co",

   "currency_from": "USD",

   "currency_to": "COP"

   }'

   A successful request will return a JSON response similar to the one below.

   {

   "fx_token": "sandbox.20171025.USD.COP",

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

   }

   caution

   Please, note that the token has an expiration date/time and must be renewed with a new API call before its expiration.

2. Call /ws/direct end-point with the generated token

   With the token that was generated in the step below, you can call normally call /ws/direct end-point (the same that you use to make your payments), sending the fx_token as an additional parameter.

   EBANX Direct API Reference

   You can check the complete EBANX Direct API reference here

   Check the example:

   curl -X POST 'https://sandbox.ebanxpay.com/ws/direct' \

   -d '{

   "integration_key": "INTEGRATION_KEY",

   "fx_token": "sandbox.20171025.USD.COP",

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

   }

   }'

   The payment will be normally generated and a successful request will return a JSON response similar to the one below.

   {

   "redirect_url": null,

   "payment": {

   "hash": "59ef82c854a2f6fd28ff865b05dc1412eba3f110b6c19f82",

   "pin": "020790537",

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

   }

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

• If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
• In case you’re already our partner please get in touch with our support team at integration@ebanx.com.