logo
Documentation Powered by ReDoc

EBANX Payment API Reference (1.0.0-beta.1)

E-mail: integration@ebanx.com URL: http://www.ebanx.com Terms of Service
More documentation about EBANX is also available in our developers portal

Introduction

Welcome to the EBANX API documentation

This API definition is intended to guide you through our integrations.

EBANX Direct API

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

Authentication

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!

integration_key

Security Scheme Type API Key
Query parameter name: integration_key

Sign up for an EBANX Sandbox Account here

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.

FX

Get FX rate

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.

Authorizations:
integration_key
Request Body schema: application/json

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).

Responses

200

OK

post /ws/exchange
https://api.ebanxpay.com/ws/exchange
https://sandbox.ebanxpay.com/ws/exchange

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "currency_code": "USD",
  • "currency_base_code": "BRL"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "currency_rate":
    {
    },
  • "status": "SUCCESS"
}

Get an FX Token

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.

Authorizations:
integration_key
Request Body schema: application/json

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:

  • br: Brazil.
  • pe: Peru.
  • mx: Mexico.
  • co: Colombia.
  • cl: Chile.
  • ar: Argentina.
  • bo: Bolivia.
currency_from
required
string 3 characters
Enum: "EUR" "USD"

The three-letter currency code from which the amount will be converted. Supported currencies:

  • EUR
  • USD
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:

  • BRL
  • MXN
  • PEN
  • CLP
  • COP
  • ARS
  • BOB

Responses

200

OK

post /ws/fxtoken/get
https://api.ebanxpay.com/ws/fxtoken/get
https://sandbox.ebanxpay.com/ws/fxtoken/get

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "country": "CO",
  • "currency_from": "USD",
  • "currency_to": "COP"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
}

Tokenization

Create a Card token

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.

Authorizations:
integration_key
Request Body schema: application/json

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:

  • br: Brazil.
  • co: Colombia.
  • mx: Mexico.
  • pe: Peru.
creditcard
required
object

The credit card JSON Object

Responses

200

OK

post /ws/token
https://api.ebanxpay.com/ws/token
https://sandbox.ebanxpay.com/ws/token

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "public_integration_key": "your_test_public_integration_key",
  • "payment_type_code": "visa",
  • "token": "stringstringstringstringstringst",
  • "country": "br",
  • "creditcard":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "SUCCESS",
  • "payment_type_code": "visa",
  • "token": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6",
  • "masked_card_number": "411111xxxxxx1111"
}

Set a token CVV

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.

Authorizations:
integration_key
Request Body schema: application/json

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.

Responses

200

OK

post /ws/token/setCVV
https://api.ebanxpay.com/ws/token/setCVV
https://sandbox.ebanxpay.com/ws/token/setCVV

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "token": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6",
  • "card_cvv": "123"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "SUCCESS",
  • "token": "805c49a8c606b4f2d53fad5aa688ec6c3aa247b83ac2146ee148e328244670b16f5cb719766b3a82e902387670958e71c323413c62df5ce975c1abf99d2049c6",
  • "masked_card_number": "411111xxxxxx1111"
}

Payment Page

Payment Page API

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.

Authorizations:
integration_key
Request Body schema: application/json

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:

  • EUR
  • BRL
  • MXN
  • PEN
  • USD
  • CLP
  • COP
  • ARS
  • BOB
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:

  • _all: all available payment methods for the merchant account in this country.
  • amex: American Express credit card (Brazil, Mexico, Colombia, Peru).
  • bancodobrasil: Banco do Brasil online debit (Brazil).
  • banrisul: Banrisul online debit (Brazil).
  • banktransfer: Bank transfer (Brazil).
  • boleto: Boleto bancário (Brazil).
  • bradesco: Bradesco online debit (Brazil).
  • carnet: CARNET credit card (Mexico).
  • diners: Diners credit card (Brazil, Colombia, Peru).
  • discover: Discover credit card (Brazil).
  • ebanxaccount: EBANX Account (Brazil).
  • eft: Bank Transfer (Colombia).
  • elo: Elo credit card (Brazil).
  • hipercard: Hipercard credit card (Brazil).
  • itau: Itaú online debit (Brazil).
  • mastercard: MasterCard credit card (Brazil, Mexico, Colombia, Peru).
  • multicaja: Multicaja (Chile).
  • oxxo: OXXO (Mexico).
  • pagoefectivo: PagoEfectivo (Peru).
  • pagosnet: PagosNet (Bolivia).
  • safetypay: SafetyPay (Peru, Ecuador, Checkout only).
  • safetypay-cash: SafetyPay Cash (Peru, Ecuador).
  • safetypay-online: SafetyPay Online (Peru, Ecuador).
  • sencillito: Sencillito (Chile).
  • servipag: Servipag (Chile).
  • spei: SPEI bank transfer method (Mexico).
  • visa: Visa credit card (Brazil, Mexico, Colombia, Peru).
  • webpay: Webpay (Chile).
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:

  • bo: Bolivia.
  • br: Brazil.
  • cl: Chile.
  • co: Colombia.
  • mx: Mexico.
  • pe: Peru.
  • ar: Argentina.
  • ec: Ecuador.
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”.

Responses

200

OK

post /ws/request
https://api.ebanxpay.com/ws/request
https://sandbox.ebanxpay.com/ws/request

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "SUCCESS",
  • "payment":
    {