Version: current

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.

FieldDescription
integration_keyYour unique and secret integration key
currency_base_codeOriginal currency code to be converted (ISO 4217 3 letter code)
currency_codeTarget 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.

    ParameterWhat is
    integration_keyYour unique and secret integration key.
    countryTwo letter country country code
    currency_fromOriginal currency code (ISO 4217 3 letter code)
    currency_toTarget 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": "baloto",
    "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": "baloto",
    "baloto_url": "...",
    "voucher_id": "20790537",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
    "document": "123123",
    "email": "customer@test.co",
    "name": "TEST CUSTOMER",
    "birth_date": 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 ou this form and our comercial 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.
Last updated on by Fernando Pankiewicz Gomes