This API definition is intended to guide you through our integrations.
The EBANX Direct API is the transparent checkout (with no redirect) solution that allows you to accept payments by all payment methods and countries directly on your domain. Your customers will benefit from a smoother user experience as they can complete the checkout without the need to leave the store's front end.
Feedbacks? You can drop us an e-mail to feedback@ebanx.com
With just one integration, your company can sell to consumers based in Brazil, Mexico, Argentina, Colombia, Chile, Peru, and Ecuador. Offering local payment options is an excellent opportunity to increase your sales and reach even more customers.
As with any secure payment integration, you will first need to set up authorization. The EBANX sandbox allows you to set up a test environment to run transactions using test credit card numbers and explore our payment solutions.
Sign up for an Sandbox Account at our EBANX Business Page, select your business model and answer a few questions. We'll get in touch with you shortly after!
At this stage, you will have access to your test Integration keys. After the conclusion of your negotiation and the integration process with our team, you will receive your live integration keys.
The exchange operation is a server-to-server HTTP POST used by the merchant website to query EBANX for the current exchange rate for a given currency.
Exchange body object
integration_key required | string <= 100 characters Your unique and secret integration key. |
currency_code required | string 3 characters The code of the currency (ISO 4217 3 letter code). |
currency_base_code required | string 3 characters The code of the base (target) currency (ISO 4217 3 letter code). |
OK
{- "integration_key": "your_test_integration_key",
- "currency_code": "USD",
- "currency_base_code": "BRL"
}
{- "currency_rate": {
- "code": "USD",
- "base_code": "BRL",
- "name": "Real to US Dollar",
- "rate": "2.7731"
}, - "status": "SUCCESS"
}
This is a server-to-server operation that retrieves a token to be used in fixed exchange rate operations.
The integration team should be contacted to enable it upon request to use this feature.
fxToken body object
integration_key required | string <= 100 characters Your unique and secret integration key. |
country required | string 2 characters Enum: "br" "pe" "mx" "co" "cl" "ar" "bo" The two-letter code for the country where the operation is being processed. The available codes are:
|
currency_from required | string 3 characters Enum: "EUR" "USD" The three-letter currency code from which the amount will be converted. Supported currencies:
|
currency_to required | string 3 characters Enum: "BRL" "MXN" "PEN" "CLP" "COP" "ARS" "BOB" The three-letter currency code to which the amount will be converted. Supported currencies:
|
OK
{- "integration_key": "your_test_integration_key",
- "country": "CO",
- "currency_from": "USD",
- "currency_to": "COP"
}
{- "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"
}
The token operation is used to create a token for a given credit card to be used for recurrent payments.
For this method, you will need to wrap the request parameters in a JSON object and send them as the value of a parameter called request_body.
Note To generate the token and check the credit card authenticity, EBANX creates a temporary transaction that will not be captured. It’s important to know that the tokens expire after 14 months of its last use.
Create a credit card token
integration_key required | string <= 100 characters Your unique and secret integration key. |
public_integration_key required | string <= 100 characters Your unique and public integration key. You can do a token operation using this key instead of the integration key when the request is from the client of your customer (browser, app, etc…). By doing this, you don’t have to deal directly with the credit card information of your customer. |
payment_type_code required | string [ 1 .. 32 ] characters Enum: "amex" "aura" "diners" "discover" "elo" "hipercard" "mastercard" "visa" The credit card scheme: amex, aura, diners, discover, elo, hipercard, mastercard, visa. |
token | string [ 32 .. 128 ] characters This must be set if you want to inform the token instead of letting EBANX create one. |
country required | string 2 characters Enum: "br" "co" "mx" "pe" The two-letter country code for the customer country. The available codes are:
|
creditcard required | object The credit card JSON Object |
OK
{- "integration_key": "your_test_integration_key",
- "public_integration_key": "your_test_public_integration_key",
- "payment_type_code": "visa",
- "token": "stringstringstringstringstringst",
- "country": "br",
- "creditcard": {
- "card_number": 4111111111111111,
- "card_name": "Jose da Silva",
- "card_due_date": "10/2020",
- "card_cvv": "123"
}
}
{- "status": "SUCCESS",
- "payment_type_code": "visa",
- "token": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6",
- "masked_card_number": "411111xxxxxx1111"
}
The setCVV operation is used to temporarily associate a CVV with an existing token. This CVV will be used by the next request made with the associated token and then discarded.
The setCVV operation is useful for one-click payments, where you already have the customer's credit card information and cannot send the CVV from your server.
For this method, you will need to wrap the request parameters in a JSON object and send them as the value of a parameter called request_body
.
Payment body object
integration_key | string <= 100 characters Your unique and secret integration key. |
token required | string [ 32 .. 128 ] characters The token that you want to associate the CVV with. |
card_cvv required | string [ 3 .. 4 ] characters Credit card security code. |
OK
{- "integration_key": "your_test_integration_key",
- "token": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6",
- "card_cvv": "123"
}
{- "status": "SUCCESS",
- "token": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6",
- "masked_card_number": "411111xxxxxx1111"
}
This method allows you to create a payment using EBANX Payment Page, where the customer is redirected to EBANX’s website to enter his data.
Payment body object
integration_key required | string <= 100 characters Your unique and secret integration key. |
name required | string [ 1 .. 100 ] characters Customer name. |
email required | string [ 5 .. 100 ] characters Customer email address. |
currency_code required | string 3 characters Enum: "EUR" "BRL" "MXN" "PEN" "USD" "CLP" "COP" "ARS" "BOB" Three-letter code of the payment currency. Supported currencies:
|
amount required | number The amount in the specified currency (currency_code). |
merchant_payment_code | string The payment hash Merchant Payment Code (unique merchant ID). |
order_number | string [ 1 .. 40 ] characters The order number, optional identifier set by the merchant. You can have multiple payments with the same order number. |
payment_type_code required | string [ 1 .. 32 ] characters Enum: "_all" "amex" "bancodobrasil" "banrisul" "banktransfer" "boleto" "bradesco" "carnet" "diners" "discover" "ebanxaccount" "eft" "elo" "hipercard" "itau" "mastercard" "multicaja" "oxxo" "pagoefectivo" "pagosnet" "safetypay" "safetypay-cash" "safetypay-online" "sencillito" "servipag" "spei" "visa" "webpay" The code of the payment method. The supported codes are:
|
user_value_1 | string [ 1 .. 20 ] characters Optional parameter that can be used by the merchant to associate additional info to the payment. This parameter will be appended to the response_url when the transaction is finished. |
user_value_2 | string [ 1 .. 20 ] characters Optional parameter that can be used by the merchant to associate additional info to the payment. This parameter will be appended to the response_url when the transaction is finished. |
user_value_3 | string [ 1 .. 20 ] characters Optional parameter that can be used by the merchant to associate additional info to the payment. This parameter will be appended to the response_url when the transaction is finished. |
user_value_4 | string [ 1 .. 20 ] characters Optional parameter that can be used by the merchant to associate additional info to the payment. This parameter will be appended to the response_url when the transaction is finished. |
user_value_5 | string [ 1 .. 20 ] characters Optional parameter that can be used by the merchant to associate additional info to the payment. This parameter will be appended to the response_url when the transaction is finished. |
notification_url | string [ 1 .. 2000 ] characters The URL to send notifications for this payment. If this field is filled, EBANX will notify using this URL instead of the configured one. Example: https://notify.example.com/ |
bypass_boleto_screen | boolean Optional parameter to tell EBANX to redirect the customer straight to the response URL after the payment is completed. This can be used in cases where the merchant will provide all the payment information in the response URL page. If this parameter is passed and equals to true then EBANX will not display the payment completed screen and will redirect the customer straight to the response URL, where the merchant must provide all the payment information. If the parameter is not provided or its value is not true, the payment completed screen will be displayed. |
zipcode | string 8 characters Customer zipcode. If provided, the information will be displayed in the EBANX Payment Page. |
street_number | string [ 1 .. 30 ] characters Customer street number. If provided, the information will be displayed in the EBANX Payment Page. |
city | string [ 1 .. 80 ] characters Customer city. If provided, the information will be displayed in the EBANX Payment Page. |
state | string Customer state/region/province. If provided, the information will be displayed in the EBANX Payment Page. |
country required | string Enum: "bo" "br" "cl" "co" "mx" "pe" "ar" "ec" The two-letter country code for the customer country. The available codes are:
|
phone_number | string [ 10 .. 15 ] characters Customer phone number. If provided, the information will be displayed in the EBANX Payment Page. |
due_date | string 10 characters The due date of payments slips. Due date for boleto payments in the format dd/mm/yyyy. The maximum expiry date will depend on your merchant account settings.The due date is based on the local time of the country that the payment is generated. |
sub_acc_name | string [ 1 .. 32 ] characters The name of the sub account. |
sub_acc_image_url | string [ 1 .. 200 ] characters The URL of the logo of the sub account. OBS: It MUST be a HTTPS URL, otherwise, you will receive and error message. |
instalments | string [ 1 .. 5 ] characters Number or Range of instalments. OBS: If your are sending a range, must be in the format “X-Y”. Example: “1-6”. |
OK
{- "integration_key": "your_test_integration_key",
- "name": "José Silva",
- "email": "josesilva@example.com",
- "currency_code": "BRL",
- "amount": "100",
- "merchant_payment_code": "d59cb7166e7",
- "order_number": "string",
- "payment_type_code": "_all",
- "user_value_1": "string",
- "user_value_2": "string",
- "user_value_3": "string",
- "user_value_4": "string",
- "user_value_5": "string",
- "notification_url": "string",
- "bypass_boleto_screen": true,
- "zipcode": "61919-230",
- "street_number": "1040",
- "city": "Maracanau",
- "state": "CE",
- "country": "br",
- "phone_number": 8522847035,
- "due_date": "stringstri",
- "sub_acc_name": "string",
- "sub_acc_image_url": "string",
- "instalments": "strin"
}
{- "status": "SUCCESS",
- "payment": {
- "hash": "5ae0b5d4f1883ed4b214c0277af29f1981443f59a26eef87",
- "country": "br",
- "merchant_payment_code": "d59cwwwb7166e7",
- "order_number": null,
- "status": "OP",
- "status_date": null,
- "open_date": "2018-04-25 17:07:31",
- "confirm_date": null,
- "transfer_date": null,
- "amount_br": 100.38,
- "amount_ext": 100,
- "amount_iof": 0.38,
- "currency_rate": 1,
- "currency_ext": "BRL&qu