logo
Documentation Powered by ReDoc

EBANX Payment API Reference (1.0.0)

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":
    {
    }
}

Digital wallets

Get available e-wallets

This is a server-to-server HTTP POST used by the merchants to get the e-wallet codes, available in their countries, in order to use it with payment_type_code = ewallet in our Direct API.

  ...
  "payment_type_code": "nequi",
  ...
Authorizations:
integration_key
Request Body schema: application/json

Get available e-wallets per country

integration_key
required
string <= 100 characters

Your unique and secret integration key.

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.

Please, note that e-wallets will not be available in all the countries.

Responses

200

OK

post /ws/ewallet-availableEWallets
https://api.ebanxpay.com/ws/ewallet-availableEWallets
https://sandbox.ebanxpay.com/ws/ewallet-availableEWallets

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "country": "co"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[]

Direct Payments

Direct Payments

This method allows you to create a payment using EBANX Direct, our Transparent Checkout solution, where the customer checkouts without being redirected to EBANX’s website.

For this method, you will need to wrap the request paratemers 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
required
string [ 1 .. 100 ] characters

Your unique and secret integration key.

operation
required
string 7 characters

Must be request

mode
required
string 4 characters

Currently only full mode is available.

payment
required
All Objects (object) or Argentina 🇦🇷 (any) or Bolivia 🇧🇴 (any) or Brazil 🇧🇷 (any) or Chile 🇨🇱 (any) or Colombia 🇨🇴 (any) or Ecuador 🇪🇨 (any) or Mexico 🇲🇽 (any) or Peru 🇵🇪 (any) or Uruguay 🇺🇾 (any)

Responses

200

OK

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "\\ {Your integration key}",
  • "operation": "request",
  • "mode": "full",
  • "payment":
    {
    }
}

Response samples

Content type
application/json
Example
AR - Credit Card
Copy
 Expand all Collapse all
{
  • "payment":
    {
    },
  • "status": "SUCCESS"
}

Capture a payment

This is a server-to-server HTTP POST used by the merchant to capture credit card payments when the auto_capture flag is false in the Direct Operation.

Authorizations:
integration_key
Request Body schema: application/json

Capture a pre-auth transaction

integration_key
required
string <= 100 characters

Your unique and secret integration key.

hash
required
string 48 characters

The payment hash (EBANX unique identifier). Required if merchant_payment_code not provided.

merchant_payment_code
required
string [ 1 .. 40 ] characters

The payment hash Merchant Payment Code (unique merchant ID). Required if hash not provided.

merchant_capture_code
string [ 1 .. 200 ] characters

Optional identifier for the payment capture.

amount
number

The amount of the partial capture. You can make only one partial capture per authorized payment and this feature is only available in Brazil. If you want to enable this feature, please contact our Integration Team.

Responses

200

OK

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "hash": "5478ba283ef8674415082844ee14817376e49bb76aa9d4c7",
  • "merchant_payment_code": "126378126",
  • "merchant_capture_code": "string",
  • "amount": 0
}

Response samples

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

Cancel

Cancel

The cancel operation is a server-to-server operation that cancels payments.

You can cancel one payment if, and only if, its status is open (OP) or pending (PE). It’s important to know that confirmed payments (CO) cannot be cancelled.

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

hash
required
string 48 characters

The payment hash (EBANX unique identifier).

Responses

200

OK

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9"
}

Response samples

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

Refund

Refund

This is a server-to-server operation that handles payment refunds. There are two sub-operations: request and cancel. The request operation requests a refund. The cancel operation cancels a refund. Be mindful that some response attributes are only available through configurations, you can reach your account manager to check if you have them enabled.

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

operation
required
string [ 6 .. 7 ] characters

The available operations are: request: request a new refund. cancel: cancel a refund.

hash
required
string 48 characters

The payment hash (EBANX unique identifier).

amount
number

The amount to be refunded; expressed in the original payment currency. Required for request.

description
string [ 1 .. 500 ] characters

Description of the refund reason. Required for request.

merchant_refund_code
string [ 1 .. 40 ] characters

The ID of the refund on the merchant system. Unique Required for request

refund_id
integer 20 characters

The ID of the refund to be cancelled. Required for cancel.

bank_info
Brazil - Bank Transfer 🇧🇷 (object) or Brazil - Pix 🇧🇷 (object) or Chile 🇨🇱 (object) or Colombia 🇨🇴 (object) or Mexico 🇲🇽 (object) or Argentina 🇦🇷 (object) or Ecuador 🇪🇨 (object) or Nigeria 🇳🇬 (object) or Peru 🇵🇪 (object)

Object that holds bank information for the refund. Although this object is not mandatory, if you choose to use it, all it's elements are required to be provided

Responses

200

OK

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "operation": "request",
  • "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
  • "amount": 100,
  • "description": "Order did not arrive",
  • "merchant_refund_code": 787653,
  • "refund_id": 3784756,
  • "bank_info":
    {
    }
}

Response samples

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

Resend Bank Info

The resend refund bank info is a server-to-server operation to update the bank info data in a existing refund. Be mindful that some response attributes are only available through configurations, you can reach your account manager to check if you have them enabled.

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

hash
required
string 48 characters

The payment hash (EBANX unique identifier).

merchant_refund_code
required
string [ 1 .. 40 ] characters

The ID of the refund on the merchant system. Unique Required for request

refund_id
required
integer 20 characters

The ID of the refund to be updated. Required for resending.

bank_info
required
Brazil - Bank Transfer 🇧🇷 (object) or Brazil - Pix 🇧🇷 (object) or Chile 🇨🇱 (object) or Colombia 🇨🇴 (object) or Mexico 🇲🇽 (object) or Argentina 🇦🇷 (object) or Ecuador 🇪🇨 (object) or Nigeria 🇳🇬 (object) or Peru 🇵🇪 (object)

Object that holds bank information for the refund. Although this object is not mandatory, if you choose to use it, all its elements are required to be provided

Responses

200

OK

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
  • "merchant_refund_code": 787653,
  • "refund_id": 3784756,
  • "bank_info":
    {
    }
}

Response samples

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

Approve Sandbox Refund

The sandbox 'approve refund' process is a server-to-server operation to authorize the refund processing workflow in the sandbox environment, changing the refund status from Requested (RE) to Pending (PE). Note: This operation is only available in the sandbox environment for testing purposes as it occurs automatically in production.

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

integration_key
required
string <= 100 characters

Your unique and secret integration key. Required for request

merchant_refund_code
string [ 1 .. 40 ] characters

The ID of the refund on the merchant system. Mandatory if refund_id is not provided.

refund_id
integer 20 characters

The ID of the refund to be updated. Mandatory if merchant_refund_code is not provided.

Responses

200

OK

400

Bad Request

post /ws/simulateRefund/approveRefund
https://api.ebanxpay.com/ws/simulateRefund/approveRefund
https://sandbox.ebanxpay.com/ws/simulateRefund/approveRefund

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "merchant_refund_code": 787653,
  • "refund_id": 3784756
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "sucess"
}

Simulate Refund Form Sandbox

Designed only for the sandbox environment, the fill refund form operation is a server-to-server process that simulates the refund form filling process. It's limited to countries where bank info refunds are supported (BR, MX, CO, CL, AR, NG, EC, PE, EG)

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

integration_key
required
string <= 100 characters

Your unique and secret integration key. Required for request

merchant_refund_code
string [ 1 .. 40 ] characters

The ID of the refund on the merchant system. Required for request if refund_id is not provided.

refund_id
integer 20 characters

The ID of the refund to be updated. Required for request if merchant_refund_code is not provided.

use_invalid_data
required
boolean

Indicates whether you want to simulate if the bank info will be valid or not. if true, the bank info will be invalidated 10 minutes after the request and simulate asking for the customer to fill in the refund form again. Required for request

Responses

200

OK

400

Bad Request

post /ws/simulateRefund/fillRefundForm
https://api.ebanxpay.com/ws/simulateRefund/fillRefundForm
https://sandbox.ebanxpay.com/ws/simulateRefund/fillRefundForm

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "merchant_refund_code": 787653,
  • "refund_id": 3784756,
  • "use_invalid_data": true
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

Set Sandbox Refund as Paid

The server-to-server 'set refund as paid' operation triggers the refund payment confirmation workflow. Note: for cash payments, the 'refund form' operation is mandatory.

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

integration_key
required
string <= 100 characters

Your unique and secret integration key. Required for request

merchant_refund_code
string [ 1 .. 40 ] characters

The ID of the refund on the merchant system. Mandatory if refund_id is not provided.

refund_id
integer 20 characters

The ID of the refund to be updated. Mandatory if merchant_refund_code is not provided.

Responses

200

OK

400

Bad Request

post /ws/simulateRefund/setAsPaid
https://api.ebanxpay.com/ws/simulateRefund/setAsPaid
https://sandbox.ebanxpay.com/ws/simulateRefund/setAsPaid

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "merchant_refund_code": 787653,
  • "refund_id": 3784756
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "sucess"
}

Refund or Cancel

Refund or Cancel

The refund or cancel operation is a server-to-server operation to cancel payments or create payments refunds.

When the refundOrCancel operation is requested, the following will occur according to the payment status:

  • Open (OP) or Pending (PE) -- the payment will be cancelled (status changes to CA), and no refund will be made.
  • Confirmed (CO) -- it will be made a full refund of the payment to the customer.
Authorizations:
integration_key
Request Body schema: application/json

Payment body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

hash
required
string 48 characters

The payment hash (EBANX unique identifier). Required if merchant_payment_code not provided.

description
string [ 1 .. 1500 ] characters

Description of the refund reason. Required for request.

merchant_refund_code
string [ 1 .. 20 ] characters

The ID of the refund on the merchant system.

Responses

200

OK

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
  • "description": "Order did not arrive",
  • "merchant_refund_code": 787653
}

Response samples

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

Utils

EBANX BIN List

The BinList API returns a list of valid card BINs that would be accepted by EBANX. Merchants will then be able to make correct routing decisions depending on the customer's card BIN.

This API is designed to be called once in a while (server-to-server HTTP POST), so that Merchants can have their BIN table updated.

Authorizations:
integration_key
query Parameters
integration_key
required
string <= 100 characters
Example: integration_key=your_test_integration_key

Your unique and secret integration key.

country
string 2 characters non-empty
Enum: "BR" "MX" "CO" "CL" "AR" "PE"
Example: country=BR

If sent, returns only the BINs of the requested country

bank_info
boolean
Enum: true false
Example: bank_info=true

If set to true, returns the issuer bank or financial institution. This information will be returned only when available.

Responses

200

OK

get /ws/cardbin
https://api.ebanxpay.com/ws/cardbin
https://sandbox.ebanxpay.com/ws/cardbin

Request samples

Copy
curl --request GET 'https://api.ebanxpay.com/ws/cardbin/?integration_key={your_integration_key}&country=MX'

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "numberOfBins": 3,
  • "binList":
    [
    ]
}

Get bank list

The “getBankList operation” is a server-to-server HTTP POST used by the merchant website to query EBANX for the list of banks that are available to process with EBANX.

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

operation
required
string 7 characters

Must be request.

country
required
string 2 characters

The two-letter country code for the customer country. The available codes are: br: Brazil. co: Colombia. cl: Chile.

Responses

200

OK

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

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "operation": "request",
  • "country": "co"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Query

The query operation is a server-to-server HTTP POST used by the merchant website to query EBANX for information about a specific payment.

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

One of
  • query using hash
  • query using merchant_payment_code
integration_key
required
string <= 100 characters

Your unique and secret integration key.

hash
required
string 48 characters

The payment hash (EBANX unique identifier). Required if merchant_payment_code not provided.

merchant_payment_code
string [ 1 .. 40 ] characters

The payment hash Merchant Payment Code (unique merchant ID). Required if hash not provided.

Responses

200

OK

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

Request samples

Content type
application/json
Example
query using hash
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "hash": "5478ba283ef8674415082844ee14817376e49bb76aa9d4c7",
  • "merchant_payment_code": "1416854121"
}

Response samples

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

Print

You can use the print method to show a printable slip for the supported (cash) payment methods.

Authorizations:
integration_key
Request Body schema: application/json

Payment body object

hash
required
string 48 characters

The payment hash (EBANX unique identifier).

format
string 3 characters

The format that Boleto(BRA) or OXXO(MEX) cash payments can be printed. The following formats are accepted: pdf and html(default).

Responses

200

OK

post /print
https://api.ebanxpay.com/print
https://sandbox.ebanxpay.com/print

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "hash": "54737a76ffc1e5a520b0ed9062213a810ef41dae990184c7",
  • "format": "pdf"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "say": "hello world"
}

Installments Plan

The main purpose of this end-point is to deliver the installments plan using a given amount and currency. The installments values are based on the negotiated fee that merchants have with EBANX.

⚠️ This end-point is temporary available only to Brazil.
The another EBANX countries are comming soon.

Authorizations:
integration_key
query Parameters
integration_key
required
string <= 100 characters
Example: integration_key=your_test_integration_key

Your unique and secret integration key.

country_abbreviation
required
string 2 characters non-empty
Value: "BR"
Example: country_abbreviation=BR

Two letter ISO-3166 country code.

currency_code
required
string 3 characters
Value: "BRL"
Example: currency_code=BRL

Three-letter code of the payment currency. Supported currencies:

  • BRL
amount
required
number
Example: amount=100

The total amount in the specified currency (currency_code).

Responses

200

OK

get /ws/installmentsPlan
https://api.ebanxpay.com/ws/installmentsPlan
https://sandbox.ebanxpay.com/ws/installmentsPlan

Request samples

Copy
curl --location --request GET 'https://sandbox.ebanx.com/ws/instalmentsPlan/?country_abbreviation=br&integration_key={{your_integration_key}}&currency_code=BRL&amount=1599.99&bin=411111' \

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "instalmentsPlan":
    [
    ],
  • "bin":
    {
    }
}

Payout

The EBANX Payout Reference describes the parameters and returns values of each available operation.

This API indicates the success or failure of a request using the conventional HTTP response codes. The 200 code indicates success, the 4xx range indicates an error with the parameters of the request, and the 500 code indicates an error with EBANX’s servers.

Create a Payout request

This method allows you to create a payout.

Request Body schema: application/json

Payout body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

external_reference
required
string [ 4 .. 60 ] characters

The unique payout ID provided by you.

transaction_type
string 3 characters

The indication if transaction is B2B or B2C.
Required for the following countries:

  • Bolivia
  • Costa Rica
  • Dominican Republic
  • Ecuador
  • Egypt
  • India
  • Indonesia
  • Kenya
  • Morocco
  • Nigeria
  • Paraguay
  • Peru
  • South Africa
  • Uruguay
country
required
string 2 characters
Enum: "ar" "br" "co" "cl" "mx" "bo" "cr" "ec" "py" "pe" "uy" "do" "ke" "ng" "za" "ma" "eg" "in" "id"

The two-letter country code for the customer country. The available codes are:

  • ar: Argentina.
  • br: Brazil.
  • co: Colombia.
  • cl: Chile.
  • mx: Mexico.
  • bo: Bolivia.
  • cr: Costa Rica.
  • ec: Ecuador.
  • py: Paraguay.
  • pe: Peru.
  • uy: Uruguay.
  • do: Dominican Republic.
  • ke: Kenya.
  • ng: Nigeria.
  • za: South Africa.
  • ma: Morocco.
  • eg: Egypt.
  • in: India.
  • id: Indonesia.
amount
required
number

The amount in the specified currency (currency_code). E.g.,: 100.50.

currency_code
required
string 3 characters
Enum: "ARS" "BRL" "CLP" "COP" "MXN" "BOB" "CRC" "PYG" "PEN" "UYU" "DOP" "KES" "ZAR" "MAD" "EGP" "INR" "IDR" "NGN" "USD"

Three-letter code of the payout currency. Supported currencies:

  • Argentina: ARS, USD.
  • Brazil: BRL, USD.
  • Colombia: COP, USD.
  • Chile: CLP, USD.
  • Mexico: MXN, USD.
  • Bolivia: BOB, USD.
  • Costa Rica: CRC, USD.
  • Ecuador: USD.
  • Paraguay: PYG, USD.
  • Peru: PEN, USD.
  • Uruguay: UYU, USD.
  • Dominican Republic: DOP, USD.
  • Kenya: KES, USD.
  • Nigeria: NGN, USD.
  • South Africa: ZAR, USD.
  • Morocco: MAD, USD.
  • Egypt: EGP, USD.
  • India: INR, USD.
  • Indonesia: IDR, USD.
target
string
Enum: "bank_account" "ewallet_nequi" "mercadopago" "pix_key" "billet" "cashpak" "mpesa" "smartcash" "dana" "gopay" "imkas" "linkaja" "shopeepay" "ovo" "astrapay"

Name of payment provider name offered for each country, default value is bank_account.

  • bank_account: All countries
  • mercadopago: Argentina, Brazil, Mexico
  • ewallet_nequi: Colombia
  • pix_key: Brazil
  • billet: Dominican Republic
  • cashpak: Costa Rica
  • mpesa: Kenya
  • smartcash: Nigeria
  • dana: India
  • gopay: India
  • imkas: India
  • linkaja: India
  • shopeepay: India
  • ovo: India
  • astrapay: India
target_account
string

Account information is required for the following targets:

  • mercadopago
  • ewallet_nequi
  • pix_key
  • billet
  • cashpak
  • mpesa
  • smartcash
  • dana
  • gopay
  • imkas
  • linkaja
  • shopeepay
  • ovo
  • astrapay
order_number
string [ 6 .. 32 ] characters

A string generated by the merchant for external control

payee
required
Brazil 🇧🇷 (object) or Argentina 🇦🇷 (object) or Colombia 🇨🇴 (object) or Chile 🇨🇱 (object) or Mexico 🇲🇽 (object) or Argentina 🇦🇷 (object) or Bolivia 🇧🇴 (object) or Costa Rica 🇨🇷 (object) or Ecuador 🇪🇨 (object) or Paraguay 🇵🇾 (object) or Peru 🇵🇪 (object) or Uruguay 🇺🇾 (object) or Dominican Republic 🇩🇴 (object) or Kenya 🇰🇪 (object) or Nigeria 🇳🇬 (object) or South Africa 🇿🇦 (object) or Morocco 🇲🇦 (object) or Egypt 🇪🇬 (object) or India 🇮🇳 (object) or Indonesia 🇮🇩 (object)

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payout/create
https://api.ebanxpay.com/ws/payout/create
https://sandbox.ebanxpay.com/ws/payout/create

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "external_reference": "PAYOUT_EBANX_01",
  • "transaction_type": "B2C",
  • "country": "br",
  • "amount": 100,
  • "currency_code": "BRL",
  • "target": "mercadopago",
  • "target_account": "your@email.com",
  • "order_number": "ABCD123_-",
  • "payee":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "payout":
    {
    }
}

Cancel a Payout request

Within this end-point you will be able to cancel a payout using payouts's external_reference or its uid

The payout has to be in a status equal to OP and within the cancellation time.

Request Body schema: application/json

Payout body object

One of
  • external_reference
  • uid
integration_key
required
string <= 100 characters

Your unique and secret integration key.

external_reference
required
string [ 4 .. 60 ] characters

The unique payout ID provided by you.

uid
string <= 50 characters

The payout uid (EBANX unique identifier).

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payout/cancel
https://api.ebanxpay.com/ws/payout/cancel
https://sandbox.ebanxpay.com/ws/payout/cancel

Request samples

Content type
application/json
Example
external_reference
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "external_reference": "PAYOUT_EBANX_01",
  • "uid": "0f28f5b2bf60536d78b2dbf003c13886dd452d926"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "message": "You've successfully cancelled your Payout!"
}

Commit a Payout request

This method allows you to commit a payout, starting the payment process, without having to wait the cancellation time. The payout has to be in a status equal to OP and within the cancellation time.

You have to send either the external_reference or the uid

Request Body schema: application/json

Payout body object

One of
  • external_reference
  • uid
integration_key
required
string <= 100 characters

Your unique and secret integration key.

external_reference
required
string [ 4 .. 60 ] characters

The unique payout ID provided by you.

uid
string <= 50 characters

The payout uid (EBANX unique identifier).

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payout/commit
https://api.ebanxpay.com/ws/payout/commit
https://sandbox.ebanxpay.com/ws/payout/commit

Request samples

Content type
application/json
Example
external_reference
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "external_reference": "PAYOUT_EBANX_01",
  • "uid": "0f28f5b2bf60536d78b2dbf003c13886dd452d926"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "message": "You've successfully started the Payout payment process!"
}

Retrieve a Payout request

This method allows you to retrieve a payout information.

Request Body schema: application/json

Payout body object

One of
  • external_reference
  • uid
integration_key
required
string <= 100 characters

Your unique and secret integration key.

external_reference
required
string [ 4 .. 60 ] characters

The unique payout ID provided by you.

uid
string <= 50 characters

The payout uid (EBANX unique identifier).

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payout/retrieve
https://api.ebanxpay.com/ws/payout/retrieve
https://sandbox.ebanxpay.com/ws/payout/retrieve

Request samples

Content type
application/json
Example
external_reference
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "external_reference": "PAYOUT_EBANX_01",
  • "uid": "0f28f5b2bf60536d78b2dbf003c13886dd452d926"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "payout":
    {
    }
}

Simulate a Payout request

This method allows you to simulate a payout.

Request Body schema: application/json

Payout body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

country
required
string 2 characters

The two-letter country code for the customer country. The available codes are:

  • br: Brazil.
  • cl: Chile.
  • co: Colombia.
  • mx: Mexico.
amount
required
number

The amount in the specified currency (currency_code). E.g.,: 100.50

currency_code
required
string

Three-letter code of the payout currency. Supported currencies:

  • Brazil: BRL, USD.
  • Chile: CLP, USD.
  • Colombia: COP, USD.
  • Mexico: MXN, USD.

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payout/simulate
https://api.ebanxpay.com/ws/payout/simulate
https://sandbox.ebanxpay.com/ws/payout/simulate

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "country": "br",
  • "amount": 100,
  • "currency_code": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "payout":
    {
    }
}

Search Payout requests

This method allows you to retrieve multiple payouts information.

Request Body schema: application/json

Payout body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

date_from
required
string 10 characters

Initial date in the format yyyy-mm-dd. E.g. 1977-05-25

date_to
required
string 10 characters

End date in the format yyyy-mm-dd. E.g. 1977-05-26

page
integer

The page number of the current search.

status
string 2 characters
Enum: "CA" "OP" "PA" "PE"

The payout status. The following statuses are available:

  • OP: the payout is waiting to start the payment process.
  • PE: the payout is in payment process.
  • PA: the payout is paid.
  • CA: the payout is cancelled.
per_page
integer

Max number of payouts per page (API Max: 50)

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payout/search
https://api.ebanxpay.com/ws/payout/search
https://sandbox.ebanxpay.com/ws/payout/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "date_from": "1977-05-25",
  • "date_to": "1977-05-26",
  • "page": 2,
  • "status": "OP",
  • "per_page": 20
}

Response samples

Content type
application/json
Example
Date Range
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "records": "5",
  • "total_pages": 1,
  • "per_page": 50,
  • "page": 1,
  • "payouts":
    [
    ]
}

Get Available Balance.

This method allows you to get your available balance.

Request Body schema: application/json

Exchange body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

Responses

200

OK

400

invalid input, object invalid

409

an item already exists

post /ws/payout/balance
https://api.ebanxpay.com/ws/payout/balance
https://sandbox.ebanxpay.com/ws/payout/balance

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "balance": 150
}

Get Available Banks

The bank operation method call will return a JSON object with the all the available banks per country.

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payout/banks
https://api.ebanxpay.com/ws/payout/banks
https://sandbox.ebanxpay.com/ws/payout/banks

Request samples

Copy
curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/banks'

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "argentina":
    {
    },
  • "bolivia":
    [
    ],
  • "brazil":
    [
    ],
  • "chile":
    [
    ],
  • "colombia":
    [
    ],
  • "ecuador":
    [
    ],
  • "mexico":
    {
    },
  • "peru":
    [
    ]
}

Get Bank Details

This method call will return a JSON object with all the available bank details information per country.

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payout/bankDetails
https://api.ebanxpay.com/ws/payout/bankDetails
https://sandbox.ebanxpay.com/ws/payout/bankDetails

Request samples

Copy
curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/bankdetails'

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "brazil":
    {
    },
  • "colombia":
    {
    }
}

Create a Payee

This method allows you to create a pyee record.

Request Body schema: application/json

Payee body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

name
required
string

Payee full name.

email
required
string <email>

Payee email address.

document
required
string <= 32 characters

Payee national identification number.

  • Brazil: CPF or CNPJ.
  • Chile: RUN for individual users and RUT for companies
  • Colombia: For individual users CC (Cédula de ciudadanía), CE (Cédula de Extranjería) and TI (Targeta de Identidad) and for companies NIT
  • Mexico: RFC and CURP (individual user) and RFC (legal entity/company)
document_type
required
string <= 5 characters
Enum: "CPF" "CNPJ" "RUT"

Payee national identification number type.

  • Brazil: CPF or CNPJ.
  • Chile: RUN for individual users and RUT for companies
  • Colombia: For individual users CC (Cédula de ciudadanía), CE (Cédula de Extranjería) and TI (Targeta de Identidad) and for companies NIT
  • Mexico: RFC and CURP (individual user) and RFC (legal entity/company)
birth_date
required
string <yyyy-mm-dd> 10 characters

Payee birthdate in the format yyyy-mm-dd.

terms_accepted_at
string <yyyy-mm-dd hh24:mi:ss> 19 characters

Date and time that the payee accepted your terms and conditions. This is a mandatory information only for the model payee analysis.

bank_name
string

Bank Name.

bank_branch
string

Bank Branch Number

Required when there is a branch number.

bank_account
string

Bank account number.

account_type
string 1 characters
Enum: "C" "S"

Bank account type.

  • C -- for checking account.
  • S -- for savings account. For Brazil Savings account is available only for Santander.
bank_details
string

Additional information of the bank account.

  • Brazil: 3 digits operation code if bank is 104 Caixa Econômica.
  • Mexico: Clabe (Mexican standardized banking cipher).
zipcode
string

Zip code of the payee

state
string

State of the payee

city
string

City of the payee

address
required
string

Street of the payee

street_complement
string

Complement of the payee's address

country
required
string 2 characters
Enum: "br" "cl" "mx"

The two-letter country code for the customer country. The available codes are:

  • br: Brazil.
  • cl: Chile.
  • co: Colombia.
  • mx: Mexico.
shareholder
Array of objects

Array of objects describing each shareholder

  • This object is required when document_type is CNPJ
  • All shareholders with at least 25% share in the payout's amount must be added.

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/payee/create
https://api.ebanxpay.com/ws/payee/create
https://sandbox.ebanxpay.com/ws/payee/create

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "name": "Han Solo",
  • "email": "chew@bac.ca",
  • "document": 85351346893,
  • "document_type": "CPF",
  • "birth_date": "1977-05-25",
  • "terms_accepted_at": "2020-05-25 17:35:47",
  • "bank_name": "341 Itaú",
  • "bank_branch": "3707",
  • "bank_account": "01854-9",
  • "account_type": "C",
  • "bank_details": "001",
  • "zipcode": "string",
  • "state": "string",
  • "city": "string",
  • "address": "string",
  • "street_complement": "string",
  • "country": "br",
  • "shareholder":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "id": "100"
}

Verify Account

This method allows you to validate an account.

Request Body schema: application/json

Verify account body object

One of
  • mercadopago
  • pix_key
  • bank_account_pix
  • bank_account
integration_key
required
string <= 100 characters

Your unique and secret integration key.

country
required
string 2 characters
Enum: "br" "cl" "co" "mx"

The two-letter country code for the customer country. The available codes are:

  • br: Brazil.
  • cl: Chile.
  • co: Colombia.
  • mx: Mexico.
target
required
string
Value: "mercadopago"

Payment methods that will process the payout.

target_account
required
string

Destination account of payment method to query. Required to mercadopago

Responses

200

OK

post /ws/payout/verify_account
https://api.ebanxpay.com/ws/payout/verify_account
https://sandbox.ebanxpay.com/ws/payout/verify_account

Request samples

Content type
application/json
Example
mercadopago
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "country": "br",
  • "target": "mercadopago",
  • "target_account": "janedoe@someone.co"
}

Response samples

Content type
application/json
Example
Valid Account
Copy
 Expand all Collapse all
{
  • "status": "valid",
  • "message": "Account is valid"
}

MassPayout request

This method allows you to request a dozen of payouts from a single file request

Request Body schema: multipart/form-data
integration_key
required
string [ 1 .. 100 ] characters

Your unique and secret integration key

email_report
required
string <email> [ 1 .. 100 ] characters

Email to receive mass payout report created

mass_payout_file
required
object <csv, xlsx> [ 1 .. 100 ] characters

Mass-payout file. Name should follow this RegExp: 0-9a-zA-Z_\-.

Responses

200

OK

post /ws/masspayout/create
https://api.ebanxpay.com/ws/masspayout/create
https://sandbox.ebanxpay.com/ws/masspayout/create

Request samples

Copy
curl -X POST 'https://sandbox.ebanxpay.com/ws/masspayout/create' \
    -F 'integration_key=your_test_integration_key'
    -F 'email_report=john@doe.com'
    -F 'mass_payout_file=@my_mass_payout_file.csv'

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "mass_payout_id": 123456
}

Transfer

Create a Transfer Request

This method allows you to create a transfer request.

Request Body schema: application/json

Payout body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

external_reference
string [ 6 .. 40 ] characters

The external transfer reference.

amount
number

The amount in the specified currency (currency_code). E.g.,: 100.50

source
string

Transfer source. Supported sources:

  • payment_balance: transfer using your payment balance.

Default value is payment_balance.

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/transfer/create
https://api.ebanxpay.com/ws/transfer/create
https://sandbox.ebanxpay.com/ws/transfer/create

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "external_reference": "PAYOUT_TRANSFER_01",
  • "amount": 100,
  • "source": "payment_balance"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "transfer":
    {
    }
}

Cancel a Transfer Request

This method allows you to cancel a transfer request.

You have to send either the transfer_code, uid, settlement_code or external_reference.

Request Body schema: application/json

Payout body object

One of
  • external_reference
  • transfer_code
  • settlement_code
  • uid
integration_key
required
string <= 100 characters

Your unique and secret integration key.

external_reference
required
string [ 6 .. 40 ] characters

The external transfer reference.

transfer_code
string [ 6 .. 40 ] characters

The unique transfer reference code.

settlement_code
string [ 6 .. 40 ] characters

The transfer settlement code.

uid
string 50 characters

The transfer uid (EBANX unique identifier).

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/transfer/cancel
https://api.ebanxpay.com/ws/transfer/cancel
https://sandbox.ebanxpay.com/ws/transfer/cancel

Request samples

Content type
application/json
Example
external_reference
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "external_reference": "PAYOUT_TRANSFER_01",
  • "transfer_code": "14-2000",
  • "settlement_code": "14-2000",
  • "uid": "11ce3097af9ccf601b11038767962d3feded348ed"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "message": "You've successfully cancelled your Transfer!"
}

Retrieve a Transfer Request

This method allows you to retrieve a transfer information.

You have to send either the transfer_code, uid, settlement_code or external_reference.

Request Body schema: application/json

Payout body object

One of
  • external_reference
  • transfer_code
  • settlement_code
  • uid
integration_key
required
string <= 100 characters

Your unique and secret integration key.

external_reference
required
string [ 6 .. 40 ] characters

The external transfer reference.

transfer_code
string [ 6 .. 40 ] characters

The unique transfer reference code.

settlement_code
string [ 6 .. 40 ] characters

The transfer settlement code.

uid
string 50 characters

The transfer uid (EBANX unique identifier).

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/transfer/retrieve
https://api.ebanxpay.com/ws/transfer/retrieve
https://sandbox.ebanxpay.com/ws/transfer/retrieve

Request samples

Content type
application/json
Example
external_reference
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "external_reference": "PAYOUT_TRANSFER_01",
  • "transfer_code": "14-2000",
  • "settlement_code": "14-2000",
  • "uid": "11ce3097af9ccf601b11038767962d3feded348ed"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "transfer":
    {
    }
}

Search Transfer Requests

This method allows you to retrieve multiple transfers information.

Request Body schema: application/json

Payout body object

integration_key
required
string <= 100 characters

Your unique and secret integration key.

date_from
required
string 10 characters

Initial date in the format yyyy-mm-dd. E.g. 1977-05-25

date_to
required
string 10 characters

End date in the format yyyy-mm-dd. E.g. 1977-05-26

page
integer

The page number of the current search.

status
string 2 characters
Enum: "CA" "OP" "PA"

The transfer status. The following statuses are available:

  • OP: the payout is waiting to start the payment process.
  • PA: the payout is paid.
  • CA: the payout is cancelled.
per_page
integer

Max number of transfers per page (API Max: 50)

Responses

200

OK

400

invalid input, object invalid

409

an existing item already exists

post /ws/transfer/search
https://api.ebanxpay.com/ws/transfer/search
https://sandbox.ebanxpay.com/ws/transfer/search

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "integration_key": "your_test_integration_key",
  • "date_from": "1977-05-25",
  • "date_to": "1977-05-26",
  • "page": 2,
  • "status": "OP",
  • "per_page": 20
}

Response samples

Content type
application/json
Example
Date Range
Copy
 Expand all Collapse all
{
  • "type": "success",
  • "records": "2",
  • "total_pages": 1,
  • "per_page": 50,
  • "page": 1,
  • "transfers":
    [
    ]
}

Digital Accounts

For detailed guidance on this feature, access our Integration Guide by clicking here

In this block, you can better understand the behavior of digital accounts. The section comprises:

  • Creating digital accounts
  • Changing digital account data
  • Querying digital accounts

The solution follows Juno's API 2.0 standard: designed for whitelabel business structures.

Important: such digital accounts do not have access to Juno, being fully operationalized through the resources made available via API throughout their lifecycle.

Create digital account

The creation of a new digital account must be done through the main account, using the Digital Account Private Token that will be integrated in the parameter X-Resource-Token.

The created accounts are of type Payment Account and the data returned when creating the accounts must be stored for the purpose of manipulating the newly created account.

Important: Account access and manipulation are done via API only. They do not have a login and password to access the Juno Platform.

As of 10/04/2021, the obligation to enter bank details when creating the account was removed.

The mandatory bank details rule is still valid for the field autotransfer:true.

header Parameters
X-Api-Version
required
integer
Value: 2

API Version

X-Resource-Token
required
string
Example: <resource-token>

Resource token to be used in the operation.

Request Body schema: application/json;charset=UTF-8
type
required
string
Value: "PAYMENT"

Create a digital account. To learn more, access the [Digital Accounts] section (https://developer.ebanx.com/docs/digital-accounts/overview/).

name
required
string <= 80 characters

Name of the digital account.

document
required
string <without mask> [ 11 .. 14 ] characters

Digital Account CPF/CNPJ. Without special characters.

email
required
string <= 80 characters

Email Digital Account.

birthDate
string <date> 10 characters

Birthday date. Required for personal accounts.

phone
required
string <= 16 characters

Digital Account Phone.

businessArea
required
number <int64> <= 4 characters

Defines the company's business area. To see the allowed values, see voltar aqui

linesOfBusiness
required
string <= 100 characters

Defines the business area type.

companyType
string
Enum: "MEI" "EI" "EIRELI" "LTDA" "SA" "INSTITUITION_NGO_ASSOCIATION"

Defines the type of company. Required for companies accounts PJ For allowed values, see voltar aqui

legalRepresentative
object (LegalRepresentative)

Legal Representative. Required for PJ accounts.

address
required
object (Address)

Endereço.

bankAccount
object (BankAccount)

Bank account. If it is necessary to pass the autotransfer:true field, it is mandatory to enter the bank details.

emailOptOut
boolean
Default: false

Defines if the account will receive emails from Juno.

autoTransfer
boolean
Default: false

Defines if the transference will be done automatically.

socialName
boolean
Default: false

Defines if the attribute name can receive different kinds of names.

monthlyIncomeOrRevenue
number <1000.00>

Monthly income or income. Mandatory.

cnae
string 7 characters

Field destined to the CNAE (National Classification of Economic Activities) of the company. Mandatory for PJ.

establishmentDate
string

Company opening date. Mandatory for PJ.

pep
boolean

Defines whether the record belongs to a politically exposed person.

companyMembers
Array of objects (CompanyMembers)

Corporate structure of the company. Mandatory for PJ accounts of companyType SA and LTDA.

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

post /digital-accounts/
https://api.ebanxpay.com/digital-accounts/
https://sandbox.ebanxpay.com/digital-accounts/

Request samples

Content type
application/json;charset=UTF-8
Copy
 Expand all Collapse all
{
  • "type": "PAYMENT",
  • "name": "string",
  • "document": "stringstrin",
  • "email": "string",
  • "birthDate": "yyyy-MM-dd",
  • "phone": "string",
  • "businessArea": 0,
  • "linesOfBusiness": "string",
  • "companyType": "MEI",
  • "legalRepresentative":
    {
    },
  • "address":
    {
    },
  • "bankAccount":
    {
    },
  • "emailOptOut": false,
  • "autoTransfer": false,
  • "socialName": false,
  • "monthlyIncomeOrRevenue": 0,
  • "cnae": "strings",
  • "establishmentDate": "string",
  • "pep": true,
  • "companyMembers":
    [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "type": "string",
  • "status": "AWAITING_DOCUMENTS",
  • "personType": null,
  • "document": "string",
  • "createdOn": "yyyy-MM-dd HH:mm:ss",
  • "resourceToken": "string",
  • "_links":
    [
    ]
}

Get digital account

For detailed guidance on this endpoint, access our Integration Guide by clicking here

Returns data from the digital account identified by its X-Resource-Token.

The id returned is used to identify the account in the resource transfer.

header Parameters
X-Api-Version
required
integer
Value: 2

API Version

X-Resource-Token
required
string
Example: <resource-token>

Resource token to be used in the operation.

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

get /digital-accounts/
https://api.ebanxpay.com/digital-accounts/
https://sandbox.ebanxpay.com/digital-accounts/

Response samples

Content type
application/json;charset=UTF-8
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "type": "string",
  • "status": "AWAITING_DOCUMENTS",
  • "personType": null,
  • "document": "string",
  • "createdOn": "yyyy-MM-dd HH:mm:ss",
  • "_links":
    [
    ]
}

Update digital account (payment)

For detailed guidance on this endpoint, access our Integration Guide by clicking here

Update data from a digital payment account.

The following information will be updated during the request:

  • Contact Email and Telephone
  • Address Information
  • Bank Details

Some data cannot be instantly updated during the call via API, as they depend on an analysis by Juno's internal areas, namely:

  • Name and date of Birth
  • Legal Representative Data
  • Corporate Name
  • Area and Line of Business
  • Type of Company

Our team will be informed of the changes and will perform them shortly.

The data fields informed in the request are optional, and will only be updated if they are sent.

If an account is created with an incorrect document number (CPF/CNPJ) it is necessary to create a new account. It is not possible to change this data.

Important: to update any of the data that make up the object of this request, only the data to be altered must be informed, otherwise the alteration of these fields will be ignored.

header Parameters
X-Api-Version
required
integer
Value: 2

API Version

X-Resource-Token
required
string
Example: <resource-token>

Resource token to be used in the operation.

Request Body schema: application/json;charset=UTF-8
companyType
required
string
Enum: "MEI" "EI" "EIRELI" "LTDA" "SA" "INSTITUITION_NGO_ASSOCIATION"

Defines the nature of the business. Required for PJ accounts. For allowed values, see voltar aqui

name
required
string <= 80 characters

Digital Account Name.

birthDate
required
string <date> 10 characters

Date of birth. Mandatory for PF accounts.

linesOfBusiness
required
string <= 100 characters

Defines the company's line of business.

email
required
string <= 80 characters

Digital Account Email.

phone
required
string <= 16 characters

Digital Account Phone.

businessArea
required
number <int64> <= 4 characters

Defines the company's business area. To see the allowed values, see voltar aqui

tradingName
required
string [ 0 .. 80 ] characters

Fantasy name. Optional for PJ.

address
required
object (Address)

Endereço.

bankAccount
required
object (BankAccount)

Bank account. If it is necessary to pass the autotransfer:true field, it is mandatory to enter the bank details.

legalRepresentative
required
object (LegalRepresentative)

Legal Representative. Required for PJ accounts.

Responses

200

Success

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

patch /digital-accounts/
https://api.ebanxpay.com/digital-accounts/
https://sandbox.ebanxpay.com/digital-accounts/

Request samples

Content type
application/json;charset=UTF-8
Copy
 Expand all Collapse all
{
  • "companyType": "MEI",
  • "name": "string",
  • "birthDate": "yyyy-MM-dd",
  • "linesOfBusiness": "string",
  • "email": "string",
  • "phone": "string",
  • "businessArea": 1003,
  • "tradingName": "string",
  • "address":
    {
    },
  • "bankAccount":
    {
    },
  • "legalRepresentative":
    {
    }
}

Response samples

Content type
application/json;charset=UTF-8
Copy
 Expand all Collapse all
{
  • "id": "string",
  • "type": "string",
  • "status": "AWAITING_DOCUMENTS",
  • "personType": null,
  • "document": "string",
  • "createdOn": "yyyy-MM-dd HH:mm:ss",
  • "_links":
    [
    ]
}