GuidesAPI ReferenceRelease Notes

EBANX

Suggest Edits

Overview

Account Management: https://dashboard.ebanx.com
Developer Documentation:
https://business.ebanx.com/en/integrations/ebanx-direct-api
https://developer.ebanx.com/docs/payments/guides/accept-payments/api/credit-cards
https://ebanx.github.io/api-reference/#tag/Direct-Payments
Default Currency: USD

Request Objects: BillingAddress, CreditCard, OrderInfo, ThreeDSecure

Gateway Endpoints
This implementation of EBANX forwards requests to the below endpoints.
Production: https://api.ebanxpay.com/ws/direct
Sandbox: https://sandbox.ebanxpay.com/ws/direct

Supported Request Parameters

Type column indicates max length

Field NameTypeDirect API MappingNotes
gatewaystringN/AEBANX
integrationKeystring(100)integration_keyEBANX unique and secret Integration Key
modestring(4)modeDefaults to "full" if left blank on Authorize/Purchase operations.
operationstring(7)operationUsed in Authorize, Purchase, and Refund.
Defaults to "request" if left blank.
tokenExTransactionCodestringN/AUsed for processing capture, refund, or void operations
merchantCaptureCodestring(200)merchant_capture_codeOptional identifier for the payment capture.
merchantRefundCodestring(40)merchant_refund_codeThe ID of the refund on the merchant system.
descriptionstring(500)descriptionBrief summary of the operation. Used in Refund.
refundIdstring(20)refund_idThe ID of the refund to be canceled
items[ ]payment.itemsArray containing the items of the order
items.Skustring(20)payment.items.skuSKU of the item
items.Namestring(100)payment.items.nameName of the item
items.Descriptionstring(200)payment.items.descriptionDescription of the item
items.UnitPricenumericpayment.items.unit_priceSmallest values of currency specified by CurrencyCode. Converted to format of CurrencyCode. Example for USD: input 1000 for an output of $10.00.
items.Quantitynumericpayment.items.quantityQuantity of each item
items.Typestring(50)payment.items.typeType of the item
documentstring(32)payment.documentCustomer identification document number
merchantPaymentCodestring(128)payment.merchant_payment_codeThe payment hash Merchant Payment Code (unique merchant ID).
userValue1string(20)payment.user_value_1Parameter that can be used by the merchant to associate additional info to the payment.
orderInfo.orderIdstring(40)payment.order_numberAn optional identifier set by the merchant. There can be multiple payments with the same order number.
userValue1string(20)payment.user_value_1Parameter that can be used by the merchant to associate additional info to the payment.
userValue3string(20)payment.user_value_3Parameter that can be used by the merchant to associate additional info to the payment.
userValue4string(20)payment.user_value_4Parameter that can be used by the merchant to associate additional info to the payment.
userValue5string(20)payment.user_value_5Parameter that can be used by the merchant to associate additional info to the payment.
paymentTypeCodestring(3)payment.payment_type_codeThe code of the payment method.
amountnumericpayment.amount_totalSmallest values of currency specified by CurrencyCode. Converted to format of CurrencyCode. Example for USD: input 1000 for an output of $10.00.
currencyCodepayment.currency_codeUse the ISO 4217 three-letter alphabetic code for the currency.
dueDatestring(10)payment.due_dateThe due date of payment slips
subAccountNamenumericpayment.installmentsThe number of installments of the payment. Defaults to 1
notestring(200)payment.noteA note about the payment. The value of this parameter will be shown along with payment details.
subAccountNamestring(32)payment.sub_account.nameName of the sub account
subAccountImageUrlstring(2000)payment.notification_urlThe URL to send notifications for this payment. If this field is filled, EBANX will notify using this URL instead of the configured one.
eftCodestring(32)payment.eft_codeCode for the customer’s bank. Only required for Colombia payments
redirectUrlstring(2000)payment.redirect_urlThe URL to redirect the customer after the payment in the EBANX Payment Page. If this field is filled, EBANX will redirect the customer using this URL instead of the configured one.
personTypestring(8)payment.person_typeOptional parameter that can be used to identify the type of customer: "business" or "personal"
responsibleNamestring(100)payment.responsible.nameResponsible name. Required if person_type = business.
customerIpAddressstringpayment.customer_ipCustomer’s IP address. It may be used by an anti-fraud tool.
deviceIdstringpayment.device_idUnique ID to identify the customer’s device.
billingAddress.FirstName
billingAddress.LastName		stringpayment.nameIf left empty, this field's default value will be populated from billingAddress.FirstName + billingAddress.LastName. Sum of both fields cannot be greater than 50 characters
billingAddress.FullNamestring payment.nameAlternative entry for name.
billingAddress.Address1stringpayment.street_numberCustomer street number.
billingAddress.Address2string(100)payment.addressExtra address field for complimentary data.
billingAddress.Citystring(80)payment.cityCustomer city
billingAddress.Statestringpayment.stateCustomer state/region/province
billingAddress.Countrystringpayment.countryCustomer country. Input Alpha 3. Converted to Alpha 2.
billingAddress.Zipstring(8)payment.zipcodeCustomer zip code
billingAddress.Emailstring(100)payment.emailCustomer email address
billingAddress.Phonestringpayment.card.card_numberCustomer phone number
creditCardobjectpayment.cardUse for either credit or debit card transactions
creditCard.Numberstringpayment.card.card_numberTokenEx Token or PAN
creditCard.CVVstringpayment.card.card_cvvCard security code.
creditCard.FirstName
creditCard.LastName		stringpayment.card.card_nameParameters are combined and space separated.
creditCard.FullNamestringpayment.card.card_nameAlternative entry for name
creditCard.ExpMonthstring(128)payment.card.card_due_dateMM. Combined with CreditCard.ExpYear to equal MM/YYYY
creditCard.ExpYearnumericpayment.card.card_due_dateYYYY. Combined withe CreditCard.ExpMonth to equal MM/YYYY
creditCard.EBANXTokenstringpayment.card.tokenEBANX token used for recurring billing.
threeDSecure.ECIstringpayment.card.threeds_eciElectronic Commerce Indicator
threeDSecure.CAVVstringpayment.card.threeds_cryptogramCardholder Authentication Verification Value
threeDSecure.XIDstringpayment.card.threeds_xidUnique transaction Identification number to identify the 3DS transaction
threeDSecure.ThreeDSecureVersionstringpayment.card.threeds_version3DS Version
threeDSecure.DSTransIdstringpayment.card.threeds_trxidDirectory Server Transaction ID
createEBANXTokenbooleanpayment.create_tokenGenerates a token for recurring billing.
softDescriptors.MerchantNamestringsoftDescriptorSee note below.
softDescriptors.MerchantPhonestringsoftDescriptorSee note below.
softDescriptors.MerchantEmailstringsoftDescriptorSee note below.
softDescriptors.MerchantUrlstringsoftDescriptorSee note below.
softDescriptors.MerchantCategoryCodestringsoftDescriptorSee note below.
softDescriptors.MerchantCitystringsoftDescriptorSee note below.
storedCredentials.Initiatorstringcard_cvv_modeValid values: "cardholder" or "merchant".

📘

Soft Descriptors - SoftDescriptor Construction

EBANX API's softDescriptor is a free-text field. If values are sent in the TokenEx SoftDescriptors fields, they will be concatenated and space separated in the forwarded request. Alternatively, use the softDescriptor passthrough in OrderInfo.

Example Usage:

"softDescriptors": {  
    "merchantName":"Bob Smalls",  
    "merchantPhone": "(876) 613-1270 x38785",  
    "merchantEmail":"[email protected]",  
    "merchantUrl": "http://merchant.com",
  	"merchantCategoryCode": "1515151515",
  	"merchantCity": "Las Vegas"
}

Forwarded output: Bob Smalls (876) 613-1270 x38785 [email protected] http://merchant.com 1515151515 Las Vegas

Example Requests

{
    "gateway": "EBANX",
    "testMode": true,
    "integrationKey": "<Your EBANX Integration Key>",
    "merchantPaymentCode": "ABC00001",
    "document": "853.513.468-93",
    "creditCard": {
        "firstName": "José",
        "lastName": "Silva",
        "number": "378282246310005",
        "cvv": "123",
        "expMonth": 6,
        "expYear": 2023
    },
    "billingAddress": {
        "firstName": "José",
        "lastName": "Silva",
        "address1": "1040",
        "address2": "Rua teste",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "zip": "61919",
        "country": "BRA",
        "phone": "8522847035",
        "email": "[email protected]"
    },
    "softDescriptors": {  
      "merchantName":"Bob Smalls",  
      "merchantPhone": "(876) 613-1270 x38785",  
      "merchantEmail":"[email protected]",  
      "merchantUrl": "http://merchant.com",
      "merchantCategoryCode": "1515151515",
      "merchantCity": "Las Vegas"
 		},
    "amount": 1000,
    "currencyCode": "BRL"
}

{
    "gateway": "EBANX",
    "testMode": true,
    "integrationKey": "<Your EBANX Integration Key>",
    "merchantCaptureCode": "ABC00001",
    "tokenExTransactionCode": "<TokenExTransactionCode from a previous Authorize call>",
    "amount": 1000
}

{
    "gateway": "EBANX",
    "testMode": true,
    "integrationKey": "<Your EBANX Integration Key>",
    "amount": 1000,
    "description": "water damage",
    "merchantRefundCode": "ABC00001",
    "tokenExTransactionCode": "<TokenExTransactionCode from a previous Purchase or Capture call>"
}

{
    "gateway": "EBANX",
    "testMode": true,
    "integrationKey": "<Your EBANX Integration Key>",
    "tokenExTransactionCode": "<TokenExTransactionCode from a previous Authorize, or Purchase, Capture, or Refund call>"
}

Gateway Response Parameters

Field NameTypeDirect API MappingNotes
approvedbooleanN/AIf EBANX returns an authcode, this field will be true.
approvalCodestring(40)authcodeTransaction authentication code from the processor.
providerTransactionCodestringhashThe payment hash (EBANX unique identifier).
merchantReferenceIdstringorder_numberThe value sent in orderInfo.orderId.

Example Responses

{
    "gatewayResponse": {
        "rawResponse": "{\"payment\":{\"hash\":\"656f8fa4e9924d5ac1efa65ac0c624a713ade094d1417359\",\"country\":\"br\",\"merchant_payment_code\":\"example\",\"order_number\":null,\"status\":\"PE\",\"status_date\":null,\"open_date\":\"2023-12-05 21:01:24\",\"confirm_date\":null,\"transfer_date\":null,\"amount_br\":\"58.52\",\"amount_ext\":\"10.00\",\"amount_iof\":\"0.22\",\"currency_rate\":\"5.8300\",\"currency_ext\":\"USD\",\"due_date\":\"2023-12-08\",\"instalments\":\"1\",\"payment_type_code\":\"visa\",\"details\":{\"billing_descriptor\":\"TOKENEX\"},\"transaction_status\":{\"acquirer\":\"EBANX\",\"code\":\"OK\",\"description\":\"Accepted\",\"authcode\":\"23643\"},\"pre_approved\":true,\"capture_available\":true},\"status\":\"SUCCESS\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "NjU2ZjhmYTRlOTkyNGQ1YWMxZWZhNjVhYzBjNjI0YTcxM2FkZTA5NGQxNDE3MzU5O2V4YW1wbGU=",
        "approvalCode": "23643",
        "providerTransactionCode": "656f8fa4e9924d5ac1efa65ac0c624a713ade094d1417359",
        "approved": true
    },
    "referenceNumber": "23120515012312723182",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"payment\":{\"hash\":\"656f90992e7f6ff60ae4305402010bca98b7eb57951f9d5a\",\"country\":\"br\",\"merchant_payment_code\":\"example2\",\"order_number\":null,\"status\":\"CO\",\"status_date\":\"2023-12-05 21:05:30\",\"open_date\":\"2023-12-05 21:05:29\",\"confirm_date\":\"2023-12-05 21:05:30\",\"transfer_date\":null,\"amount_br\":\"58.52\",\"amount_ext\":\"10.00\",\"amount_iof\":\"0.22\",\"currency_rate\":\"5.8300\",\"currency_ext\":\"USD\",\"due_date\":\"2023-12-08\",\"instalments\":\"1\",\"payment_type_code\":\"visa\",\"details\":{\"billing_descriptor\":\"TOKENEX\"},\"transaction_status\":{\"acquirer\":\"EBANX\",\"code\":\"OK\",\"description\":\"Accepted\",\"authcode\":\"63258\"},\"pre_approved\":true,\"capture_available\":false},\"status\":\"SUCCESS\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "NjU2ZjkwOTkyZTdmNmZmNjBhZTQzMDU0MDIwMTBiY2E5OGI3ZWI1Nzk1MWY5ZDVhO2V4YW1wbGUy",
        "approvalCode": "63258",
        "providerTransactionCode": "656f90992e7f6ff60ae4305402010bca98b7eb57951f9d5a",
        "approved": true
    },
    "referenceNumber": "23120515052947124633",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"payment\":{\"hash\":\"656f8fa4e9924d5ac1efa65ac0c624a713ade094d1417359\",\"country\":\"br\",\"merchant_payment_code\":\"example\",\"order_number\":null,\"status\":\"CO\",\"status_date\":\"2023-12-05 21:06:46\",\"open_date\":\"2023-12-05 21:01:24\",\"confirm_date\":\"2023-12-05 21:06:46\",\"transfer_date\":null,\"amount_br\":\"58.52\",\"amount_ext\":\"10.00\",\"amount_iof\":\"0.22\",\"currency_rate\":\"5.8300\",\"currency_ext\":\"USD\",\"due_date\":\"2023-12-08\",\"instalments\":\"1\",\"payment_type_code\":\"visa\",\"details\":{\"billing_descriptor\":\"TOKENEX\"},\"transaction_status\":{\"acquirer\":\"EBANX\",\"code\":\"OK\",\"description\":\"Accepted\",\"authcode\":\"23643\"},\"pre_approved\":true,\"capture_available\":false},\"status\":\"SUCCESS\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "NjU2ZjhmYTRlOTkyNGQ1YWMxZWZhNjVhYzBjNjI0YTcxM2FkZTA5NGQxNDE3MzU5O2V4YW1wbGU=",
        "approvalCode": "23643",
        "providerTransactionCode": "656f8fa4e9924d5ac1efa65ac0c624a713ade094d1417359",
        "approved": true
    },
    "referenceNumber": "23120515064620722884",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"payment\":{\"hash\":\"656f90992e7f6ff60ae4305402010bca98b7eb57951f9d5a\",\"country\":\"br\",\"merchant_payment_code\":\"example2\",\"order_number\":null,\"status\":\"CO\",\"status_date\":\"2023-12-05 21:05:30\",\"open_date\":\"2023-12-05 21:05:29\",\"confirm_date\":\"2023-12-05 21:05:30\",\"transfer_date\":null,\"amount_br\":\"58.52\",\"amount_ext\":\"10.00\",\"amount_iof\":\"0.22\",\"currency_rate\":\"5.8300\",\"currency_ext\":\"USD\",\"due_date\":\"2023-12-08\",\"instalments\":\"1\",\"payment_type_code\":\"visa\",\"details\":{\"billing_descriptor\":\"TOKENEX\"},\"transaction_status\":{\"acquirer\":\"EBANX\",\"code\":\"OK\",\"description\":\"Accepted\",\"authcode\":\"63258\"},\"pre_approved\":true,\"capture_available\":false,\"refunds\":[{\"id\":\"9785428953\",\"merchant_refund_code\":null,\"status\":\"RE\",\"request_date\":\"2023-12-05 21:10:02\",\"pending_date\":null,\"confirm_date\":null,\"cancel_date\":null,\"amount_ext\":\"10.00\",\"description\":\"defect in product\",\"email_quantity\":0,\"email_first_date\":null,\"email_last_date\":null,\"bank_info_customer_filled\":0,\"bank_info_customer_filled_date\":null}]},\"refund\":{\"id\":\"9785428953\",\"merchant_refund_code\":null,\"status\":\"RE\",\"request_date\":\"2023-12-05 21:10:02\",\"pending_date\":null,\"confirm_date\":null,\"cancel_date\":null,\"amount_ext\":\"10.00\",\"description\":\"defect in product\",\"email_quantity\":0,\"email_first_date\":null,\"email_last_date\":null,\"bank_info_customer_filled\":0,\"bank_info_customer_filled_date\":null},\"operation\":\"refund\",\"status\":\"SUCCESS\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "NjU2ZjkwOTkyZTdmNmZmNjBhZTQzMDU0MDIwMTBiY2E5OGI3ZWI1Nzk1MWY5ZDVhO2V4YW1wbGUy",
        "approvalCode": "63258",
        "providerTransactionCode": "656f90992e7f6ff60ae4305402010bca98b7eb57951f9d5a",
        "approved": true
    },
    "referenceNumber": "23120515100284997369",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"payment\":{\"hash\":\"656f91be53fc1210531807b7e7b1c696d282459a0ff3a6a4\",\"country\":\"br\",\"merchant_payment_code\":\"example1\",\"order_number\":null,\"status\":\"CA\",\"status_date\":\"2023-12-05 21:10:36\",\"open_date\":\"2023-12-05 21:10:22\",\"confirm_date\":null,\"transfer_date\":null,\"amount_br\":\"58.52\",\"amount_ext\":\"10.00\",\"amount_iof\":\"0.22\",\"currency_rate\":\"5.8300\",\"currency_ext\":\"USD\",\"due_date\":\"2023-12-08\",\"instalments\":\"1\",\"payment_type_code\":\"visa\",\"details\":{\"billing_descriptor\":\"TOKENEX\"},\"transaction_status\":{\"acquirer\":\"EBANX\",\"code\":\"OK\",\"description\":\"Accepted\",\"authcode\":\"44515\"},\"pre_approved\":false,\"capture_available\":false},\"operation\":\"cancel\",\"status\":\"SUCCESS\"}",
        "gatewayErrors": [],
        "tokenExTransactionCode": "NjU2ZjkxYmU1M2ZjMTIxMDUzMTgwN2I3ZTdiMWM2OTZkMjgyNDU5YTBmZjNhNmE0O2V4YW1wbGUx",
        "approvalCode": "44515",
        "providerTransactionCode": "656f91be53fc1210531807b7e7b1c696d282459a0ff3a6a4",
        "approved": true
    },
    "referenceNumber": "23120515103561530597",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"status\":\"ERROR\",\"status_code\":\"BP-DR-0\",\"status_message\":\"Payment already exists with merchant_payment_code: example1 (created on 2023-12-05 21:10:22, status is CA)\"}",
        "gatewayErrors": [
            {
                "code": "BP-DR-0",
                "message": "Payment already exists with merchant_payment_code: example1 (created on 2023-12-05 21:10:22, status is CA)",
                "source": "Gateway"
            }
        ],
        "tokenExTransactionCode": "",
        "approved": false
    },
    "referenceNumber": "23120815505323000961",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

{
    "gatewayResponse": {
        "rawResponse": "{\"payment\":{\"hash\":\"65738fa85f187f642cf59ada93b69160a2d7c74066686b40\",\"country\":\"br\",\"merchant_payment_code\":\"example4\",\"order_number\":null,\"status\":\"CA\",\"status_date\":\"2023-12-08 21:50:32\",\"open_date\":\"2023-12-08 21:50:32\",\"confirm_date\":null,\"transfer_date\":null,\"amount_br\":\"58.52\",\"amount_ext\":\"10.00\",\"amount_iof\":\"0.22\",\"currency_rate\":\"5.8300\",\"currency_ext\":\"USD\",\"due_date\":\"2023-12-11\",\"instalments\":\"1\",\"payment_type_code\":\"visa\",\"details\":{\"billing_descriptor\":\"TOKENEX\"},\"transaction_status\":{\"acquirer\":\"EBANX\",\"code\":\"NOK\",\"description\":\"Insufficient funds\"},\"pre_approved\":false,\"capture_available\":false},\"status\":\"SUCCESS\"}",
        "gatewayErrors": [
            {
                "code": "NOK",
                "message": "Insufficient funds",
                "source": "Processor"
            }
        ],
        "tokenExTransactionCode": "",
        "providerTransactionCode": "65738fa85f187f642cf59ada93b69160a2d7c74066686b40",
        "approved": false
    },
    "referenceNumber": "2312081550315893143",
    "success": true,
    "error": "",
    "message": "",
    "thirdPartyStatusCode": "200"
}

Updated 2 months ago