This page's content:

Endpoints

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

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

HTTP Method

POST

Response

JSON

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. You can view some practical examples on our API guides section.

Request parameters

integration_key string, length 100, required

Your unique and secret integration key.

operation string, length 7, required

Must be request.

mode string, length 4, value must be full, required

Currently only full mode is available.

payment JSON

A JSON object that represents the payment.

payment.name string, length 1-100, required

Customer name.

payment.email string, length 5-100, email, required

Customer email address.

payment.currency_code string, lenght 3, Format: ISO 4217 three letter code

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

  • BRL
  • EUR
  • MXN
  • PEN
  • USD
  • CLP
  • COP
  • ARS
  • BOB
payment.amount_total float, required

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

payment.merchant_payment_code string, 1-40 length

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

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).
  • 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).
  • pagosnet: PagosNet (Bolivia).
  • 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).
payment.document string, Length: 32

Customers document.

  • Brazil: requires a valid CPF (natural person taxpayer ID) or CNPJ (business taxpayer ID).
  • Chile: requires a valid RUT (Registro Único Tributario).
  • Colombia: requires a valid NIT / CC (Número de Identificación Tributaria).
  • Argentina: requires a valid CUIT / CUIL / CDI (Clave Única de Identificación Tríbutaria).
payment.customer_ip string, Format: IPv4 (RFC 791), IPv6 (RFC 2460), optional

Customer’s IP adress. It may be used by an anti-fraud tool.

payment.zipcode string, Length: 8, Format: 00000000, required(Brazil) / Optional (Other)

Customer’s zipcode.

  • Brazil: required.
  • Argentina: required for Credit Card payments.
  • Chile: required for Webpay and Multicaja payments.
  • Colombia: required for Credit Card payments.
  • Mexico: required for Credit Card payments.
payment.address string, Length: 1-100, required(Brazil) / optional(Others)

Customer address (street name).

  • Brazil: required.
  • Argentina: required for Credit Card payments.
  • Chile: required for Webpay and Multicaja payments.
  • Colombia: required for Credit Card payments.
  • Mexico: required for Credit Card payments.
payment.street_number string, Length: 1-30, required(Brazil) / optional(Others)

Customer street number.

  • Brazil: required.
  • Argentina: required for Credit Card payments.
  • Chile: required for Webpay and Multicaja payments.
  • Colombia: required for Credit Card payments.
  • Mexico: required for Credit Card payments.
payment.street_complement string, Length: 1-100, optional

Extra address field for complimentary data.

payment.city string, Length: 1-80, required(Brazil) / optional(Others)

Customer city.

  • Brazil: required.
  • Argentina: required for Credit Card payments.
  • Chile: required for Webpay and Multicaja payments.
  • Colombia: required for Credit Card payments.
  • Mexico: required for Credit Card payments.
payment.state string, Length: 2-5, required(Brazil) / optional(Others)

Customer state/region/province.

  • Brazil: required.
  • Argentina: required for Credit Card payments..
  • Chile: required for Webpay and Multicaja payments.
  • Colombia: required for Credit Card payments.
  • Mexico: required for Credit Card payments.
payment.country string, Length: 2, required

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

  • br: Brazil.
  • pe: Peru.
  • mx: Mexico.
  • co: Colombia.
  • cl: Chile.
  • ar: Argentina.
  • ec: Ecuador.
  • bo: Bolivia.
payment.phone_number string, Length: 10-15, required

Customer phone number. It is required for all countries.

payment.user_value_1 | payment.user_value_2 | payment.user_value_3 | payment.user_value_4 | payment.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.

payment.due_date string, Length: 10, Format: dd/mm/yyyy, optional(boleto)

The due date of payments slips. Boletos issued in USD can have a maximum expiry period of three days; boletos issued in BRL can have an extended expiry date. The due date is based on local time of the country that the payment is generated.

payment.create_token boolean, optional(credit cards)

Generates a token for recurring billing. This is only available for merchants that have requested recurring billing on their contracts.

payment.token string, Length: 32-128, Constraints: unique, optional(credit cards)

Choose the token you want to use for recurring billing. This is only available for merchants that have requested recurring billing on their contracts. Use this parameter only if create_token is true. NOTE: TOKENS EXPIRE AFTER 14 MONTHS OF ITS LAST USE.

payment.instalments integer, Contraints: ranges from 1 to 36, optional(credit cards)

The number of instalments of the payment (from 1 to 12, depending on your contract and the country).

  • Brazil: 1 to 12 (depending on your contract).
  • Mexico: 1, 3, 6, 9 or 12 (depending on your contract).
  • Colombia: 1 to 36 (depending on your contract).
  • Argentina: 1 to 12 (depending on your contract).
payment.creditcard JSON object, required(credit cards)

Object containing the customers credit card information.

payment.creditcard.card_number string, Length: 14-19, required(credit cards)

Credit card number.

payment.creditcard.card_name string, Length: 50, required(credit cards)

Credit card cardholder name.

payment.creditcard.card_due_date string, Length: 7, Format: mm/yyyy, required(credit cards)

Credit card due date (“valid thru”) in the format mm/yyyy.

payment.creditcard.card_cvv string, Length: 3-4, required(credit cards)

Credit card security code.

payment.creditcard.auto_capture boolean, optional(credit cards)

If true, the payment will be captured automatically by EBANX; if false, the payment will have to be captured by the merchant using the API method capture. The default value is true.

payment.creditcard.token string, Length: 1-200, Constraints: unique, optional(credit cards)

If a previously created token is informed, no credit card information is needed. EBANX will identify the credit card associated with the token and perform the transaction. Only available if you do recurring billing.

payment.note string, Length: 1-200, Optional

A note about the payment. The value of this parameter will be shown along with payment details.

payment.sub_account JSON object, required

The object containing the sub account’s name. Required for payments where the sub account feature is being used.

payment.sub_account.name string, Length: 32, required

Name of the sub account

payment.sub_account.image_url string, Length: 200, required

URL of the logo of the sub-account. PS: It MUST be an HTTPS URL. Otherwise, you will receive an error message.

payment.items JSON object, optional

Object containing the items of the order

payment.items.sku string, Length: 20, optional

SKU of the item

payment.items.name string, Length: 100, optional

Name of the item

payment.items.description string, Length: 200, optional

Description of the item

payment.items.unit_price float, optional

Price of the unity of the item

payment.items.quantity integer, optional

Quantity of each item

payment.items.type string, Length: 50, optional

Type of the item

payment.device_id string, Length: 1-200, optional

Unique ID to identify the customer’s device. Used for anti-fraud checking purposes. More information about it HERE.

payment.eft_code string, Length: 0-32, optional

Code for the customer’s bank. Only required for Colombia payments. You can retrieve the available codes from ws/getBankList operation.

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

payment.person_type string, length 8, optional

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

  • business: Corporation, legal entity.
  • personal: Natural person.
payment.responsible JSON

A JSON object that represents the responsible. Required if person_type = business.

payment.responsible.name string, length 1-100

Responsible name. Required if person_type = business.

This method call will return a JSON object with the payment data. The response parameters will vary depending on the chosen payment method:

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.pin string, 41 length, unique

The payment PIN (EBANX and Customer unique identifier).

payment.country string, 2 length, unique

The country of the payment.

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).
  • 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).
  • pagosnet: PagosNet (Bolivia).
  • 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).
payment.details JSON

A JSON object that represents the payment details.

payment.details.billing_descriptor string

The billing descriptor of the payment.

payment.transaction_status JSON

A JSON object that represents the payment credit card transaction.

payment.transaction_status.acquirer string, 16 length

The acquirer that processed the transaction.

payment.transaction_status.code string, 2-7 length

The transaction status code:

  • OK: The transaction amount was approved.
  • NOK: The acquirer did not approved the transaction. The customer must contact the issuer to check for any issue with his credit card.
  • RETRY: Something went wrong with the process. You can retry with the same data. We recommend you to try more 3 times on different periods of time (first try, then second try after 2 hours after the first, etc).

You can see more of these status HERE.

payment.transaction_status.description string, 500 length

The description for the status code, which is returned from the acquirer.

payment.transaction_status.authcode string, length 40

Transaction authentication code in the acquirer.

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.

payment.redirect_url string, variable

The URL the customer should be redirected to. Applies to certain payment methods using the Direct API.

payment.pay_with_balance_url string, variable

If the customer has an EBANX Account profile and it has balance enough to pay for the created boleto, the response will contain this parameter responsible for redirecting the customer to his EBANX Account page so he can pay the boleto with his available balance.

payment.boleto_url string, variable

The boleto URL.

payment.boleto_barcode string, length 47

The boleto barcode number. (Boleto)

payment.cip_url string, variable

The CIP URL. (PagoEfectivo)

payment.cip_code string, length 12

The CIP code. (PagoEfectivo)

payment.refunds JSON

An array of objects that represent a refund linked to this payment. This node will only be present if a refund was issued.

payment.refunds.id integer

The ID of the refund on EBANX.

payment.refunds.merchant_refund_code string, length 1-20

The ID of the refund on the merchant system (optional).

payment.refunds.status string, length 2

The status of the refund:

  • RE (Requested): The refund has been requested and is waiting to be processed. It can be cancelled while it has this status.
  • PE (Pending): The refund is being processed. It cannot be cancelled anymore.
  • CO (Confirmed): The refund was processed and the money was sent back to the customer.
  • CA (Cancelled): The refund was cancelled.
payment.refunds.request_date string, length 19, UTC Date

The date and hour when the refund was created.

payment.refunds.pending_date string, length 19, UTC Date

The date and hour when the customer data was received

payment.refunds.confirm_date string, length 19, UTC Date

The date and hour when the money was transferred to the customer.

payment.refunds.amount_ext float

The refunded amount in the original currency.

payment.refunds.description string, length 1-1500

Description of the refund reason.

payment.chargeback JSON

A JSON object that represents a chargeback linked to this payment. This node will only be present if a chargeback was issued.

payment.chargeback.create_date string, length 19, UTC Date

The date and hour when the chargeback was imported into the system.

payment.chargeback.chargeback_date string, length 19, UTC Date

The date and hour when the chargeback was created by the acquirer on behalf of the customer.

payment.chargeback.description string, length 1-1500

Description of the chargeback.

payment.chargeback_credit boolean

Flag that shows if a chargeback credit was issued.

payment.clabe_account string

(Only for SPEI payments) The customer’s CLABE account.

payment.clabe_reference string

(Only for SPEI payments) The reference for the current payment.