Here you will find some frequently asked questions about our integration, notifications, your credentials, tips to improve your sales and some more. But don’t worry if you didn’t find what you are looking for. We will add more questions as doubts are arising, ok?

And, if you have a different one, don’t hesitate and send an email to EBANX Integration Team ( We will be happy to help you answering your questions.

I created additional credentials for my sandbox account. Are those credentials available on the new live account?

No. The live account does not use any of the previous credentials. If you need these, you’ll need to create them again, ok?

What about my Notification URL?

Once you’ve got your live account, its very important to configure your URL and receive all incoming EBANX notifications, only now within the live environment.

Don’t forget to configure your URL, because 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 check to make sure you’re using https, instead of HTTP. Where you change this configuration? HERE is a link to our documentation that deals with that.

I just received my live credentials. What should I do, now?

OK – first, you should change your old test integration key for the new “live” key, so all payments will now be directed to your live account. Also, you may 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? Will I need those credentials, anymore?

Your sandbox credentials will not be deleted. You can still use them if you want to run some tests. Also, if you’re going to enable new features, such as payments in new countries, you will need to use your sandbox account to test them.

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 the payment is created. PIN can be used to search a payment in 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 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

I get an error message, saying that the payment type is not enabled for a merchant. How can I solve this?

If this error happens in your sandbox account, you can contact our Integration Team with your merchant name and it 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.

I have finished my tests, can I go into production?

Not quite yet! Once you have completed your tests, please contact our Integration Team. We will make some tests of our own to check that your integration is working correctly. After that, we will create your production account and send you your credentials.

I want to have more payment methods enabled on my account and/or add new countries. How do I do this?

Once you have finished 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 to your account.

What is the difference between the Integration Key and the Public Integration Key?

The Integration Key is the key that you use to make requests to our API operations. Keep it safe and do not expose this information.

The Public Integration Key is the key that you use to make the token operation, using this key from the client of your customer (browser, app, etc.). By doing this, you don’t have to deal directly with the credit card information of your customer.

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 (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 will indicate when you can deliver your product/service to your customer.

For more detailed and technical information check our documentation here.

One of my customers tried to make a payment and received the error “BP-DR-98 – Customer country does not match”. What happened?

What happened is that your customer used an email to make a payment in a country ( 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 a another email.

What is the difference between payment.order_number and payment.merchant_payment_code?

Merchant Payment code is a unique identifier of your payment on our system; our system will not generate new payments with merchant payment code that already exists on your account. Order Number is not a 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 the customer at the same checkout.

I can’t see my live payments on the Dashboard, how can I solve this?

On your Dashboard, you just have to click the button on the bottom left, “Sandbox mode”, and make sure that is disabled. That way, you switch your view to your live account, and you will be able to see your live payments.

Pay attention: if your Dashboard has one yellow box like the one below, it means that you are in the sandbox mode.

How soon can I get my live keys?

After all your integrations get ready, and all problems solved, our Integration Team can make the test and send your live keys on the same day.

Do I need SSL Certification?

Having SSL Certification on your checkout page decreases the chances of your customers giving up on their purchase because this certification has been shown to make customers feel safe about entering their information on your website.

Look at the following topics:

  • What fields need to be completed on my checkout page?

We suggest that you put the minimum amount of fields necessary on your checkout page, to improve user experience. The use of input mask on these fields is appreciated.

  • Should I present my checkout in Portuguese?

We strongly suggest, that as a minimum your checkout page is translated to Portuguese (Brazilian Portuguese). We know that translating English terms into Portuguese can be tricky, but you can always ask for help from our Integration Team.

  • Should I use EBANX’s zip code operation?

Using the zip code operation can make check out the process quicker and easier. You just send us your integration key and the zipcode as parameters, and we automatically return the state, city and street name of that zip code. You can find more information about the zip code operation here..

Translating fields, error messages and relevant terms

Having translated fields, error messages and relevant terms in certain parts of your site can help a lot your Brazilian customers. You can learn more about these in our documentation.

Do recurring payments work automatically?

No, they do not. Every time you want to charge your customer you have to make a new request (ie not just in the first month, but every month/quarter/year, etc). How do you so that? See our documentation about how to create recurring payments HERE.

How long is the token for the recurring payment valid for? Is there an expiration date?

Tokens expire after 14 months of it’s last use.

What recurring periods are available? Can recurring periods be set to be weekly/monthly/annually?

You can choose wherever 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 these charges.

If the recurring payments fails to charge customer’s card for whatever reasons (such as: the card is expired, or insufficient funds or the expiry date has changed), how can I get information about failed transactions using an API so I can stop customer’s subscription and notify the customer about the situation?

If the transaction does not go through, we will return 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 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.

How can I cancel a customer’s recurring payments after they have been set up, using API?

If you do not want to charge a customer you don’t need to turn recurring payments off, you just stop sending requests with that token to EBANX.

Do I need to keep the customer’s card information?

You just need to keep the token. When you generate a token, we will retrieve these credit card informations, so you don’t need to do that, but if you are able send the CVV, your approval rates should increase by 15-20%. So, our recommendation for this case is that you send the token plues the CVV.

Can I disable the emails that EBANX send to my customers?

Unfortunately, no, you can’t. The e-mails that EBANX sends out to customers have important information about the payments that needs to be shown for compliance and legal reasons.

What is the different between payment and payout?

Payment is how to charge your common customer on your store. Payout is how you make a payment for your payee.

If you still have any questions, please send an e-mail to EBANX Integration Team at and we will be happy answer those questions