Payment Page

This guide explains how to automate API requests for generating an EBANX Payment Page. If you’re new to this integration method, we recommend reviewing the EBANX Payment Page Product Info for a comprehensive overview. Please follow the instructions below to use this feature.

Requirements

• API authentication - All API requests must be authenticated using JWS (JSON Web Signature). The legacy integration_key is being deprecated — if you still use it, follow the Migration Guide to transition to JWS. If you don't have credentials yet, complete the Merchant Signup Form.

Instructions

Follow the steps below.

1. 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.

   Check the method's availability for your country and tenant in Payment Methods by Country. Questions about tenant and environment? Check our API Operability and API Endpoints.

   Cross-border sandbox

   https://sandbox.ebanxpay.com/ws/request

2. Base parameters

   To redirect your customers to a payment page hosted by EBANX, you will need to send an HTTP request to /ws/request to obtain a Payment Page URL. When sending a request, some parameters are country specific. Use the selector below to view unique values for each country.

   Select a country

   Parameter	Description
   country	Two-letter country code. ar : Argentina
   integration_key	Your EBANX integration key.
   name	Customer name.
   email	Customer email address.
   payment_type_code	Allowed payment types. Options: _creditcard debitcard debin mercadopago pagofacil rapipago _all Select 1 or more individual payment methods, or select _all. For a complete list, see Payment Type Codes.
   currency_code	The currency code of your transaction. Options: ARS : Argentine Pesos USD : US Dollars
   amount	Transaction amount, in the specified currency. E.g.,: 100.50
   merchant_payment_code	Unique identifier for this payment (usually the order number from your system).

   Note: If you want to use Euros as the currency in your Payment Page or Direct API, please contact your sales engineer at sales.engineering@ebanx.com.

3. Sample request

   Use the following example to initiate a request.

   JavaScript

   curl -X POST \
     --location 'https://sandbox.ebanxpay.com/ws/request' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "****************", // Your EBANX integration_key
       "name": "José Silva",
       "email": "josesilva@example.com",
       "country": "ar", // 2 digit country code.
       "payment_type_code": "_all",
       "merchant_payment_code": "0x0W26D05-T10",
       "currency_code": "ARS",
       "amount": 1000
     }'

4. Sample response

   A successful request will return a JSON response similar to the example below. The redirection link, found in the redirect_url parameter, will guide your customers to the payment page.

   JavaScript

   {
     "payment": {
       "hash": "5ef6208cc0ae84cee0a3850148e1417a0a2e70495c6b2807",
       "country": "ar",
       "merchant_payment_code": "0x0W26D05-T10",
       "order_number": null,
       "status": "OP",
       "status_date": null,
       "open_date": "2020-06-26 16:21:31",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": 1000,
       "amount_ext": 996.2143853357243,
       "amount_iof": 3.79,
       "amount_ext_requested": "1000.00",
       "currency_rate": 1,
       "currency_ext": "ARS",
       "due_date": "2020-06-29",
       "instalments": 1,
       "payment_type_code": "_all",
       "pre_approved": false,
       "capture_available": null
     },
     "redirect_url": "https://sandbox.ebanxpay.com/checkout?hash=5ef6208cc0ae84cee0a3850148e1417a0a2e70495c6b2807",
     "status": "SUCCESS"
     }

   The redirect_url contains a url for redirecting customers to a web-based payment page.

5. Redirect customer to Payment Page

   Redirect your customer to the URL provided in the redirect_url field, which will forward them to the EBANX Payment Page.

   JSON

   {
     "redirect_url": "https://sandbox.ebanxpay.com/checkout?hash=5ef6208cc0ae84cee0a3850148e1417a0a2e70495c6b2807"
   }

   Example screenshot of a payment page (redirect_url) in Brazil.

6. Confirmation

   Once your customer completes the purchase, they will be redirected to a "Thank You" page similar to the one below, with an option to return to your website.

   Example Screenshot of Thank You Page.

   
   

   If the customer does not complete payment, the transaction will automatically cancel after a predefined period.

   
   
   Info

   You can configure the return URL in your Merchant Area, or include it as the redirect_url parameter in the /ws/request API call.

7. Custom Domain Setup

   This step applies only if your Payment Page uses Custom Branding & Domain with your own subdomain, such as checkout.mycompany.com. If you use the standard EBANX address, your integration is already complete — skip to the next step.

   Info

   Custom domains require a subdomain. checkout.mycompany.com is supported; the root domain mycompany.com is not.

   Security prerequisites

   • HTTPS with an active SSL certificate - the subdomain must be served over HTTPS. EBANX requests, validates, and renews the certificate for you; you do not need to buy or install one.
   • A CNAME record pointing to the EBANX domain - traffic for your subdomain must be routed to the EBANX checkout through a CNAME record that your DNS team creates.

   Both requirements are met by adding the two DNS records below in your DNS provider. Your Sales Engineer provides the exact Record Name and Record Value for each one.

   Step 1 - Request the certificate for your domain

   Send your Sales Engineer the subdomain you want to use. EBANX registers it and requests the SSL certificate, then returns the values for Record 1. No action is required on your side until you receive them.

   Step 2 - Add Record 1: domain ownership validation

   This record proves to the certificate authority that you own the domain. It does not route any traffic and has no effect on your live site, because it uses a separate validation subdomain that starts with _.

   Field	What EBANX provides	Example
   Type	CNAME	CNAME
   Record Name	A validation subdomain starting with _	_abc123.checkout.mycompany.com
   Record Value	An AWS validation address	_xyz456.acm-validations.aws
   TTL	300, or your DNS provider's default	300

   Step 3 - Certificate validation and issuance

   Once the record propagates, EBANX detects it automatically and the certificate is issued. There is nothing for you to do at this stage: you do not need to confirm anything or notify EBANX. Propagation usually takes from 15 minutes to a few hours.

   Step 4 - Add Record 2: point your domain to EBANX

   After the certificate is issued, EBANX creates the checkout configuration for your domain and sends you the values for Record 2. This record routes traffic from your subdomain to the EBANX checkout, and affects only that subdomain — your main domain and any other subdomain are untouched.

   Field	What EBANX provides	Example
   Type	CNAME	CNAME
   Record Name	Your checkout subdomain	checkout.mycompany.com
   Record Value	An EBANX address	d-xxxx.cloudfront.net
   TTL	300, or your DNS provider's default	300

   When this record propagates, the custom domain is active. Your Sales Engineer confirms the activation and sends you a test link.

   How the status advances

   You do not trigger any of the transitions below: EBANX monitors your DNS records and advances the status automatically.

   Status	What it means	What you need to do
   Pending	The certificate has been requested and EBANX is waiting for the validation record to propagate.	Add Record 1, then wait.
   Issued	The domain was validated and the certificate was issued. EBANX prepares the checkout configuration for your domain.	Nothing. Wait for the Record 2 values.
   Deployed	The checkout configuration is live and serving your subdomain.	Add Record 2, then confirm the test link.

   Expected timeline

   Step	Typical time
   Add Record 1	15 minutes
   DNS propagation for Record 1	15 minutes to a few hours (rarely up to 72 hours)
   EBANX prepares Record 2 after validation	Usually the same day
   Add Record 2	15 minutes
   DNS propagation for Record 2	15 minutes to a few hours

   Common questions from DNS teams

   Question	Answer
   Do we generate the SSL certificate?	No. EBANX requests, validates, and renews it. You only add the two CNAME records.
   Does adding Record 1 affect our live site?	No. It is a separate validation subdomain starting with _, with no effect on existing DNS or live traffic.
   Does adding Record 2 affect our live site?	It affects only the subdomain you configured, such as checkout.mycompany.com. Your main domain and other subdomains are not affected.
   Can we use our root domain?	No. Only subdomains are supported, such as checkout.mycompany.com or pay.mycompany.com.
   Which DNS providers are supported?	Any provider that supports CNAME records, including Cloudflare, Route 53, GoDaddy, and Namecheap.
   What if propagation takes longer than expected?	Contact your Sales Engineer - they can check the validation status on the EBANX side.

8. Congratulations!

   You have successfully generated an EBANX hosted Payment Page.

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.

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

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.