EBANX Integration Guide
Before you start
Take a few minutes to go through the following topics as they represent vital questions that must be answered before your company starts integrating with EBANX. Consider each topic, their possible answers, and EBANX recommendations accordingly.
Cross-border or Local?
EBANX offers two distinct services for local and cross-border companies. Merchants must have the desired operation in mind when planning an integration. Both operations use the same API endpoints, but country and feature availability may differ. The main difference between these two models is the money's final destination. In other words, the Cross-border model involves financial transactions between parties located in different countries, which might imply currency exchange rates and taxes. The Local model refers to financial transactions that take place within the country. If your business does not have based operations inside the country where EBANX has the Local model available, then the operation must be Cross-border.
If you want help to understand what countries to prioritize take a look at our latest materials and studies at the EBANX website, on the Resources tab.
info
If you want help to understand what countries to prioritize take a look at our latest materials and studies at the EBANX website, on the Resources tab.
Defining the Countries
EBANX offers a multitude of countries in which you can sell your services, some of them have the cross-border operation model, while others have both local and cross-border models for you to choose from. Remember to ensure that your company has a local entity to operate locally in the countries where you select the Local operation model.
Operation Model availability per country
| Country | Cross-border | Local |
|---|---|---|
| Argentina | ✔️ | ✔️ |
| Bolivia | ✔️ | |
| Brazil | ✔️ | ✔️ |
| Chile | ✔️ | ✔️ |
| Colombia | ✔️ | ✔️ |
| Costa Rica | ✔️ | |
| Dominican Republic | ✔️ | |
| Ecuador | ✔️ | |
| Egypt | ✔️ | |
| El Salvador | ✔️ | |
| Ghana | ✔️ | |
| Guatemala | ✔️ | |
| India | ✔️ | |
| Kenya | ✔️ | |
| Mexico | ✔️ | ✔️ |
| Nigeria | ✔️ | |
| Panama | ✔️ | |
| Paraguay | ✔️ | |
| Peru | ✔️ | |
| South Africa | ✔️ | |
| Tanzania | ✔️ | |
| Uganda | ✔️ | |
| Uruguay | ✔️ | |
| Zambia | ✔️ |
Payment Methods
EBANX enables you to operate using a variety of the most common payment methods in each country where we process payments. For that, we have payments with cards, alternative payment methods such as vouchers or transfers, and e-wallet payments that rely on a user’s external account. The processing of all kinds of payments through EBANX works exactly the same for you, with only differences in what is required in the payload body that you send and how the workflow will respond in synchronous vs. asynchronous cases. This is the list of currently available payment methods for each country:
| Country | Currency | Available Payment Method |
|---|---|---|
| Argentina | ARS - Peso Argentino | Bank Transfer, Cupon de Pagos, Pago Facil, Rapipago, Credit Cards, Debit Cards, Mercado Pago, MP Connect |
| Bolivia | BOB - Boliviano | Cash - PagosNet |
| Brazil | BRL - Brazilian Real | Bank Transfer, Boleto Bancário, Credit Card, Debit Card, E-Wallet, Multibenefícios, PIX, Voucher Cards |
| Chile | CLP - Peso Chileno | Credit Card, Debit Card, E-Wallet, Webpay, Flow, Multicaja, Sencillito, Servipag |
| Colombia | COP - Peso Colombiano | Baloto, Cash, Credit Card, Debit Card, E-Wallet, External Payment Provider, Bank Transfer |
| Costa Rica | CRC - Costa Rican Colón | Cash, Credit Card, Debit Card |
| Dominican Republic | DOP - Dominican Republic Peso | Credit Card, Debit Card |
| Ecuador | USD - United States Dollar | Credit Card, SafetyPay (Cash, Online) |
| Egypt | EGP - Egyptian Pound | Credit Card, Debit Card |
| El Salvador | USD - United States Dollar | Cash, Credit Card, Debit Card |
| Ghana | GHS - Ghanaian Cedi | E-Wallet (Mobile Money - Airtel, MTN, Tigo, Vodafone) |
| Guatemala | GTQ - Guatemalan Quetzal | Cash, Credit Card, Debit Card |
| India | Rs - Indian Rupee | E-Wallet (UPI Collect, UPI QR Code) |
| Kenya | KSh - Kenya Shilling | Credit Card, Debit Card, E-Wallet (Mobile Money - Airtel, M-Pesa, Equitel) |
| Mexico | MXN - Peso Mexicano | Credit Card, Debit Card, Mercado Pago, MP Connect, Oxxo, OxxoPay, Paynet, SPEI |
| Nigeria | NGN - Nigerian Naira | Bank Transfer, Credit Card, Debit Card, NIBBS, USSD |
| Panama | USD - United States Dollar | Cash, Credit Card, Debit Card |
| Paraguay | PYG - Paraguay Guarani | Credit Card, Debit Card |
| Peru | PEN - Sol | Credit Card, Debit Card, PagoEfectivo, SafetyPay |
| South Africa | ZAR - Rand | Credit Card, Debit Card, Ozow |
| Tanzania | TZS - Tanzania Shilling | E-Wallet (Mobile Money - Airtel, M-Pesa, Tigo, Vodafone) |
| Uganda | UGX - Ugandan Shilling | E-Wallet (Mobile Money - Airtel, MTN) |
| Uruguay | UYU - Peso Uruguayo | Credit Card, Debit Card, MP Connect |
| Zambia | ZMW - Zambian Kwacha | E-Wallet (Mobile Money - Airtel, Zamtel) |
To follow this integration guide, the recommendation is to select one of the payment methods and develop an MVP connection through EBANX, establishing the framework for the payment processing. With that done, adding payment methods is as simple as changing a few parameters in the payloads. As you finish your first payment integration, you should also be able to deep dive into our extended documentation and expand your offerings with EBANX
Customer Data Management
There are a few steps that you can take to make it easier to integrate with EBANX, here you will find what you have to do to handle your customer data with no problems:
- Is important to mention that EBANX has the following certifications, to make sure our merchants know that we take care of all data that goes through our (SAAS) platform.
- PCI DSS
- ISO 27001
- ISO 27701
- Are you PCI compliant? If not you can use our EBANX JS to tokenize your customer credit card and process the payment with no issues.
- Do you work with recurring payments and need to do a data migration? For that please contact our support team at integration@ebanx.com.
- Not sure what is the best checkout experience for your customers, please click here and follow the detailed instructions for each country.
Settlement and Reconciliation
What is the Settlement?
The settlement is the operation in which the Merchant will request the processed amount of their transactions that are available to be settled. At this moment, the applicable fees will be charged, and the money will be transferred to the Merchant bank account. The EBANX Dashboard shows the funds pending and available for settlement. Once payment is confirmed the amount will be "Pending for Settlement" until it's settled from the bank/partner to EBANX, then it will move to the "Ready for Settlement" balance. The timeframe to become ready for settlement varies per country and payment method. For example, credit cards in Brazil by default take 30 days, and debit take 2 days.
How to request a Settlement?
A Settlement can be requested manually via the EBANX Dashboard or we can set a frequency that could be Daily, Weekly, Monthly, or per amount. When the Settlement is triggered we start the remittance process which usually takes 5 days to be completed and the wire transfer to the merchant bank account happens.
Settlement report
Once a Settlement is completed, a report with all transactions and financial data is generated and available in the Dashboard in the XML format. We can also automate the Settlement Reports generation and deliver it to the merchant SFTP in CSV, XLSX, XML, and JSON formats. See more about the Settlement report in the Reports section of this document.
Anti-Fraud
Every country has a different fraud pattern, and fraud attacks require a lot of active support and customization from anti-fraud tools to prevent malicious actions. Thinking about this, EBANX has developed its own anti-fraud tool, EBANX Shield, a localized smart fraud prevention strategy that uses algorithms and machine learning to keep your operation safe and optimized. Merchants can also improve the anti-fraud effectiveness with special metadata fields to help with the risk analysis. EBANX has a few extra features to expand your anti-fraud capabilities, please reach out to your Account Manager for further information.
Introduction
Now that you have a good understanding of what is needed to start integrating with EBANX you are ready to do your first payment attempt and learn how to manipulate the payment object to your needs. EBANX supports four integration methods that can be used on your business that have different levels of effort and customization.
| Integration Methods | Effort | Customization |
|---|---|---|
| EBANX Direct API | High effort. Merchants must develop the whole checkout experience. | Full customization |
| EBANX Payment Page | Low effort. Merchants only need to call the EBANX Payment Page with the right parameter and EBANX will present the checkout experience, validate fields, and create payments. | Limited customization, just banners, names, and logos. |
| EBANX Payment by-link | No effort. Only ask for a payment link on the EBANX Dashboard and share it with your customer. | No customization |
| EBANX Drop-In | Medium Effort. Use a set of fields in an HTML form to call EBANX API. Fields and validations are done by EBANX. | Medium customization. Can customize the html/css page aspects with a few limitations |
How to use this guide
For this guide, we will go through the EBANX Direct API integration. Here you will learn how to create your first payment request and go through the operations necessary to complete the payment cycle. If you are not interested in developing your own direct integration EBANX also offers a plug-in EBANX is also compatible with the Shopify plugin. If you want to integrate using Shopify, please refer to the Shopify Installation guide.
Backend EBANX API Integration
The EBANX Merchant Account
The EBANX Merchant Account is an entity that supports your operation inside EBANX EBANX supports multiple countries, currencies, and payment methods in a single Merchant Account delivering a unique dashboard for all the accounts you want to have at the same operation model (Cross-border or Local).
caution
Don’t have access to the EBANX Dashboard? Click here to request the access through our onboarding form.
Using your Integration Key
The Integration section of the EBANX Dashboard will contain your private integration key, used to make the API calls to our servers. To access it, navigate to the dashboard, login with your credentials and click on the top right of the page through the Account Settings menu. In that menu, the Integration subpage should have your Test Integration Keys. You will also have access to the public integration key, which can be used in any of our EBANX.js tools. Make sure you understand the difference between the Integration Key and the Public Integration Key. Here is an example of how the integration key is used on our requests.
Here is an example of how the integration key is used on our requests:
Changing Operation Model
In order to select the correct operation model (see Cross-border or Local?) you have two options that can be used. Both options will have the same outcomes but one can favor your current backend logic while the other can offer a higher difficulty lever to implement for your structure.
caution
If you have a hybrid operation (both local and cross-border), there will be a dedicated integration key for each environment. Make sure you are using the correct key for each environment
Dedicated Endpoint
EBANX offers a dedicated endpoint for each of the operation models that can be reached, although the URLs will be different, the actual operation endpoint will be the same (i.e. /ws/direct for payments or /ws/refunds for refunds).
| Environment | Cross-border URL | Local URL |
|---|---|---|
| Sandbox | https://sandbox.ebanx.com | https://sandbox-local-latam.ebanx.com |
| Production | https://api.ebanx.com | https://api-local-latam.ebanx.com |
Header
Instead of changing the endpoint, we support the addition of a header on the request that will automatically route the request to our local environment. Remember to check if the integration key corresponds to the desired operation model.
EBANX Recommendations
Unique Identifiers
Every transaction request must have a unique identifier created by the merchant. An order number can also be assigned to a single or a group of transactions, the order number doesn’t have to be unique per payment, different from the merchant code. On transactional API responses, there will be another unique transaction ID from EBANX, a payment hash.
Customer information
EBANX is prepared to receive a number of different customer information fields. According to the country and operation, some fields may be mandatory while others won’t. Requirements will vary based on local legislation and market rules.
The main customer information fields are:
- address
- street_number
- city
- state
- zipcode
- birth_date
- name
- document
- telephone
- personal_document
- personal_birth_date
Most of these fields can be optional in all countries. The mandatory fields per country are:
- Name:
- All countries
- E-mail:
- All countries
- Personal Document:
- Brazil
- Uruguay
- Argentina
- South Africa
Payment method information
Each payment method will have different requirements both in terms of the information in the request payload and for the provided information in the response of your request. To exemplify this, here you can check that a credit card payment has the requirement of carrying the card data itself, in addition to information about how many installments this payment is processed in:
Meanwhile, the response carries the information EBANX gets from the downstream partners such as acquirers in order to qualify the payment. This can be seen in the “transaction_status” node inside the payment. In addition to that, the billing descriptor is returned, and a “payment_type_code” that matches the card scheme is also present in this card workflow, as well as approval and capture indicators(we will detail them in the payment operations).
As a counterpart, in the below PIX example you can see below what an instant cash payment transaction payload looks like, without any specific parameter required. This means that with only the basic transaction information and customer data you are able to initiate this payment. No details on the user's account is needed, and the PIX transaction is ready to be initiated:
The response, though, brings with it details that the customer will need in order to complete the transaction and have it be properly identified by EBANX. This includes a redirect URL that can be used to render the PIX unique identifier that the customer uses to make the payment and the QR code value itself, which can be used to render the value inside your own checkout page.
With these examples, you can see that different payment methods have slightly different requirements in how they are initiated, what data is required to properly initiate them and how our responses will vary depending on what payment method is being used. More details on the payloads and requirements for each payment method can be found in our extended documentation.
Payment Operations
One-time payments
If you deal with sales of goods or pre-paid services the one-time payment operation might suit your needs. EBANX supports one-time payments for Cards in all the available countries and the majority of Alternative Payment Methods.
Compatible Payment Methods:
- Credit Cards
- Debit Cards
- Pre-paid Cards
- Cash Payments
- Bank Transfers
- Non-recurring E-wallets
Below is a request format containing all the standard information to create a one-time payment request for the Brazilian country. Note that not all information is mandatory for all countries. Brazil is the most restricted one, so It’s a good place to start with.
One-time payment credit card request
One-time payment credit card response
Recurring payments
If you need to charge recurring payments from your customers, there are different ways to do it and EBANX has different products and features to support it. Compatible Payment Methods:
- Credit, Debit, and Pre-paid Cards *
- Nupay (BR)
- MPconnect (BR/MX/CL/UY) Debit in Brazil requires a pinless solution which is not available for all businesses. Please contact the Sales Engineering team for more information.
Credit, Debit, and Pre-paid Cards
EBANX Card Tokenization
By using this solution, we will be storing the cards in our vault and returning a token that can be used on recurring payments.
There are two options to create a credit card token:
- EBANX.js: In this method, you'll generate the token on the client side, using our EBANX.js javascript library, and send the token on your API call. This is the correct option in case you're not PCI compliant.
- Direct API: In this method, you'll use only our Direct API to create the token and add it to your payment. Keep in mind that you need to be PCI compliant to traffic sensitive data on your servers.
Create a token using EBANX.js 3. Add EBANX.js to your webpage
Our client SDK enables you to securely collect payment information from your customers. Add the following script to your webpage:
And initialize it with your Merchant's Configuration:
- Create an object with your payment information
- Create the token using EBANX.js
Call the EBANX.cardTokenizer.tokenize function passing the object created in the previous step.
EBANX.cardTokenizer.tokenize returns a Promise object, so, make sure you handle the asynchronous call properly by using a callback function. A successful token creation response contains the following fields. The values will vary for each token creation:
- Add the token to your payment request Include the token you obtained in the previous step to your card object in your Direct API call.
Recurrent payment credit card request:
Create a token using Direct API
- Call the /ws/token to create the token
Using the /ws/token API call, pass the credit card information, country, payment type, and your integration key. Here's an example:
A successful API call will return the following JSON object:
- Add the token to your payment request Include the token you obtained in the previous step to your card object in your Direct API call.
Recurrent payment credit card request
Importing Tokens
In case you want to import existing tokens from a different provider, you'll need to export them safely using an encryption key. Please use this public key to encrypt files from your existing provider before sending them to EBANX.
External Vault
In case you're PCI compliant and can retrieve the cards from an external vault for recurring payments, you can simply send us the raw PAN with no CVV and we can process it as well. Please note that recurring payments with subscriptions that were initiated with EBANX have more chances of being approved by our acquirers and issuer banks.
Refund
What is a refund?
A refund is when you have charged a payer, and need to cancel the payment and return the funds to the payer. In general, the funds will be returned to whatever payment method that the payer initially used to make the payment. When it's not possible to return to the original payment method, EBANX attempts other alternatives
Refund Flow
Basically, the refund process can only be triggered to already confirmed payments generated with your account. Payments with status open (OP) or pending (PE) cannot be refunded. To understand a little bit more how it works, take a look in the refund flow in the following diagram:
- The merchant requests the refund through the Dashboard or the API.
- This refund request gets directly into the EBANX refund queue, marked as Requested.
- EBANX then acknowledges the refund and the refund is marked as Pending.
- When the customer receives the money back (in his bank account or through his credit card, for example), the refund transitions its state to Confirmed.
General information:
- Each payment can have many refunds, given that the sum of their amounts does not exceed the original payment amount. Cancelled refunds do not count toward this sum;
- Only confirmed payments (CO) can be refunded;
- The currency of the refund is the same as the original payment;
- The merchant will be notified of refunds in 2 cases: when the refund is pending, and an email is sent to the customer asking for bank information, and when the refund is confirmed.
To refund a payment, you just need to call the end-point from your server with the following required fields.
Please, check the example below:
A successful request will return a JSON response similar to the one below.
Cancel
Whenever you want to cancel a transaction that has not yet been confirmed, you can use the cancel operation, this is especially useful if you want to make an uncaptured payment just to reserve the funds on the customer's card.
Make sure that the payment status is equal pending or open You can only cancel a payment if its status is equal to (OP) open or (PE) pending. You can check the status of your payment using the end-point ws/query.
Query the payment:
Cancel the payment using /ws/cancel end-point:
A successful request will return a JSON response similar to the one below.
Webhooks
How can you get notified that, after a customer has created a voucher payment, they have completed the payment? Asynchronous payments, updates to payments status and other changes that occur outside of your environment can be hard to track, as they rely on a multitude of systems that may rely on an offline transaction(such as the printing and payment of a voucher) or even on batch transactions from a bank, for example.
In these scenarios, EBANX handles all the downstream information gathering, and conveniently carries the burden of keeping track of status, completing transactions and updating all the required information.
For this information to reach your systems(such as to confirm to the customer that the payment is received and authorize the shipment of goods), EBANX provides a webhook notification system that will call out a preconfigured URL in your system with a minimum payload that identifies the update type and the payment that has been updated.
Our webhook payload will generally look like this:
This uniquely identifies the payment that has the update via the hash code and also indicates what type of notification is being sent, which can be already used to route automation inside your systems for cases of chargebacks and refunds, if that is the case.
In this case, when an update is being notified, it means that something changed in the payment, and you should be able to query that payment to get the most recent status.
Note that in the webhook payload, we only send the information that an update happened, and not the updated information. To get this information, it is fundamental that you query the original payment.
Additional information on the webhook functionality, such as the header signatures to ensure that the webhook comes from EBANX, the list of notification types and details on the query can be found in our extended documentation.
Reports
EBANX Settlement Report
For every settlement EBANX can send a report with the details of all the transactions, it is mainly used to do a financial conciliation. This will include the following information:
- General information about the settlement
- All payments entries, with all data collected and processed
- All refunds entries, with all data collected and processed
- All chargeback entries, with all data collected and processed
- All chargeback dispute entries, with all data collected and processed
EBANX transactional Reports
EBANX can send reports with the technical details of the requests made to EBANX, this would include more API fields like Status, Hash codes and timestamps. This report does not contain information about fees, and taxes. Regulatory and Compliance For some of the listed countries specific regulations apply. See here a list of those regulations for each specific country.
Regulatory and Compliance
For some of the listed countries specific regulations apply. See here a list of those regulations for each specific country.
Argentina
For Argentina due to regulatory requirements, all checkouts must present a breakdown of the IIBB (Ingresos Brutos) tax that can vary from 2% to 13.2% of the product value.
We recommend using the following text to clarify the user:
info
Spanish Note que, en base a la reglamentación del Impuesto a los Ingresos Brutos, se puede incluir un porcentaje variable entre 1% e 13.2% sobre el valor de la transacción en pesos, dependiendo del tipo de bienes / servicios adquiridos y su provincia.
info
English Note that, based on the Gross Income Tax regulations, a variable percentage between 1% and 13.2% can be included in the value of the transaction in pesos, depending on the type of goods/services purchased and its province.
Brazil
The IOF Federal Tax
The Brazilian Central Bank demands that any checkout experience, whenever a purchase is made that implies a currency exchange (i.e. a Cross-border operation in Brazil where EBANX settles to the Merchant), must exhibit the IOF (Imposto sobre Operação Financeira - Tax over Finance Operation) and made clear to the customer that this tax is applied to their purchase.
Here is an example of the IOF tax exhibition:
EBANX Disclaimer
Due to the Brazilian Central Bank resolution 277 merchants that are using EBANX as their payment solution must make available to the customer the EBANX terms and conditions, giving them clear access to EBANX sets of compliance rules.
Here is an example of the EBANX Disclaimer exhibition:
info
Portuguese Esta é uma compra internacional, mediante operação de câmbio, que será intermediada pelo EBANX de acordo com seus termos e condições. Ao clicar em pagar, você dá ciência e aceita os termos desta transação.
info
English This is an international purchase, through an exchange transaction, which will be intermediated by EBANX in accordance with its terms and conditions. By clicking pay, you acknowledge and accept the terms of this transaction.
If there are any questions on how to conduct this and other requirements, please reach out to integration@ebanx.com.
API Homologation
Integration checklist
Before launching in production please consider responding to the following checklist to ensure that there are no gaps in your integration.
| Action | Description | Mandatory |
|---|---|---|
| Direct Payment endpoint | Are you sending a payment request using /ws/direct endpoint, including the mandatory fields per country? | Yes |
| Refund endpoint | Are you sending requests to /ws/refund to refund customers? Note that it can be done manually in the EBANX Dashboard. | No |
| Capture endpoint | If you are using two-step payments (auto_capture=false), are you capturing the pending payment afterward using /ws/capture endpoint? It can be done manually in the EBANX Dashboard. | No |
| Cancel endpoint | If you are using two-step payments (auto_capture=false), are you canceling the pending payment afterward using /ws/cancel endpoint? Note that pending payments will be automatically canceled if not captured in X days ( it varies per payment method). It can be done manually in the EBANX Dashboard. | No |
| Query endpoint | Are you verifying payment status changes using /ws/query endpoint? Note that payment status, refunds, and chargebacks can be manually managed in the EBANX Dashboard. | No |
| Token endpoint | Are you tokenizing cards using /ws/token endpoint for recurring or one-click payments? For subscriptions, you can also store cards with an external vault provider and send us the raw PAN. | No |
| Card Verify endpoint | Are you sending a payment request using /ws/direct endpoint, including the mandatory fields per country? | Yes |
| Installments Plan endpoint | If you're charging the installment fees from your customers, are you using the /ws/installmentsPlan endpoint to calculate the final amounts for your checkout? Note that you can also calculate it by yourself based on your fees. This is not necessary for Chile, Colombia, and Peru, where the installment fees are handled by issuer banks directly . | No |
| Get FX Endpoint | If you're charging customers in USD, are you calculating and displaying the prices in local currency using the /ws/exchange? Note that we refresh the rates every 2 minutes and it's important to display reliable final prices in local currency for a better customer experience. | No |
| Website translation | Are you translating your Website to local languages? This is very important for the customer experience and better conversion rates. | No |
| Refund endpoint | Are you sending requests to /ws/refund to refund customers? Note that it can be done manually in the EBANX Dashboard. | No |
| IOF Calculation | If you're processing in Brazil, are you calculating the IOF on the final price and explicitly informing customers that the IOF is included? Note that even if you're absorbing this tax, you still need to inform that it is included in the price. | Yes (In Brazil for XB) |
| Central Bank Resolution Disclaimer | If you're processing in Brazil, are displaying the disclaimer informing the customer that there is an FX operation tied to the payment and EBANX will be managing that? | Yes (In Brazil for XB) |
| Retrieve the production key | Are you sending a payment request using /ws/direct endpoint, including the mandatory fields per country? | Yes |
| Upload the company logo | Have you submitted the company logo on the EBANX Dashboard? It will be displayed on the communication emails and our Payment Page. | No |
| Submit bank account | Have you submitted your bank account on the EBANX Dashboard and is it approved? This is necessary for the settlement and needs to be approved by our compliance team. | Yes |
| WebhookURL | If you're not sending this dynamically on the payment request, have you configured on the Dashboard your production webhook URL? Note that Webhook is not mandatory, but you may need to hit /ws/query endpoint more frequently to verify payment status changes. | No |
| Redirect URL | If you're not sending this dynamically on the payment request, have you configured on the Dashboard your production redirect URL? This is important to redirect customers to your Website after the payment completion when using the EBANX Payment Page or APMs that redirect to external platforms. | No |
| SFTP Report | Are you retrieving the settlement report and daily transaction report via the SFTP directory, and logon file provided by the integration team? | No |
Test Matrix
What is a Test Matrix?
An API testing matrix is an organized framework that outlines the test cases to be executed during the testing process of an Application Programming Interface (API). APIs consist of sets of rules and definitions that facilitate interaction between different software, enabling efficient communication and data exchange. Testing APIs is crucial to ensure they operate correctly, meeting both functional and non-functional requirements. The API testing matrix typically includes a list of test cases covering various scenarios, ranging from ideal situations to adverse conditions. Each test case details the input, expected output, and execution conditions, providing a comprehensive structure to validate the functionality of the API.
What to test?
Before starting testing our APIs, make sure that you already have your integration key. Keep in mind that for each scenario (sandbox and production) you'll have different integration keys. Pay attention to the two base_url endpoints for each scenario.
In sandbox: https://sandbox.ebanxpay.com/ws/ In production: https://api.ebanxpay.com/ws/
Sample Test Scenario
The table below presents some use cases and their descriptions and how to handle errors with its given error response samples.
For all given possible errors scenarios, please make reference to this section, where you can find more information about each situation.
| Use Case | Description | Possible Errors | Handling with Errors |
|---|---|---|---|
| Tokenize a card | Creates a token that can be used as a unique data in every transaction | Mistake information, Business Rule, Card Decline, Error Server | Check if the card data are correct, even though if it's been performed in the right environment (sandbox/production, crossborder or local) |
| Payments with cards | Simulates a card transaction using the credit/debit card data and customer data. It also can be tested with the tokenized card | Wrong country/currency, Insuficient funds, Payment method not active, Card type non matching with operation (e.g. try to process a debit card as a credit card) | Check some parameters such as country, currency, and payment method (note that installments are not available for debit cards) |
| Capture a payment | Captures a payment previously authorized. The auto_capture parameter has true as value | Wrong payment ID (hash), Wrong integration key, Inexistent payment, Payment already captured | Check if the payment is eligible to be captured, if it was not canceled or rejected |
| Query a payment | Seek for a payment using the unique ID generated by EBANX (hash) | Inexistent payment | Check if the payment's ID (hash) corresponding to given transaction |
| Refund a payment | A successful refund will retrieve the payment once made and confirmed to the payer. Note that this method is only available to payments with confirmed (CO) status | Payment already refunded, Payment with CA (canceled) status | Check if payment was already refunded, and check if the payment is with status CO (confirmed) |
| Cancel a payment | Only available to payments with status OP (open) or PE (pending). For confirmed (CO) payment status, a refund must be performed | Payment already canceled, Payment refunded | Check if the payment is with status CO (confirmed) |
Test Resources
For you to be able to successfully go live with EBANX in all of the supported countries, testing is one of the most important steps. To help you with that, please take advantage of all the resources that the EBANX team prepared for you:
- If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
- In case you’re already our partner please get in touch with our support team at integration@ebanx.com.