Endpoints

https://api.ebanx.com/ws/request

https://sandbox.ebanx.com/ws/request

HTTP Method

POST

Response

JSON

This method allows you to create a payment using EBANX Checkout, where the customer is redirected to EBANX’s website to enter his data.

Request parameters

integration_key

string, length 100, required

Your unique and secret integration key.

name

string, length 1-100, required

Customer name.

email

string, length 1-100, email, required

Customer email address.

currency_code

string, length 3, ISO 4217, required

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

  • EUR
  • BRL
  • MXN
  • PEN
  • USD
  • CLP
  • COP
  • ARS

amount

float, required

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

merchant_payment_code

string, length 1-40, required if hash not provided

The payment hash Merchant Payment Code (merchant unique ID).

order_number

string, 1-40 length

The order number, optional identifier set by the merchant. You can have multiple payments with the same order number.

payment_type_code

string, length 32, required

The code of the payment method. The supported codes are:

  • amex: American Express credit card (Brazil, Mexico, Colombia).
  • aura: Aura credit card (Brazil).
  • baloto: Baloto (Colombia).
  • bancodobrasil: Banco do Brasil bank transfer (Brazil).
  • banrisul: Banrisul bank transfer (Brazil).
  • boleto: Boleto bancário (Brazil).
  • bradesco: Bradesco bank transfer (Brazil).
  • carnet: CARNET credit card (Mexico).
  • diners: Diners credit card (Brazil, Colombia).
  • 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ú bank transfer (Brazil).
  • mastercard: MasterCard credit card (Brazil, Mexico, Colombia).
  • multicaja: Multicaja (Chile).
  • oxxo: OXXO (Mexico).
  • pagoefectivo: PagoEfectivo (Peru).
  • rapipago: Rapipago. (Argentina)
  • pagofacil: PagoFacil. (Argentina)
  • cupon: Cupon de Pagos. (Argentina)
  • 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).
  • webpay: Webpay (Chile).

user_value_1, user_value_2, user_value_3, user_value_4, user_value_5

string, length 1-20, optional

Optional parameters that can be used by the merchant associate additional info to the payment. These parameters will be appended to the response_url when the transaction is finished.

notification_url

string, length 1-2000, optional

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

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.

person_type

string, length 2, optional

Optional parameter that can be used to identify the type of customer:

  • PJ: corporation, legal entity.
  • PF: natural person.

zipcode

string, length 8, 00000000, optional

Customer zipcode. If provided, the information will be displayed in the EBANX Checkout page.

address

string, length 1-100, optional

Customer address (street name). If provided, the information will be displayed in the EBANX Checkout page.

street_number

string, length 1-30, optional

Customer street number. If provided, the information will be displayed in the EBANX Checkout page.

city

string, length 1-80, optional

Customer city. If provided, the information will be displayed in the EBANX Checkout page.

state

string, length 2-5, optional

Customer state/region/province. If provided, the information will be displayed in the EBANX Checkout page.

country

string, length 2, required

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

  • br: Brazil.
  • cl: Chile.
  • co: Colombia.
  • mx: Mexico.
  • pe: Peru.
  • ar: Argentina.
  • ec: Ecuador.

phone_number

string, length 10-15, required

Customer phone number. It is required for all countries.

  • Brazil: required.
  • Mexico: required.
  • Peru: required.
  • Chile: required.
  • Colombia: required.
  • Argentina: required.
  • Ecuador: required.

due_date

string, length 10, dd/mm/yyyy

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, Length: 32, required

The name of the sub account

sub_acc_image_url

string, Length: 200, required

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, Length: 5, optional

Number or Range of instalments. OBS: If your are sending a range, must be in the format “X-Y”. Example: “1-6”.

This method call will return a JSON object with the payment data. If the request was placed successfully, you then redirect the customer to the EBANX Checkout using the redirect_url parameter.

Response parameters

status

string

The status of the the request (SUCCESS or ERROR).

payment

JSON

A JSON object that represents the payment.

payment.hash

string, 41 length, unique

The payment hash (EBANX unique identifier).

payment.merchant_payment_code

string, 1-40 length

The payment hash Merchant Payment Code (unique merchant ID).

payment.order_number

string, 1-40 length

The order number, optional identifier set by the merchant. You can have multiple payments with the same order number.

payment.status

string, 2 length

The payment status. The following statuses are available:

  • OP: the customer has not yet filled the payment details on the EBANX Checkout. It can change either to CA (time out) or PE.
  • PE: the payment is pending confirmation. It can change either to CA or CO.
  • CO: the payment is confirmed (paid).
  • CA: the payment is cancelled.

payment.status_date

string, 19 length, UTC Date

The date and hour of the last status change.

payment.open_date

string, 19 length, UTC Date

The date and hour of when the payment was created.

payment.confirm_date

string, 19 length, UTC Date

The date and hour of when the payment was confirmed.

payment.transfer_date

string, 19 length, UTC Date

The date and hour of when the payment was settled.

payment.amount_br

float

The amount in local currency.

payment.amount_iof

float

The tax amount in local currency (varies between countries).

payment.amount_ext

float

The amount in the original currency.

payment.currency_rate

float

The exchange rate used in the payment.

payment.currency_ext

string, 3 length, ISO 4217 three letter code

Three-letter code of the original currency.

payment.due_date

string, 10 length, dd/mm/yyyy

Expiry date of the payment (not applicable to all payment methods).

payment.instalments

integer, ranges from 1 to 12

Number of instalments for the payment, default value is 1.

payment.payment_type_code

string, 32 length

The code of the payment method. The supported codes are:

  • amex: American Express credit card (Brazil, Mexico, Colombia).
  • aura: Aura credit card (Brazil).
  • baloto: Baloto (Colombia).
  • bancodobrasil: Banco do Brasil bank transfer (Brazil).
  • banrisul: Banrisul bank transfer (Brazil).
  • boleto: Boleto bancário (Brazil).
  • bradesco: Bradesco bank transfer (Brazil).
  • carnet: CARNET credit card (Mexico).
  • diners: Diners credit card (Brazil, Colombia).
  • 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ú bank transfer (Brazil).
  • mastercard: MasterCard credit card (Brazil, Mexico, Colombia).
  • multicaja: Multicaja (Chile).
  • oxxo: OXXO (Mexico).
  • pagoefectivo: PagoEfectivo (Peru).
  • safetypay: SafetyPay (Peru, Checkout only).
  • safetypay-cash: SafetyPay Cash (Peru).
  • safetypay-online: SafetyPay Online (Peru).
  • sencillito: Sencillito (Chile).
  • servipag: Servipag (Chile).
  • spei: SPEI bank transfer method (Mexico).
  • visa: Visa credit card (Brazil, Mexico, Colombia).
  • webpay: Webpay (Chile).

payment.pre_approved

boolean

Flag that shows if a payment is pre-approved by the credit card acquirer.

payment.capture_available

boolean

Flag that shows if a payment is ready to be captured. Applies only to credit cards when auto_capture is set to false. Some remarks on this attribute:

  • A payment can only be captured if pre_approved value is true, which means that the payment has been pre approved by the credit card acquirer. Before capture, an authorized payment has status as PE (pending). After the capture, the status changes to CO (confirmed). A payment can only be captured if the status is PE (pending). *Payments must be captured in 4 (four) days, otherwise they are automatically cancelled.

NOTE: It can be changed up to 5 (five) days.

redirect_url

string, variable

The URL the customer should be redirected to complete the payment in thhe EBANX Checkout. Applies to certain payment methods using the Direct API.