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",
- "due_date": "2018-04-28",
- "instalments": 1,
- "payment_type_code": "_all",
- "pre_approved": false,
- "capture_available": null,
}
}
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",
...
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:
|
OK
{- "integration_key": "your_test_integration_key",
- "country": "co"
}
[- {
- "code": "nequi",
- "name": "Nequi",
- "promotional_text": "¡Texto promocional de prueba!"
}
]
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.
Payment body object
integration_key required | string [ 1 .. 100 ] characters Your unique and secret integration key. |
operation required | string 7 characters Must be |
mode required | string 4 characters Currently only |
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) |
OK
{- "integration_key": "\\ {Your integration key}",
- "operation": "request",
- "mode": "full",
- "payment": {
- "name": "José Silva",
- "email": "jose@example.com",
- "document": "853.513.468-93",
- "customer_ip": "string",
- "address": "Rua E",
- "street_number": "1040",
- "street_complement": "string",
- "city": "Maracanau",
- "state": "CE",
- "zipcode": "61919-230",
- "country": "BR",
- "phone_number": 8522847035,
- "payment_type_code": "creditcard",
- "merchant_payment_code": "3ad1f4096a2",
- "user_value_1": "string",
- "user_value_2": "string",
- "user_value_3": "string",
- "user_value_4": "string",
- "user_value_5": "string",
- "due_date": "stringstri",
- "create_token": true,
- "token": "stringstringstringstringstringst",
- "currency_code": "BRL",
- "instalments": "3",
- "amount_total": "100",
- "creditcard": {
- "card_number": "4111111111111111",
- "card_name": "José Silva",
- "card_due_date": "12/2019",
- "card_cvv": "123",
- "auto_capture": true,
- "token": "string"
}, - "note": "string",
- "sub_account": {
- "name": "string",
- "image_url": "string"
}, - "items": {
- "sku": "string",
- "name": "string",
- "description": "string",
- "unit_price": 0,
- "quantity": 0,
- "type": "string"
}, - "device_id": "string",
- "eft_code": "string",
- "notification_url": "string",
- "redirect_url": "string",
- "person_type": "business",
- "responsible": {
- "name": "string"
}
}
}
{- "payment": {
- "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
- "country": "ar",
- "merchant_payment_code": "ecc9be4512a",
- "order_number": null,
- "status": "CO",
- "status_date": "2017-09-04 14:11:12",
- "open_date": "2017-09-04 14:11:11",
- "confirm_date": "2017-09-04 14:11:12",
- "transfer_date": null,
- "amount_br": "376.00",
- "amount_ext": "100.00",
- "amount_iof": "0.00",
- "currency_rate": "3.7600",
- "currency_ext": "USD",
- "due_date": "2017-09-07",
- "instalments": "3",
- "payment_type_code": "visa",
- "details": {
- "billing_descriptor": "TP * EBANX S.A."
}, - "transaction_status": {
- "acquirer": "EBANX",
- "code": "OK",
- "description": "Sandbox - Test credit card, transaction captured"
}, - "pre_approved": true,
- "capture_available": false
}, - "status": "SUCCESS"
}
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.
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. |
OK
{- "integration_key": "your_test_integration_key",
- "hash": "5478ba283ef8674415082844ee14817376e49bb76aa9d4c7",
- "merchant_payment_code": "126378126",
- "merchant_capture_code": "string",
- "amount": 0
}
{- "payment": {
- "hash": "5478ba283ef8674415082844ee14817376e49bb76aa9d4c7",
- "merchant_payment_code": "126378126",
- "order_number": null,
- "status": "CO",
- "status_date": "2014-11-28 16:09:19",
- "open_date": "2014-11-28 16:08:39",
- "confirm_date": "2014-11-28 16:09:19",
- "transfer_date": null,
- "amount_br": "100.00",
- "amount_ext": "100.00",
- "amount_iof": "0.00",
- "currency_rate": "1.0000",
- "currency_ext": "BRL",
- "due_date": "2014-12-05",
- "instalments": "1",
- "payment_type_code": "visa",
- "transaction_status": {
- "acquirer": "EBANX",
- "code": "OK",
- "description": "Cartão de teste autorizado - aguardando captura",
- "authcode": "12345"
}, - "pre_approved": true,
- "capture_available": false
}, - "status": "SUCCESS"
}
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.
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). |
OK
{- "integration_key": "your_test_integration_key",
- "hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9"
}
{- "payment": {
- "hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9",
- "merchant_payment_code": "1461416920319",
- "order_number": "146",
- "status": "CA",
- "status_date": "2014-11-26 17:34:11",
- "open_date": "2014-11-25 10:45:56",
- "confirm_date": null,
- "transfer_date": null,
- "amount_br": "204.45",
- "amount_ext": "87.00",
- "amount_iof": "0.00",
- "currency_rate": "2.3500",
- "currency_ext": "USD",
- "due_date": "2014-12-2",
- "instalments": "1",
- "payment_type_code": "boleto",
- "pre_approved": false,
- "capture_available": null
}, - "operation": "cancel",
- "status": "SUCCESS"
}
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.
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) 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 |
OK
{- "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": {
- "bank_name": "104 Caixa Econômica",
- "bank_branch": "00001-2",
- "bank_account": "08251777-6",
- "account_type": "C",
- "bank_details": 1,
- "bank_account_holder_document": 85351346893,
- "bank_account_holder_name": "José Silva"
}
}
{- "payment": {
- "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
- "country": "br",
- "merchant_payment_code": "9dwdwdw1e31c4c234",
- "order_number": null,
- "status": "CO",
- "status_date": "2018-04-19 20:57:07",
- "open_date": "2018-04-19 20:56:42",
- "confirm_date": "2018-04-19 20:57:07",
- "transfer_date": null,
- "amount_br": "100.38",
- "amount_ext": "100.00",
- "amount_iof": "0.38",
- "currency_rate": "1.0000",
- "currency_ext": "BRL",
- "due_date": "2018-04-22",
- "instalments": "1",
- "payment_type_code": "itau",
- "pre_approved": false,
- "capture_available": null,
- "refunds": [
- {
- "id": "68682",
- "merchant_refund_code": null,
- "status": "RE",
- "request_date": "2018-04-19 21:00:06",
- "pending_date": null,
- "confirm_date": null,
- "cancel_date": null,
- "amount_ext": "100.00",
- "description": "Testing notifications"
}
]
}, - "status": "SUCCESS"
}
The resend refund bank info is a server-to-server operation to update the bank info data in a existing refund.
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) 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 |
OK
{- "integration_key": "your_test_integration_key",
- "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
- "merchant_refund_code": 787653,
- "refund_id": 3784756,
- "bank_info": {
- "bank_name": "104 Caixa Econômica",
- "bank_branch": "00001-2",
- "bank_account": "08251777-6",
- "account_type": "C",
- "bank_details": 1,
- "bank_account_holder_document": 85351346893,
- "bank_account_holder_name": "José Silva"
}
}
{- "payment": {
- "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
- "country": "br",
- "merchant_payment_code": "9dwdwdw1e31c4c234",
- "order_number": null,
- "status": "CO",
- "status_date": "2018-04-19 20:57:07",
- "open_date": "2018-04-19 20:56:42",
- "confirm_date": "2018-04-19 20:57:07",
- "transfer_date": null,
- "amount_br": "100.38",
- "amount_ext": "100.00",
- "amount_iof": "0.38",
- "currency_rate": "1.0000",
- "currency_ext": "BRL",
- "due_date": "2018-04-22",
- "instalments": "1",
- "payment_type_code": "itau",
- "pre_approved": false,
- "capture_available": null,
- "refunds": [
- {
- "id": "68682",
- "merchant_refund_code": null,
- "status": "RE",
- "request_date": "2018-04-19 21:00:06",
- "pending_date": null,
- "confirm_date": null,
- "cancel_date": null,
- "amount_ext": "100.00",
- "description": "Testing notifications"
}
]
}, - "operation": "updatecustomerbankinfo",
- "status": "SUCCESS"
}
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:
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. |
OK
{- "integration_key": "your_test_integration_key",
- "hash": "5ad9028b30eb8de099f9fe72b9763283c7cf4d35b6430221",
- "description": "Order did not arrive",
- "merchant_refund_code": 787653
}
{- "payment": {
- "hash": "5476099e890c06ca6f02cae9da1b1faaf3c5929439076cb9",
- "merchant_payment_code": "1461416920319",
- "order_number": "146",
- "status": "CA",
- "status_date": "2014-11-26 17:34:11",
- "open_date": "2014-11-25 10:45:56",
- "confirm_date": null,
- "transfer_date": null,
- "amount_br": "204.45",
- "amount_ext": "87.00",
- "amount_iof": "0.00",
- "currency_rate": "2.3500",
- "currency_ext": "USD",
- "due_date": "2014-12-2",
- "instalments": "1",
- "payment_type_code": "boleto",
- "pre_approved": false,
- "capture_available": null
}, - "operation": "cancel",
- "status": "SUCCESS"
}
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.
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. |
OK
curl --request GET 'https://api.ebanxpay.com/ws/cardbin/?integration_key={your_integration_key}&country=MX'
{- "numberOfBins": 3,
- "binList": [
- {
- "bin": "506323",
- "cardBrand": "MASTERCARD",
- "isoCountryA2": "BR",
- "cardType": "DEBIT",
- "fullBankName": "ITAU UNIBANCO S.A"
}, - {
- "bin": "445017",
- "cardBrand": "VISA",
- "isoCountryA2": "BR",
- "cardType": "DEBIT"
}, - {
- "bin": "542861",
- "cardBrand": "MASTERCARD",
- "isoCountryA2": "BR",
- "cardType": "CREDIT",
- "fullBankName": "NUBANK"
}
]
}
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.
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. |
OK
{- "integration_key": "your_test_integration_key",
- "operation": "request",
- "country": "co"
}
[- {
- "code": "banco_agrario",
- "name": "BANCO AGRARIO"
}, - {
- "code": "banco_av_villas",
- "name": "BANCO AV VILLAS"
}, - {
- "code": "banco_bbva_colombia_s.a.",
- "name": "BANCO BBVA COLOMBIA S.A."
}, - {
- "code": "banco_caja_social",
- "name": "BANCO CAJA SOCIAL"
}, - {
- "code": "banco_colpatria",
- "name": "BANCO COLPATRIA"
}, - {
- "code": "banco_cooperativo_coopcentral",
- "name": "BANCO COOPERATIVO COOPCENTRAL"
}, - {
- "code": "banco_corpbanca_s.a",
- "name": "BANCO CORPBANCA S.A"
}, - {
- "code": "banco_davivienda",
- "name": "BANCO DAVIVIENDA"
}, - {
- "code": "banco_de_bogota",
- "name": "BANCO DE BOGOTA"
}, - {
- "code": "banco_de_occidente",
- "name": "BANCO DE OCCIDENTE"
}, - {
- "code": "banco_falabella_",
- "name": "BANCO FALABELLA "
}, - {
- "code": "banco_gnb_sudameris",
- "name": "BANCO GNB SUDAMERIS"
}, - {
- "code": "banco_pichincha_s.a.",
- "name": "BANCO PICHINCHA S.A."
}, - {
- "code": "banco_popular",
- "name": "BANCO POPULAR"
}, - {
- "code": "banco_procredit",
- "name": "BANCO PROCREDIT"
}, - {
- "code": "bancolombia",
- "name": "BANCOLOMBIA"
}, - {
- "code": "bancoomeva_s.a.",
- "name": "BANCOOMEVA S.A."
}, - {
- "code": "citibank_",
- "name": "CITIBANK "
}, - {
- "code": "helm_bank_s.a.",
- "name": "HELM BANK S.A."
}
]
The query operation is a server-to-server HTTP POST used by the merchant website to query EBANX for information about a specific payment.
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. |
merchant_payment_code | string [ 1 .. 40 ] characters The payment hash Merchant Payment Code (unique merchant ID). Required if hash not provided. |
OK
{- "integration_key": "your_test_integration_key",
- "hash": "5478ba283ef8674415082844ee14817376e49bb76aa9d4c7",
- "merchant_payment_code": "1416854121"
}
{- "status": "SUCCESS",
- "payment": {
- "hash": "54737a76ffc1e5a520b0ed9062213a810ef41dae990184c7",
- "merchant_payment_code": "1416854121",
- "order_number": null,
- "status": "CO",
- "status_date": "2014-11-24 16:35:43",
- "open_date": "2014-11-24 16:35:34",
- "confirm_date": "2014-11-24 16:35:43",
- "transfer_date": null,
- "amount_br": "352.50",
- "amount_ext": "150.00",
- "amount_iof": "0.00",
- "currency_rate": "2.3500",
- "currency_ext": "USD",
- "due_date": "2014-12-01",
- "instalments": "1",
- "payment_type_code": "bradesco",
- "pre_approved": false,
- "capture_available": null,
- "refunds": [
- {
- "id": "9283",
- "merchant_refund_code": null,
- "status": "RE",
- "request_date": "2014-11-26 17:56:52",
- "pending_date": null,
- "confirm_date": null,
- "cancel_date": null,
- "paid_date": null,
- "amount_ext": "100.00",
- "description": "Order did not arrive",
- "settlement": {
- "transfer_date": "2014-12-01",
- "amount": 100
}, - "refund_status_details": {
- "cancellation_reason": "Not Paid: refund payment period has been exceed",
- "cancellation_reason_code": "RSD-01",
- "can_have_settlement": true,
- "can_be_cancelled": false
}
}
], - "improper_payment_refunds": [
- {
- "paid_date": "2024-09-08 16:15:12",
- "email_send_date": "2024-09-05 19:40:27",
- "create_date": "2024-09-05 19:32:38",
- "amount_local": "0.01",
- "description": "unconfirmed",
}
]
}
}
You can use the print method to show a printable slip for the supported (cash) payment methods.
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). |
OK
{- "hash": "54737a76ffc1e5a520b0ed9062213a810ef41dae990184c7",
- "format": "pdf"
}
{- "say": "hello world"
}
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.
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:
|
amount required | number Example: amount=100 The total amount in the specified currency (currency_code). |
OK
curl --location --request GET 'https://sandbox.ebanx.com/ws/instalmentsPlan/?country_abbreviation=br&integration_key={{your_integration_key}}¤cy_code=BRL&amount=1599.99&bin=411111' \
{- "instalmentsPlan": [
- {
- "totalAmount": "1606.07",
- "quantity": 1,
- "instalmentAmount": 1606.07,
- "appliedFee": 0
}, - {
- "totalAmount": "1655.74",
- "quantity": 2,
- "instalmentAmount": 827.87,
- "appliedFee": 0.03
}, - {
- "totalAmount": "1672.99",
- "quantity": 3,
- "instalmentAmount": 557.66,
- "appliedFee": 0.04
}, - {
- "totalAmount": "1690.6",
- "quantity": 4,
- "instalmentAmount": 422.65,
- "appliedFee": 0.05
}, - {
- "totalAmount": "1708.59",
- "quantity": 5,
- "instalmentAmount": 341.72,
- "appliedFee": 0.06
}, - {
- "totalAmount": "1726.96",
- "quantity": 6,
- "instalmentAmount": 287.83,
- "appliedFee": 0.07
}, - {
- "totalAmount": "1745.73",
- "quantity": 7,
- "instalmentAmount": 249.39,
- "appliedFee": 0.08
}, - {
- "totalAmount": "1764.91",
- "quantity": 8,
- "instalmentAmount": 220.61,
- "appliedFee": 0.09
}, - {
- "totalAmount": "1784.53",
- "quantity": 9,
- "instalmentAmount": 198.28,
- "appliedFee": 0.1
}, - {
- "totalAmount": "1804.57",
- "quantity": 10,
- "instalmentAmount": 180.46,
- "appliedFee": 0.11
}, - {
- "totalAmount": "1825.08",
- "quantity": 11,
- "instalmentAmount": 165.92,
- "appliedFee": 0.12
}, - {
- "totalAmount": "1846.06",
- "quantity": 12,
- "instalmentAmount": 153.84,
- "appliedFee": 0.13
}
], - "bin": {
- "bin": "411111",
- "brand": "VISA",
- "country": "BR"
}
}
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.
This method allows you to create a payout.
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.
|
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:
|
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:
|
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.
|
target_account | string Account information is required for the following targets:
|
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) |
OK
invalid input, object invalid
an existing item already exists
{- "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": {
- "name": "Han Solo",
- "email": "chew@bac.ca",
- "phone": "+554112345678",
- "document": 85351346893,
- "document_type": "CPF",
- "birthdate": "1977-05-25",
- "terms_accepted_at": "2020-05-25 17:35:47",
- "bank_info": {
- "bank_name": "341 Itaú",
- "bank_branch": "3707",
- "bank_account": "01854-9",
- "account_type": "C",
- "bank_details": "001"
}, - "address": {
- "zipcode": "string",
- "state": "string",
- "city": "string",
- "street_address": "string",
- "street_complement": "string"
}, - "shareholder": [
- {
- "name": "Jose Silva",
- "email": "luke@bac.ca",
- "document": 85351346892,
- "birth_date": "1977-07-23",
- "ownership_percent": 0
}
]
}
}
{- "type": "success",
- "payout": {
- "uid": "0e495f7a4409c032d54376084b10b9c771e9b39f0",
- "external_reference": "PAYOUT_EBANX_04",
- "status": "OP",
- "request_date": "2017-02-07 20:00:15",
- "status_date": null,
- "paid_date": null,
- "cancel_date": null,
- "payee": {
- "name": "Han Solo",
- "email": "chew@bac.ca",
- "phone": " 554112345678",
- "document": "85351346893",
- "document_type": "CPF",
- "birthdate": "1977-05-25",
- "bank_info": {
- "bank_name": "104 Caixa Econômica",
- "bank_branch": "3708",
- "bank_account": "08251777-6",
- "account_type": "C",
- "bank_details": "001"
}
}, - "request_amount": "10.00",
- "request_currency": "USD",
- "request_exchange_rate": "1.0000",
- "debit_amount": "10.00",
- "debit_fee": "0.15",
- "debit_amount_total": "10.15",
- "debit_currency": "USD",
- "order_number": "ABCD_-123",
- "target": "bank_account"
}
}
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.
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. |
uid | string <= 50 characters The payout uid (EBANX unique identifier). |
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "external_reference": "PAYOUT_EBANX_01",
- "uid": "0f28f5b2bf60536d78b2dbf003c13886dd452d926"
}
{- "type": "success",
- "message": "You've successfully cancelled your Payout!"
}
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
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. |
uid | string <= 50 characters The payout uid (EBANX unique identifier). |
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "external_reference": "PAYOUT_EBANX_01",
- "uid": "0f28f5b2bf60536d78b2dbf003c13886dd452d926"
}
{- "type": "success",
- "message": "You've successfully started the Payout payment process!"
}
This method allows you to retrieve a payout information.
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. |
uid | string <= 50 characters The payout uid (EBANX unique identifier). |
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "external_reference": "PAYOUT_EBANX_01",
- "uid": "0f28f5b2bf60536d78b2dbf003c13886dd452d926"
}
{- "type": "success",
- "payout": {
- "uid": "0f28f5b2bf60536d78b2dbf003c13886dd452d926",
- "external_reference": "PAYOUT_EBANX_ACCOUNT_01",
- "status": "PA",
- "request_date": "2017-02-07 17:01:59",
- "status_date": "2017-02-07 17:03:15",
- "paid_date": "2017-02-07 17:03:15",
- "cancel_date": null,
- "payee": {
- "name": "Han Solo",
- "email": "chew@bac.ca",
- "phone": " 554112345678",
- "document": "08271284959",
- "document_type": "CPF",
- "birthdate": "1977-05-25",
- "bank_info": null
}, - "request_amount": "10.00",
- "request_currency": "USD",
- "request_exchange_rate": "1.0000",
- "debit_amount": "10.00",
- "debit_fee": "0.15",
- "debit_amount_total": "10.15",
- "debit_currency": "USD",
- "target": "ebanx_wallet"
}
}
This method allows you to simulate a payout.
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:
|
amount required | number The amount in the specified currency ( |
currency_code required | string Three-letter code of the payout currency. Supported currencies:
|
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "country": "br",
- "amount": 100,
- "currency_code": "string"
}
{- "type": "success",
- "payout": {
- "request_amount": "10",
- "request_currency": "USD",
- "request_exchange_rate": 1,
- "debit_amount": 10,
- "debit_fee": 0.3,
- "debit_amount_total": 10.3,
- "debit_currency": "USD"
}
}
This method allows you to retrieve multiple payouts information.
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 |
date_to required | string 10 characters End date in the format |
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:
|
per_page | integer Max number of payouts per page (API Max: 50) |
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "date_from": "1977-05-25",
- "date_to": "1977-05-26",
- "page": 2,
- "status": "OP",
- "per_page": 20
}
{- "type": "success",
- "records": "5",
- "total_pages": 1,
- "per_page": 50,
- "page": 1,
- "payouts": [
- {
- "uid": "0f28f5b2bf60536d78b2dbf003c13886dd452d926",
- "external_reference": "PAYOUT_EBANX_01",
- "status": "PA",
- "request_date": "2017-02-07 17:01:59",
- "status_date": "2017-02-07 17:03:15",
- "paid_date": "2017-02-07 17:03:15",
- "cancel_date": null,
- "payee": {
- "name": "Han Solo",
- "email": "chew@bac.ca",
- "phone": " 554112345678",
- "document": "85351346893",
- "document_type": "CPF",
- "birthdate": "1977-05-25",
- "bank_info": null
}, - "request_amount": "10.00",
- "request_currency": "USD",
- "request_exchange_rate": "1.0000",
- "debit_amount": "10.00",
- "debit_fee": "0.15",
- "debit_amount_total": "10.15",
- "debit_currency": "USD",
- "target": "ebanx_wallet"
}, - {
- "uid": "07af7cd0fd2f64a4953cc707bf09811ddf83ec090",
- "external_reference": "PAYOUT_EBANX_02",
- "status": "PE",
- "request_date": "2017-02-07 17:11:43",
- "status_date": "2017-02-07 17:12:46",
- "paid_date": null,
- "cancel_date": null,
- "payee": {
- "name": "Han Solo",
- "email": "chew@bac.ca",
- "phone": " 554112345678",
- "document": "85351346893",
- "document_type": "CPF",
- "birthdate": "1977-05-25",
- "bank_info": null
}, - "request_amount": "10.00",
- "request_currency": "USD",
- "request_exchange_rate": "1.0000",
- "debit_amount": "10.00",
- "debit_fee": "0.15",
- "debit_amount_total": "10.15",
- "debit_currency": "USD",
- "target": "bank_account"
}, - {
- "uid": "0bf887fdadeef424a857c2bff69b94db0fb77f071",
- "external_reference": "PAYOUT_EBANX_03",
- "status": "PE",
- "request_date": "2017-02-07 19:45:38",
- "status_date": "2017-02-07 19:46:38",
- "paid_date": null,
- "cancel_date": null,
- "payee": {
- "name": "Han Solo",
- "email": "chew@bac.ca",
- "phone": " 554112345678",
- "document": "85351346893",
- "document_type": "CPF",
- "birthdate": "1977-05-25",
- "bank_info": {
- "bank_name": "341 Itaú",
- "bank_branch": "3707",
- "bank_account": "01854-9",
- "account_type": "C",
- "bank_details": null
}
}, - "request_amount": "10.00",
- "request_currency": "USD",
- "request_exchange_rate": "1.0000",
- "debit_amount": "10.00",
- "debit_fee": "0.15",
- "debit_amount_total": "10.15",
- "debit_currency": "USD",
- "target": "bank_account"
}, - {
- "uid": "0e495f7a4409c032d54376084b10b9c771e9b39f0",
- "external_reference": "PAYOUT_EBANX_04",
- "status": "PE",
- "request_date": "2017-02-07 20:00:15",
- "status_date": "2017-02-07 20:01:15",
- "paid_date": null,
- "cancel_date": null,
- "payee": {
- "name": "Han Solo",
- "email": "chew@bac.ca",
- "phone": " 554112345678",
- "document": "85351346893",
- "document_type": "CPF",
- "birthdate": "1977-05-25",
- "bank_info": {
- "bank_name": "104 Caixa Econômica",
- "bank_branch": "3708",
- "bank_account": "08251777-6",
- "account_type": "C",
- "bank_details": "001"
}
}, - "request_amount": "10.00",
- "request_currency": "USD",
- "request_exchange_rate": "1.0000",
- "debit_amount": "10.00",
- "debit_fee": "0.15",
- "debit_amount_total": "10.15",
- "debit_currency": "USD",
- "target": "bank_account"
}, - {
- "uid": "088d8930148d84205a82efddb53f9a6c003a122c1",
- "external_reference": "PAYOUT_EBANX_05",
- "status": "PA",
- "request_date": "2017-02-07 20:31:44",
- "status_date": "2017-02-07 20:32:52",
- "paid_date": "2017-02-07 20:32:52",
- "cancel_date": null,
- "payee": {
- "name": "Han Solo",
- "email": "chew@bac.ca",
- "phone": " 554112345678",
- "document": null,
- "document_type": null,
- "birthdate": "1977-05-25",
- "bank_info": null
}, - "request_amount": "10.00",
- "request_currency": "USD",
- "request_exchange_rate": "1.0000",
- "debit_amount": "10.00",
- "debit_fee": "0.30",
- "debit_amount_total": "10.30",
- "debit_currency": "USD",
- "target": "ebanx_wallet"
}
]
}
This method allows you to get your available balance.
Exchange body object
integration_key required | string <= 100 characters Your unique and secret integration key. |
OK
invalid input, object invalid
an item already exists
{- "integration_key": "your_test_integration_key"
}
{- "type": "success",
- "balance": 150
}
The bank operation method call will return a JSON object with the all the available banks per country.
OK
invalid input, object invalid
an existing item already exists
curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/banks'
{- "type": "success",
- "argentina": {
- "389": "BANCO COLUMBIA S.A.",
- "005": "AMBN AMRO BANK N. V."
}, - "bolivia": [
- "10001 Banco de Desarrollo Productivo S.A.M.",
- "74003 Banco PYME de la Comunidad S.A."
], - "brazil": [
- "104 Caixa Econômica",
- "001 Banco do Brasil"
], - "chile": [
- "001 BANCO DE CHILE",
- "504 SCOTIABANK AZUL (BBVA)"
], - "colombia": [
- "1040 Banco Agrario",
- "1014 Helm Bank S.A"
], - "ecuador": [
- "BANCO AMAZONAS S.A.",
- "BANCO DINERS CLUB DEL ECUADOR"
], - "mexico": {
- "168": "HIFED - HIPOTECARIA FEDERAL",
- "001": "BANCO - BANXICO"
}, - "peru": [
- "BCP - BANCO DE CREDITO DO PERU",
- "INTERBANK"
]
}
This method call will return a JSON object with all the available bank details information per country.
OK
invalid input, object invalid
an existing item already exists
curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/bankdetails'
{- "type": "success",
- "brazil": {
- "104 Caixa Econômica": {
- "description": "Number of the operation required by Caixa Econômica",
- "values": [
- "001",
- "002",
- "003",
- "006",
- "007",
- "013",
- "022",
- "023",
- "028",
- "043"
]
}
}, - "colombia": {
- "_all": {
- "description": "Name of the city of account holder",
- "values": [
- "APARTADO",
- "VILLAVICENCIO"
]
}
}
}
This method allows you to create a pyee record.
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.
|
document_type required | string <= 5 characters Enum: "CPF" "CNPJ" "RUT" Payee national identification number type.
|
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.
|
bank_details | string Additional information of the bank account.
|
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:
|
shareholder | Array of objects Array of objects describing each shareholder
|
OK
invalid input, object invalid
an existing item already exists
{- "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": [
- {
- "name": "Jose Silva",
- "email": "luke@bac.ca",
- "document": 85351346892,
- "birth_date": "1977-07-23",
- "zipcode": "string",
- "state": "string",
- "city": "string",
- "address": "string",
- "complement": "string",
- "ownership_percent": 0
}
]
}
{- "id": "100"
}
This method allows you to validate an account.
Verify account body object
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:
|
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 |
OK
{- "integration_key": "your_test_integration_key",
- "country": "br",
- "target": "mercadopago",
- "target_account": "janedoe@someone.co"
}
{- "status": "valid",
- "message": "Account is valid"
}
This method allows you to request a dozen of payouts from a single file request
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_\-. |
OK
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'
{- "mass_payout_id": 123456
}
This method allows you to create a transfer request.
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 ( |
source | string Transfer source. Supported sources:
Default value is |
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "external_reference": "PAYOUT_TRANSFER_01",
- "amount": 100,
- "source": "payment_balance"
}
{- "type": "success",
- "transfer": {
- "uid": "11ce3097af9ccf601b11038123962d3feded348ed",
- "external_reference": "PAYOUT_TRANSFER_02",
- "status": "OP",
- "request_date": "2017-02-08 17:33:56",
- "confirm_date": null,
- "cancel_date": null,
- "amount": "150.00",
- "settlement_code": null,
- "source": "payment_balance"
}
}
This method allows you to cancel a transfer request.
You have to send either the transfer_code, uid, settlement_code or external_reference.
Payout body object
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). |
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "external_reference": "PAYOUT_TRANSFER_01",
- "transfer_code": "14-2000",
- "settlement_code": "14-2000",
- "uid": "11ce3097af9ccf601b11038767962d3feded348ed"
}
{- "type": "success",
- "message": "You've successfully cancelled your Transfer!"
}
This method allows you to retrieve a transfer information.
You have to send either the transfer_code, uid, settlement_code or external_reference.
Payout body object
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). |
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "external_reference": "PAYOUT_TRANSFER_01",
- "transfer_code": "14-2000",
- "settlement_code": "14-2000",
- "uid": "11ce3097af9ccf601b11038767962d3feded348ed"
}
{- "type": "success",
- "transfer": {
- "uid": "11ce3097af9ccf601b11038123962d3feded348ed",
- "external_reference": "PAYOUT_TRANSFER_02",
- "status": "OP",
- "request_date": "2017-02-08 17:33:56",
- "confirm_date": null,
- "cancel_date": null,
- "amount": "150.00",
- "settlement_code": "14-2001",
- "source": "payment_balance"
}
}
This method allows you to retrieve multiple transfers information.
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 |
date_to required | string 10 characters End date in the format |
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:
|
per_page | integer Max number of transfers per page (API Max: 50) |
OK
invalid input, object invalid
an existing item already exists
{- "integration_key": "your_test_integration_key",
- "date_from": "1977-05-25",
- "date_to": "1977-05-26",
- "page": 2,
- "status": "OP",
- "per_page": 20
}
{- "type": "success",
- "records": "2",
- "total_pages": 1,
- "per_page": 50,
- "page": 1,
- "transfers": [
- {
- "uid": "11ce3097af9ccf601b11038767962d3feded348ed",
- "external_reference": "PAYOUT_TRANSFER_01",
- "status": "OP",
- "request_date": "2017-02-08 17:33:56",
- "confirm_date": null,
- "cancel_date": null,
- "amount": "100.00",
- "transfer_code": "14-2000",
- "source": "wire_transfer"
}, - {
- "uid": "11ce3097af9ccf601b11038123962d3feded348ed",
- "external_reference": "PAYOUT_TRANSFER_02",
- "status": "OP",
- "request_date": "2017-02-08 17:33:56",
- "confirm_date": null,
- "cancel_date": null,
- "amount": "150.00",
- "settlement_code": null,
- "source": "payment_balance"
}
]
}
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:
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.
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.
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. |
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 |
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 |
Success
Bad Request
Unauthorized
Forbidden
Internal Server Error
{- "type": "PAYMENT",
- "name": "string",
- "document": "stringstrin",
- "email": "string",
- "birthDate": "yyyy-MM-dd",
- "phone": "string",
- "businessArea": 0,
- "linesOfBusiness": "string",
- "companyType": "MEI",
- "legalRepresentative": {
- "name": "string",
- "document": "string",
- "birthDate": "yyyy-MM-dd",
- "motherName": "string",
- "type": "INDIVIDUAL"
}, - "address": {
- "street": "string",
- "number": "string",
- "complement": "string",
- "neighborhood": "string",
- "city": "string",
- "state": "string",
- "postCode": "string"
}, - "bankAccount": {
- "bankNumber": "string",
- "agencyNumber": "string",
- "accountNumber": "string",
- "accountComplementNumber": "001",
- "accountType": "CHECKING",
- "accountHolder": {
- "name": "string",
- "document": "stringstrin"
}
}, - "emailOptOut": false,
- "autoTransfer": false,
- "socialName": false,
- "monthlyIncomeOrRevenue": 0,
- "cnae": "strings",
- "establishmentDate": "string",
- "pep": true,
- "companyMembers": [
- {
- "name": "string",
- "document": null,
- "birthDate": "stringstri"
}
]
}
{- "id": "string",
- "type": "string",
- "status": "AWAITING_DOCUMENTS",
- "personType": null,
- "document": "string",
- "createdOn": "yyyy-MM-dd HH:mm:ss",
- "resourceToken": "string",
- "_links": [
- {
- "self": {
- "href": "string"
}
}
]
}
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. |
Success
Bad Request
Unauthorized
Forbidden
Internal Server Error
{- "id": "string",
- "type": "string",
- "status": "AWAITING_DOCUMENTS",
- "personType": null,
- "document": "string",
- "createdOn": "yyyy-MM-dd HH:mm:ss",
- "_links": [
- {
- "self": {
- "href": "string"
}
}
]
}
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:
Some data cannot be instantly updated during the call via API, as they depend on an analysis by Juno's internal areas, namely:
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.
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. |
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 |
legalRepresentative required | object (LegalRepresentative) Legal Representative. Required for PJ accounts. |
Success
Bad Request
Unauthorized
Forbidden
Internal Server Error
{- "companyType": "MEI",
- "name": "string",
- "birthDate": "yyyy-MM-dd",
- "linesOfBusiness": "string",
- "email": "string",
- "phone": "string",
- "businessArea": 1003,
- "tradingName": "string",
- "address": {
- "street": "string",
- "number": "string",
- "complement": "string",
- "neighborhood": "string",
- "city": "string",
- "state": "string",
- "postCode": "string"
}, - "bankAccount": {
- "bankNumber": "string",
- "agencyNumber": "string",
- "accountNumber": "string",
- "accountComplementNumber": "001",
- "accountType": "CHECKING",
- "accountHolder": {
- "name": "string",
- "document": "stringstrin"
}
}, - "legalRepresentative": {
- "name": "string",
- "document": "string",
- "birthDate": "yyyy-MM-dd",
- "motherName": "string",
- "type": "INDIVIDUAL"
}
}
{- "id": "string",
- "type": "string",
- "status": "AWAITING_DOCUMENTS",
- "personType": null,
- "document": "string",
- "createdOn": "yyyy-MM-dd HH:mm:ss",
- "_links": [
- {
- "self": {
- "href": "string"
}
}
]
}