This page is intended to provide you with quick answers to common questions about integrating EBANX services. It covers topics such as API usage, payment processing, refund management, and security protocols. Whether you’re troubleshooting an issue or seeking clarification on specific features, the FAQ page serves as a valuable resource for streamlining your integration process and ensuring smooth transactions.
Getting started
How do I get integration keys?
Choose from the following:
New User To start you first integration, please complete the Merchant Signup Form to create an EBANX account. After the form has been submitted, we will contact you within 2 business days with log in instructions. Once you receive log in instructions, go to the EBANX Dashboard to obtain your integration key which is needed to integrate your site with EBANX.
Existing User
Log in to your EBANX Dashboard to obtain your integration key.
How do I get a Sandbox account?
If you're in contact with one of our Business Development representatives, you can request access to the EBANX Dashboard in Sandbox mode. Alternatively, complete the Merchant Signup Form to create an EBANX account.
How do I get started with EBANX?
To get started with EBANX, integrate your eCommerce store and offer the most popular payment methods across multiple countries. This integration allows you to tap into new markets, significantly boosting sales by providing localized payment options that are familiar and trusted by consumers in the region. For detailed instructions, visit the Get Started guide.
What payment methods can I accept through EBANX?
Through EBANX, you can accept a wide variety of local payment methods. These include:
- Credit and Debit Cards
- Digital Wallets
- Bank Transfers
- Cash Payments
- Alternative Payment Methods
You can also offer local installments and voucher-based payments that are widely used in certain countries.
Visit the Get Started guide to explore the full list of payment methods.
Going live
What is the difference between the Integration Key and the Public Integration Key?
- Integration Key - This is the private key used by merchants for server-side operations, such as making payments, handling refunds, and managing other sensitive operations. It should be kept secure and never exposed to client-side code, as it allows access to critical functionality in the EBANX API.
- Public Integration Key - This is the public-facing key used in client-side interactions, such as when integrating payment forms through EBANX.js. It allows the front end to interact with EBANX securely while still protecting the more sensitive aspects of the integration. Since it’s used in public contexts (like JavaScript), it has limited functionality compared to the private Integration Key.
I am having problems with my integration key, such as invalid integration key error. What can I do?
Please verify that you’re using the correct integration key for the appropriate environment. A common issue is mistakenly using a test key in the production environment, or a live key in the test environment. If the issue persists, feel free to reach out to us at sales.engineering@ebanx.com for further assistance.
I just received my live integration keys. What should I do now?
First, replace your test integration key with the new live key to ensure that all transactions are processed through your live account. Additionally, make sure to disable test mode in your application if needed. Lastly, configure your live account settings in the EBANX Dashboard, including your logo, Notification URL, credentials, and other relevant settings. This ensures that your integration is fully functional and tailored to your business needs.
When I receive my live credentials, will I lose my sandbox credentials?
No, your sandbox credentials will remain active even after you receive your live credentials. You can continue using them for testing purposes. If you’re planning to enable new features, such as accepting payments in additional countries, you’ll need to use your sandbox account to thoroughly test those functionalities before going live.
I have finished my tests, can I go into production?
You are almost ready. After completing your tests, please contact us at sales.engineering@ebanx.com, and we will conduct our own validation tests to ensure your integration is functioning properly. This process is typically handled very quickly. Once the tests are successful, we’ll create your production account and provide you with your live credentials so you can begin processing real transactions.
How soon can I get my live keys?
Once your integration is ready, reach out to us at sales.engineering@ebanx.com. We will run some tests on your integration, and upon successful validation, we’ll send you your live keys as quickly as possible. The process is usually handled promptly to ensure a smooth transition into production.
I created additional users in the EBANX Dashboard for my sandbox account. Are those users available on the new live account?
No, any additional users created in your sandbox account will not be transferred to the live account. If you need the same users on your live account, you’ll have to create them again manually. Alternatively, feel free to contact us, and we can assist you with setting them up.
I can’t see my LIVE payments on the Dashboard. Why?
In your EBANX Dashboard, locate the “Sandbox mode” button at the bottom left corner and ensure that it is disabled. This will switch your view to your live account, allowing you to access and manage your live payments.
Payments
What are the response codes EBANX returns to merchants in case of payment failure?
When a credit card payment is rejected, the EBANX API may return two types of errors to the merchant: Soft Declines and Hard Declines. These error codes are usually provided immediately after payment rejection, and merchants can query the payment for more detailed information.
- Soft Declined - This occurs when the issuing bank refuses the transaction due to issues during the authorization process. Common reasons include insufficient funds or incorrect card details.
- Hard Declined - These are declines based on EBANX’s predefined business rules. For example, if the payment amount exceeds the allowed limit for a specific payment method. See Error Code Guide for more information
By differentiating between soft and hard declines, EBANX helps merchants identify the root cause of payment failures and take appropriate actions.
How can I enable more payment methods or add new countries to my account?
If you’d like to enable additional payment methods or expand to new countries, please contact your account manager or business development representative. They will guide you through the process, and once everything is set up, these options will be activated on your account.
What is the difference between the PIN and Payment Hash Code?
Both the PIN and Hash are unique identifiers generated by EBANX when a payment is created, but they serve different purposes:
- PIN - A unique payment ID primarily used for searching payments in the EBANX Dashboard. It is also displayed on the user’s receipt for reference.
- Payment Hash Code - A unique identifier used in API operations, such as querying payment details, cancelling a payment, or requesting a refund. The Payment Hash is essential for integration purposes in both Direct API and Checkout integrations.
I’m getting an error message saying that the payment type is not enabled for a merchant.
If this error occurs in your sandbox account, please reach out to us at sales.engineering@ebanx.com, providing your merchant name and details about the issue. We will resolve it promptly.
If the error is in your production account, ensure the payment method you’re attempting to use is included in your signed agreement. For further assistance, you can contact your account manager or business development representative to address the issue and enable the required payment method.
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.
- Merchant Payment Code - This is a unique identifier for each payment in the EBANX system. You cannot create multiple payments with the same merchant payment code in your account. It’s used to ensure that each transaction is unique and easily identifiable.
- Order Number - Unlike the merchant payment code, the order number is not unique. You can create multiple payments with the same order number, which makes it useful for grouping related transactions (e.g., when a customer retries a payment multiple times during checkout). This field can help you track a set of related payments.
Can I disable the emails that EBANX sends to my customers?
Unfortunately, you cannot stop EBANX from sending emails to customers. These emails contain crucial information about their payments, which are required to be sent for compliance and legal reasons. This ensures that customers receive essential updates about their transactions.
What is the different between payment and payout?
Payment - The process of charging your customers for products or services they purchase from your store. It involves collecting funds from the buyer.
Payout - The process of transferring funds to a payee, such as a vendor, affiliate, or contractor. This typically happens when you need to pay out earnings or commissions to someone else.
Payment methods
Why am I getting an error message saying that the payment type is not enabled for a merchant?
If this error occurs in your sandbox account, you can reach out to us at sales.engineering@ebanx.com, providing your merchant name and details about the issue. We will resolve it promptly.
In your production account, this error typically happens when the payment method you are trying to use is not included in your signed agreement with EBANX. To verify or update the available payment methods, please contact your account manager or business development representative for assistance.
Credit card payments
Do I need an SSL certificate?
Yes, having an SSL certificate for your checkout page is highly recommended. It increases customer trust and reduces the likelihood of abandoned carts, as it helps customers feel secure when entering their payment information.
If you are processing credit card payments through the Direct API integration, SSL is mandatory to ensure secure data transmission. However, if your website does not have SSL, you can use the EBANX Payment Page, which provides a secure, hosted environment for payment processing.
Do I need to keep the customer’s card information?
We will retrieve the customer’s credit card information based on the token provided. For best results, we strongly recommend sending both the token and the CVV during the payment process, as this can significantly improve your approval rates by providing additional security measures to the card issuer.
Recurring payments
Do recurring payments work automatically?
No. Each time you need to charge your customer, you must submit a new request (e.g., for every month, quarter, year, etc.). How can you do this? Check out our guide for creating Recurring Payments, which explains how to implement tokenization for streamlined, secure payments.
How long is the token for the recurring payment valid for?
Tokens for recurring payments are valid for 14 months from their last use. If the token is not used within this period, it will expire and you’ll need to request a new token to continue processing payments.
For recurring payments, can recurring periods be set to weekly, monthly, or annually?
Yes, you can set your recurring payment schedule to whatever suits your business model, whether it’s weekly, monthly, annually, or even daily. You simply need to make a request using the token that was generated for your customer whenever you want to process a charge. You have full control over the timing of the charges, but it’s important to ensure that your customers are informed about the recurring payments and their schedule.
How can I get information about failed recurring payment transactions via the API?
If a transaction fails, we will provide the reason for the failure in the response, along with one of the following status codes:
- OK - The transaction was approved successfully.
- NOK - The transaction was not approved by the acquirer. The customer should contact their card issuer to resolve any issues with the card.
- RETRY - Something went wrong during the process. You can retry the transaction with the same data. We recommend attempting up to three more times, with increasing intervals between retries (e.g., try again after 2 hours).
These status codes help you identify the issue and decide on the next steps for handling the transaction.
How can I cancel a customer’s recurring payments after they have been set up?
If you no longer want to charge a customer, you don’t need to disable recurring payments entirely. Instead, you can simply stop sending requests using that customer’s token to EBANX. This way, the recurring payment will effectively be paused without needing to turn off the recurring payments feature.
Notifications
What are Notifications and how do they work?
When a payment status changes, EBANX sends a notification to your system through the Notification URL configured in your Dashboard. Upon receiving the notification, your system can then call the Query Operation to retrieve the current status and additional details about the payment.
After processing the notification, your system should return a response (any string of your choice) to confirm that the notification was successfully received. You can review all notifications in the Notification Log within your Dashboard.
Notifications are crucial for knowing when it’s safe to deliver your product or service to the customer.
For more in-depth technical information, visit our Payment Notification Guide.
What about my notification URL?
After setting up your live account, it’s crucial to configure your Notification URL to receive all incoming EBANX notifications.
Many merchants experience issues when moving to the live environment because they forget to update their Notification URLs for the live account. Be sure to configure your URL correctly to avoid disruptions.
When setting up your URL, make sure you're using the correct live environment URL and not the one from your test environment. Also, ensure that the URL uses HTTPS instead of HTTP. For detailed instructions on how to configure your Notification URL, visit our Payment Notification Guide.
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.