Skip to main content
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 credentials - Ensure you have your EBANX integration key. If not, 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.

    https://sandbox.ebanx.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:​

    ParameterDescription
    country
    Two-letter country code.
    br : brazil
    integration_keyYour unique and secret integration key.
    nameCustomer name.
    emailCustomer email address.
    payment_type_code
    Allowed payment types.
    Options:
    • boleto : Boleto Bancário
    • _creditcard : Credit Cards
    • debitcard : Debit Cards
    • mercadopago : Mercado Pago
    • nupay : NuPay
    • nupay-recurrent : NuPay Recurrent
    • paypal : PayPal
    • picpay : Picpay
    • pix : Pix
    • _all : All Payment Types
    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:
    • BRL : Brazilian Real
    • EUR : Euros
    • USD : US Dollars
    amountTransaction amount, in the specified currency. E.g.,: 100.50
    merchant_payment_codeUnique 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.

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/request' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "****************", // Your EBANX integration_key.
        "operation": "request",
        "name": "José Silva",
        "email": "josesilva@example.com",
        "country": "br", // 2 digit country code.
        "payment_type_code": "_all",
        "merchant_payment_code": "0x0W26D05-T10",
        "currency_code": "BRL",
        "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.

    {
      "payment": {
        "hash": "5ef6208cc0ae84cee0a3850148e1417a0a2e70495c6b2807",
        "country": "br",
        "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": "BRL",
        "due_date": "2020-06-29",
        "instalments": 1,
        "payment_type_code": "_all",
        "pre_approved": false,
        "capture_available": null
      },
      "redirect_url": "https://sandbox.ebanx.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.

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

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

    EBANX Payment page

  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.

    EBANX Payment 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 EBANX dashboard, or include it as the return_url parameter in the /ws/request API call.

  7. Congratulations!

    You have succesfully generated an EBANX hosted Payment Page.


Resources​

Use the following resources when testing in your sandbox environment.

Credit Card Icon

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right
Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

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

Click to explorechevron_right
Debit Card Icon

Error Codes

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

Click to explorechevron_right

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: