This guide will walk you through the process of integrating debit card payments using EBANX Direct. You’ll learn how to securely process transactions, handle authorizations, and manage payment captures, ensuring a smooth and efficient payment experience for your customers. Follow the steps below to start accepting debit card payments with EBANX.
Requirements
- API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
Instructions
Follow the steps below.
Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
https://sandbox.ebanx.com/ws/directChoose your features
Select a country to explore available features.The features listed below reflect availability based on your selection.
Card Verification
Validates the authenticity of a payment card by checking its details, such as CVV, ensuring secure and authorized transactions.
Click to explorechevron_rightAvailable
3DS
Adds an extra layer of authentication for online payments, protecting customers and merchants by verifying cardholder identity during transactions.
Click to explorechevron_rightAvailable
Card on File
Securely stores customer card details for future use, enabling faster checkouts and recurring payments while maintaining compliance and data security.
Click to explorechevron_rightAvailable
Installments
Allows customers to split payments into multiple installments, increasing affordability and boosting conversion rates for merchants.
Click to explorechevron_rightAvailable
Pre-Authorization
Holds a specific amount on a customer’s payment method to verify funds, ensuring payment readiness before finalizing the transaction.
See step 6 belowAvailable
Tokenization
Replaces payment data, like card numbers, with secure, unique tokens, enhancing security while ensuring seamless transactions for customers.
Click to explorechevron_rightAvailableDefine your parameters
You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.Essential parameters
payment.payment_type_code- Specifies the payment method to be used for the transaction.payment.currency_code- Three-letter code of the payment currency.payment.amount_total- Total amount to be charged.payment.card- Card details such as card number, expiration date, CVV, and cardholder name.- Card details can also be securely tokenized. See theCard Tokenization Guidechevron_right
Additional parameters
- EBANX Integration Key - Used to authenticate and authorize API requests.
- Customer Information
- Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
- While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
- Additional Context - Extra data for specific methods or countries.
To learn more about API parameters, please refer to theAPI Reference Guide chevron_rightSample request
Use the following example to initiate a payment request. Select another country from the dropdown if needed.
Brazil | Using Sandbox URLcurl -X POST \
--location 'https://sandbox.ebanx.com/ws/direct' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"operation": "request",
"payment": {
"name": "José Silva",
"email": "jose@example.com",
"document": "853.513.468-93",
"address": "Rua E",
"street_number": "1040",
"city": "Maracanaú",
"state": "CE",
"zipcode": "61919-230",
"country": "br",
"phone_number": "8522847035",
"payment_type_code": "debitcard",
"merchant_payment_code": "ecc9be4512a",
"currency_code": "BRL",
"installments": 1,
"amount_total": 100,
"card": {
"card_number": "4111111111111111",
"card_name": "José Silva",
"card_due_date": "12/2019",
"card_cvv": "123",
"threeds_eci": "05",
"threeds_cryptogram": "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
"threeds_xid": "AAIBAkl0NwmHglFBAXQ3AAAAAAA",
"threeds_version": "2",
"threeds_trxid": "AAIBAkl0NwmHglFBAXQ3AAAAAAA"
}
}
}'When using tokenized card information, the
cardobject should be as follows:card: {
token: "card_token_here"
}Or for recurrent transactions:
"card": {
"token": "card_token_here",
"network_token_mode": "recurrent"
}For more information about card tokenization, please refer to theCard Tokenization Guidechevron_rightSample response
Each request returns a response similar to the example below.
Brazil | Using Sandbox URL{
"payment": {
"hash": "59ad5f00945fa382ab051651440826da7701533249b3a475",
"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": "100.38",
"amount_ext": "100.00",
"amount_iof": "0.38",
"currency_rate": "1.0000",
"currency_ext": "BRL",
"due_date": "2017-09-07",
"installments": "1",
"payment_type_code": "debitcard",
"details": {
"billing_descriptor": ""
},
"transaction_status": {
"acquirer": "EBANX",
"code": "OK",
"description": "Sandbox - Test debit card, transaction captured"
},
"pre_approved": true,
"capture_available": false
},
"status": "SUCCESS"
}Capture a pending payment
Two-Step Payments OnlyThis step applies when
auto_captureis set to false, changing the payment status from pending (PE) to confirmed (CO).1. Overview
- In the first step, the payment was authorized and is pending (PE).
- The payment needs to be captured to change its status to confirmed (CO).
- Uncaptured payments will automatically expire.
2. Get Hash, or Merchant Payment Code
Get the
hashormerchant_payment_codefrom the authorized pending (PE) transaction.{
"payment": {
"hash": "59ad5f00945fa382ab051651440826da7701533249b3a475", // example hash
"country": "br",
"merchant_payment_code": "ecc9be4512a", // example merchant payment code
"order_number": null,
"status": "PE", // Pending
...
...
... // remainder of the response
},
}3. Send a request to capture the payment
To capture the payment, send a request to
ws/captureusing the Hash or Merchant Payment Code.Examples:
-using Hash
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/capture' \
--header 'Content-Type: application/json' \
--data
{
integration_key: "your_ebanx_integration_key",
hash: "59ad5f00945fa382ab051651440826da7701533249b3a475",
}-using Merchant Payment Code
curl -X POST \
--location 'https://sandbox.ebanx.com/ws/capture' \
--header 'Content-Type: application/json' \
--data
{
integration_key: "your_ebanx_integration_key",
merchant_payment_code: "ecc9be4512a"
}4. Successful capture
A successful capture will return a response similar to the one below.
{
"payment": {
"hash": "59ad5f00945fa382ab051651440826da7701533249b3a475",
"country": "br",
"merchant_payment_code": "ecc9be4512a",
"order_number": null,
"status": "CO", // Confirmed
...
...
... // remainder of the response
},
"status": "SUCCESS"
}API ReferenceThe API reference for
ws/capturecan be found here. We recommend reviewing all available options.Congratulations!
You have completed the necessary steps to create a debit card payment.
Resources
Use the following resources when testing in your sandbox environment.
Sample Cards
Click here to view mock card data to validate your payment integration.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.