Frequently Asked Questions
Getting Started
How do I get the integration keys?
Once you have a Business Account set up, you can find your integration keys on your EBANX Dashboard settings. For further details, you can refer to this file.
How do I get Sandbox account?
If you are in touch with any of our Business Development representatives, you can ask them to provide you access to our EBANX Dashboard in Sandbox (test mode). Otherwise, you can access dashboard.ebanx.com and register to get access to it.
How do I get started with EBANX?
You can connect your Commerce store to a EBANX account and start increasing your sales by offering the most relevant payment methods across Latina America . To learn more, visit here.
What payment methods can I accept through EBANX?
Once you are integrated with EBANX, your company can access new consumers located in the fastest growing markets in Latin America.
With just one integration, you can offer local payment options to consumers from Brazil, Mexico, Argentina, Colombia, Chile, Peru and Ecuador, significantly increasing sales throughout the region. See the full list of available payment methods here.
Going Live
What is the difference between the Integration Key and the Public Integration Key?
The Integration Key is used to make requests to our API operations. Keep it safe and do not expose this information.
The Public Integration Key is used to make token operations from your customerâs client (browser, app, etc.). By doing this, you donât have to deal directly with your customerâs credit card sensitive information.
I am having problems with my integration key, such as invalid integration key error. What can I do?
Please check that you are using the right integration key in the right environment. A common mistake is to use a test integration key in the production environment and vice-versa. If the error persists, please contact our integration@ebanx.com.
I just received my live integration keys. What should I do now?
First, you should replace your old test integration key with the new âliveâ key, so that all payments can be redirected to your live account. Also, you might need to turn off the test mode in your application (if necessary) and configure your new account with your logo, Notification URL, credentials, etc., in your account in our Dashboard.
When I receive my live credentials, will I lose my sandbox credentials?
Your sandbox credentials will not be deleted. You can still use them if you want to run some tests. Also, if youâre planning on enabling new features, such as payments in new countries, you will need to use your sandbox account to test them.
I have finished my tests, can I go into production?
Not quite yet! Once you have completed your tests, please contact us through integration@ebanx.com and we will run some tests of our own to check if your integration is working properly(donât worry, this requests is usually handled very quickly!). After that, we will create your production account and send you your credentials.
How soon can I get my live keys?
After getting all your integration ready, please let us know through integration@ebanx.com so we can do some testing and send your live keys as soon as possible.
I created additional users in the EBANX Dashboard for my sandbox account. Are those users available on the new live account?
No. The live account does not use any of the previous Dashboard users. If you need those, youâll need to create them again or let us know, ok?
I canât see my LIVE payments on the Dashboard. Why?
In your EBANX Dashboard, click the âSandbox modeâ button at the bottom left side and make sure that it is disabled. This way, you switch your view to your live account and you will be able to see your live payments.
Payments
What are the response codes EBANX return to Merchant in case of payment failure?
Upon the credit card payment rejection the EBANX API may return 2 types of errors to Merchant: Soft declined and Hard declined. Those messages / codes are usually returned right after the payment rejection and you can query the payment to retrieve more details.
1 â Soft declined: Is executed by a credit card processor when the issuing bank refuses the transaction because something has gone wrong in the authorization process. I.e insufficient funds. You can get more details about our responses here.
2 â Hard declined: Pre defined EBANX business rules that can decline a transaction. I.e the payment amount has exceed the maximum amount allowed for that specific payment type. You can get more details about our error codes here.
I want to have more payment methods enabled on my account and/or add new countries
Once you have ânished testing these new features, please contact your account manager or business developer. After your documentation is ready for those new features, we will enable them on your account.
What is the difference between the PIN and payment Hash code?
Both PIN and Hash are the unique payment ID that is generated in EBANX once a payment is created. The PIN can be used to search for a payment in the EBANX Dashboard and is also showed in the user receipt. The payment Hash code is used to retrieve payment details using our query operation (for Direct API and Checkout integrations) and also to cancel a payment and request refunds.
Iâm getting an error message saying that the payment type is not enabled for a merchant
If this error happens in your sandbox account, you can contact us through integration@ebanx.com informing us your merchant name and the issue will be quickly resolved. If you are in your production account, please make sure that the payment method that you are trying to use is included in the agreement that you signed. You can contact your account manager or business development representative to solve this.
One of my customers tried to make a payment and received the error âBP-DR-98 â Customer country does not matchâ
What happened is that your customer probably has an email registered in a specific country (willian@gmail.com in Brazil, for example) and tried to use the same email to make a payment in a different country. To solve this, you can ask your customer to use another email.
What is the difference between payment.order_number and payment.merchant_payment_code?
The Merchant Payment code is a unique identifier of your payment in our system; our system will not generate new payments with a merchant payment code that already exists on your account. The order number is not an unique identifier so that you can create payments with the same order number. You can use this field to identify a group of payments, like retries of a customer at the same checkout.
Can I disable the emails that EBANX sends to my customers?
Unfortunately you canât. The emails that EBANX sends out to customers have important information about their payments that needs to be sent for compliance and legal reasons.
What is the different between payment and payout?
Payment is how to charge your customer on your store. Payout is how you make a payment for your payee.
Payment Methods
Iâm getting an error message saying that the payment type is not enabled for a merchant. Why?
If this error happens in your sandbox account, you can contact us through integration@ebanx.com informing us your merchant name and the issue will be quickly resolved. If you are in your production account, please make sure that the payment method that you are trying to use is included in the agreement that you signed. You can contact your account manager, or business developer, for this information.
Credit Card Payments
Do I need an SSL certificate?
Having an SSL certificate for your checkout page decreases the chances of your customers giving up on their purchase since this has been proved to make customers feel safe about entering their payment information. If you are going to process credit card payments using the Direct API integration, SSL is mandatory. If your website does not have SSL, you can use our EBANX Payment Page.
Do I need to keep the customerâs card information?
We will retrieve the customerâs credit card information based on the token. We strongly suggest to send the token + CVV as this may improve your approval rates.
Recurring Payments
Do recurring payments work automatically?
No, they donât. Every time you want to charge your customer you have to make a new request (for instance, not just in the first month, but every month/quarter/year, etc). How can you do that? See our documentation on how to create recurring payments HERE.
How long is the token for the recurring payment valid for?
Tokens expire after 14 months of their last use.
For recurring payments, can recurring periods be set to weekly/monthly/annually?
You can choose whichever recurring profile works best for your business: Weekly/Month/Annually/Daily. You just need to make a request using the token that you generated whenever you want to charge your customer and you control when you want to do that. Please just remember to communicate with your customer about those charges.
If the recurring payments fail to charge customerâs card for whatever reasons (such as expired card, insufficient funds or wrong expiration date), how can I get information about failed transactions using an API so I can stop a customerâs subscription and notify them about the situation?
If the transaction does not go through, we will specify the reason for the failure in our request response. We use the following transaction status codes:
OK: The transaction amount was approved.
NOK: The acquirer did not approve the transaction. The customer must contact the issuer to check if there is any issue with the credit card.
RETRY: Something went wrong with the process. You can retry with the same data. We recommend you to try 3 more 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
How can I cancel a customerâs recurring payments after they have been set up?
If you do not want to charge a customer you donât need to turn recurring payments off, you can just stop requests with that token to EBANX.
Handling Notification
What are the Notifications and how do they work?
When a payment status is changed, EBANX sends a notification to your system through the Notification URL that you have set in your Dashboard. Your system receives the notification then call our Query Operation. By doing this, you will know the status and more information about that payment.
After you get the notification, you must output a response (it can be any string that you like) indicating that the notification was successful. You can check your notifications in the Notification Log in your Dashboard.
Notifications are important since they indicate when you can deliver your product/service to your customer.
For more detailed and technical information check out our documentation HERE.
What about my Notification URL?
Once youâve got your live account, it is very important to configure your URL and receive all incoming EBANX notifications.
Donât forget to configure your URL, as some merchants have problems when moving to the live environment because they forgot to set their URLs to the new account.
When youâre doing this configuration, please make sure that youâre using the right URL (your live details), not the URL from your test environment. Also, please make sure youâre using https, instead of HTTP. How you change this configuration? HERE is a link to our documentation that deals with that.