Skip to main content

Online Debit

Online Debit with EBANX offers a secure, real-time payment solution that allows customers to complete transactions directly through their online banking. When using Online Debit, customers are seamlessly redirected from your platform to their bank’s website, where all payment details are pre-filled, enabling a fast and safe checkout experience. This integration is especially popular in Latin America, as it provides a familiar and trusted method for consumers to pay directly from their bank accounts.

Requirements​

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
  • Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.

How it works​

  • Define payment parameters - Collect essential details, such as amount, currency, and customer information.
  • Request redirection link - Call the ws/request endpoint with required fields to generate the Online Debit redirection link.
  • Redirect customer - Use the payment.redirect_url to send customers to their online banking environment to complete the payment.
  • Listen for notifications - Receive payment status updates from EBANX.
  • Confirm payment - Check the status for completed payments.

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/direct

  2. Define your parameters

    With Online Debit, customers are redirected to their online banking site, where they can complete the payment securely and quickly. To obtain this redirection link, call the ws/direct endpoint with the required fields:

    Basic parameters:​

    ParameterDescription
    operationSet to request
    integration_keyYour EBANX integration key
    payment_type_codeSet to banrisul, bradesco, bancodobrasil, or itau
    countrySet to br for Brazil.

    Customer data:​

    ParameterDescription
    nameCustomer name
    emailCustomer e-mail
    documentCustomer document
    addressCustomer address
    street_numberCustomer street number
    cityCustomer city
    stateCustomer state
    zipcodeCustomer zip code
    phone_numberCustomer phone number

    Charge parameters:​

    ParameterDescription
    merchant_payment_codeUnique merchant payment code
    currency_codeSupported values: BRL and USD
    amount_totalTotal amount to be charged
    due_dateExpiration date: dd/mm/yyyy (optional)

    The due date Can be more than 3 days only when payment currency is BRL (Brazilian Real). The due date is based on the local time of the country that the payment was generated.

  3. Sample request

    Use the following example to initiate a request.

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_ebanx_integration_key",
        "operation": "request",
        "payment": {
          "name": "José Silva",
          "email": "jose@example.com",
          "document": "853.513.468-93",
          "address": "Rua E",
          "street_number": "1040",
          "city": "Maracanaú",
          "state": "CE",
          "zipcode": "61919-230",
          "country": "BR",
          "phone_number": "8522847035",
          "payment_type_code": "itau",
          "merchant_payment_code": "0x0W2ver6D04-T03",
          "due_date": "08/12/2024", // Optional
          "currency_code": "BRL", // BRL or USD
          "amount_total": 100
        }
      }'

  4. Sample response

    A successful request returns a response like the example below, with the bank redirect link provided in the payment.redirect_url parameter.

    {
    "redirect_url": "https:\/\/sandbox.ebanxpay.com\/ws\/directtefredirect\/?hash=67536ed495cefb0683e26cd0492a06280d68cf7be9a97a00",
    "payment": {
      "hash": "67536ed495cefb0683e26cd0492a06280d68cf7be9a97a00",
      "country": "br",
      "merchant_payment_code": "0x0W2ver6D04-T03",
      "order_number": null,
      "status": "PE",
      "status_date": null,
      "open_date": "2024-12-06 21:38:28",
      "confirm_date": null,
      "transfer_date": null,
      "amount_br": "100.38",
      "amount_ext": "100.00",
      "amount_iof": "0.38",
      "currency_rate": "1.0000",
      "currency_ext": "BRL",
      "due_date": "2024-12-08",
      "instalments": "1",
      "payment_type_code": "itau",
      "redirect_url": "https:\/\/sandbox.ebanxpay.com\/ws\/directtefredirect\/?hash=67536ed495cefb0683e26cd0492a06280d68cf7be9a97a00",
      "pre_approved": false,
      "capture_available": null
    },
      "status": "SUCCESS"
    }

    At this stage, the payment will appear as pending (PE) in your
    EBANX Dashboardchevron_right

  5. Redirect customer to the returned URL

    Redirect your customer to the URL provided in the redirect_url parameter. Once redirected, they will enter their online banking environment, where all purchase details are pre-filled, allowing them to complete their payment securely and conveniently.

    Testing online debits in a sandbox environment​

    In our Sandbox environment, we provide an Online-Banking simulation interface to test bank transfer payments. This mock interface allows you to simulate different payment outcomes:

    • Simulate Authorized = YES: Confirms the payment as successful.
    • Simulate Authorized = NO: Denies the payment.
    • Leave Pending: Leaves the payment in a pending state.

    This simulation mimics the real production flow, where users are redirected to their Internet Banking to complete transactions, enabling you to thoroughly test authorized and unauthorized payments.

    Bank Transfer

  6. Monitor payment for status changes

    Notifications

    Status

    • After receiving a notification, retrieve the payment status.

    • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).

  7. Congratulations!

    You have succesfully integrated Online Debit.

    For more information, refer to the
    Direct API reference guidechevron_right

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: