This page's content:

If you are integrated with Spreedly, you can use EBANX as a payment gateway of choice to process credit cards in Argentina, Brazil, Colombia, Chile, Mexico and Peru. Follow the steps below to get started:


1. Add EBANX as a payment gateway

The first step is to call Spreedly’s gateway endpoint to create a token for the EBANX gateway to be called afterwards.

Endpoint: https://core.spreedly.com/v1/gateways.json
Authorization: Basic <environment key>:<access_secret key>
Header: Content-Type: application/json
Method: POST
gateway_type string

This should be set as ebanx.

integration_key string

Your unique and secret integration key.

Examples of request and response:


2. Create a payment method

Next, collect the customer information and send it to Spreedly in order to create a payment method. This operation will generate a token that will be utilized in the future to charge the customer.

Endpoint: https://core.spreedly.com/v1/payment_methods.json
Authorization: Basic <environment key>:<access_secret key>
Header: Content-Type: application/json
Method: POST

This endpoint accepts the following parameters:

payment_method.credit_card.first_name string

Customer’s First Name

payment_method.credit_card.last_name string

Customer’s Last Name

payment_method.credit_card.number string

Credit Card number

payment_method.credit_card.verification_value string

Credit Card security code (CVV)

payment_method.credit_card.month string

Credit Card expiration month

payment_method.credit_card.year string

Credit Card expiration year

payment_method.credit_card.address1 string

Customer address, first the street number and then street name. e.g.: 2323 Rua E

payment_method.credit_card.address2 string

Address complement, e.g. Apartment 302

payment_method.credit_card.city string

Customer City

payment_method.credit_card.state string

Customer State. For Brazil it must be the 2-letter code of the corresponding state

payment_method.credit_card.zip string

Customer Zipcode

payment_method.credit_card.country string

2 letter country code. Accepted values are:
br: Brazil
mx: Mexico
pe: Peru
co: Colombia
cl: Chile
ar: Argentina

payment_method.credit_card.retain_on_success boolean

Flag if the payment method must be retained.

payment_method.email string

Customer email.

payment_method.metadata string

Metadata node.

Examples of request and response:


3. Operating EBANX API

Now that you have the payment method created and the token in hands, you are able to send calls to EBANX API via Spreedly to charge the customer’s credit card (with or without pre-authorization) or refund a previous charge.


a) Charging a payment

In order to charge a credit card, replace the gateway_token you generated on step 1 in the endpoint URL, and send the payment_method_token generated on step 2 inside the request token alongside the amount and currency_code.

If you plan to reutilize a payment method for future charges, always set the retain_on_success flag as true.

In order to charge installments, you need to send the parameter instalments inside the transaction.gateway_specific_fields.ebanx node. In case the parameter is not sent, EBANX API will default the value to 1.

On some countries you might need to send the parameter document inside the transaction.gateway_specific.fields.ebanx node. Refer to the table below for field requirements across EBANX supported countries:

EBANX Mandatory Fields
Endpoint: https://core.spreedly.com/v1/gateways/<gateway_token>/purchase.json
Authorization: Basic <environment key>:<access_secret key>
Header: Content-Type: application/json
Method: POST

This endpoint accepts the following parameters:

transaction.payment_method_token string

Spreedly payment method token

transaction.amount integer

Amount to be charged. No decimals utilized, i.e. to charge 0.5 send the amount as 50

transaction.currency_code string

3 letter currency code. Accepted values are:
USD: US Dollars
BRL: Brazilian Reais
MXN: Mexican Pesos
PEN: Peruvian Soles
COP: Colombian Pesos
CLP: Chilean Pesos
ARS: Argentinian Pesos

transaction.retain_on_success boolean

Flag if the payment method must be retained.

transaction.gateway_specific_fields.ebanx.document string

Customer document, required in Argentina, Brazil, Colombia and Chile

transaction.gateway_specific_fields.ebanx.instalments integer

Number of installments, accepted values are:
Brazil: 1 – 12
Mexico: 1,3,6,9,12
Peru: 1 – 48
Colombia: 1 – 36
Chile: 1 – 48
Argentina: 1,2,3,6,9,12


Examples of request and response:


b) Pre-authorizing a payment

The request structure is the same as if you were charging a payment token, however it is sent to a different endpoint. After pre-authorizing the payment you need to either capture or void the payment. If you don’t, the pending authorization will be automatically cancelled after 4 days. Find the details below:

Endpoint: https://core.spreedly.com/v1/gateways/<gateway_token>/authorize.json
Authorization: Basic <environment key>:<access_secret key>
Header: Content-Type: application/json
Method: POST
Pre-authorization is not supported in Colombia.

Examples of request and response:


i) Capture a pre-authorized payment

To capture a payment that has been previously pre-authorized, send the transaction_token from the payment on the endpoint URL below:

Endpoint: https://core.spreedly.com/v1/transactions/<transaction_token>/capture.json
Authorization: Basic <environment key>:<access_secret key>
Header: Content-Type: application/json
Method: POST

Example of response:


ii) Cancel a pre-authorized payment

To cancel a payment that has been previously pre-authorized, send the transaction_token from the payment on the endpoint URL below:

Endpoint: https://core.spreedly.com/v1/transactions/<transaction_token>/void.json
Authorization: Basic <environment key>:<access_secret key>
Header: Content-Type: application/json
Method: POST

Example of response:


c) Refunding a payment

In order to refund a previous charge, send the transaction_token on the URL below and the description inside the node gateway_specific_fields.ebanx

Endpoint: https://core.spreedly.com/v1/transactions/<transaction_token>/credit.json
Authorization: Basic <environment key>:<access_secret key>
Header: Content-Type: application/json
Method: POST
You can do partial refunds by sending the amount parameter. If you don't send it, a full refund will be issued.

Examples of request and response: