Skip to main content

Sub Accounts

The Sub Accounts feature at EBANX allows you to create and manage multiple sub-accounts under a single primary account, enabling better organization, tracking, and distribution of payments. It’s especially useful for businesses with different brands, branches, or services that need separate payment management.

Requirements​

How it works​

  • Sub accounts
    • Each sub-account can represent a different business unit, region, or service, making it easier to manage and segment transactions.
  • Assign payment routing
    • Payments can be routed directly to the respective sub-account based on specific criteria, such as country, payment method, or other custom rules.
    • This ensures that funds are correctly attributed to the appropriate sub-account, improving financial reporting and control.
  • Custom integration
    • Developers can integrate sub-accounts through the EBANX API by specifying the sub_account_key parameter in payment requests.
    • This parameter ensures that transactions are processed under the intended sub-account, enabling more granular payment tracking.
  • Independent reconciliation
    • Each sub-account has its own set of reports, enabling independent reconciliation, analysis, and management.
    • Merchants can generate specific reports for each sub-account, making it easier to track individual performance, sales, and payment statuses.
  • Settlement and payouts
    • Settlements and payouts can be managed individually for each sub-account.
    • Merchants can receive payouts directly from each sub-account, making fund distribution clearer and more organized.
  • Role-Based access
    • Role-based access control can be applied to sub-accounts, allowing specific users to manage and view only the sub-accounts they are responsible for.
    • This ensures secure access and better control over payment management.

Benefits​

  • Improved organization - Separate transactions, funds, and reports for different business units.
  • Better reporting - Independent reporting allows for clear visibility into each unit’s performance.
  • Custom routing - Direct payments to the right sub-account based on custom rules.
  • Simplified settlements - Easier fund management and distribution based on sub-account activities.

Instructions​

Follow the steps below.

  1. Provide the sub account information
    ​

    When using sub accounts, you need to provide a few extra fields:

    ParameterDescription
    payment.sub_accountAn object containing the sub account’s name. Required for payments where the sub-account feature is being used.
    payment.sub_account.nameName of the sub-account that will be showed in the cash payment and e-mails.
    payment.sub_account.image_urlURL of the logo of the sub-account. PS: It MUST be an HTTPS URL. Otherwise, you will receive an error message.

  2. Send payment request with sub account
    ​

    This feature is available in both Direct API and Payment Page.

    Request using Direct API​

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_ebanx_integration_key",
        "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": "boleto",
          "merchant_payment_code": "17c0c4ef790",
          "currency_code": "BRL",
          "amount_total": 100,
          "sub_account": {
            "name": "Loja de Teste",
            "image_url": "https://www.colourbox.com/preview/9155263-store-front.jpg"
          }
        }
      }'

    Request using payment page​

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/request' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_ebanx_integration_key",
        "name": "José Silva",
        "email": "josesilva@example.com",
        "country": "br",
        "payment_type_code": "boleto",
        "merchant_payment_code": "d59cb7166e7",
        "currency_code": "BRL",
        "amount": 100,
        "sub_acc_name": "Merchant Test Name",
        "sub_acc_image_url": "https://www.colourbox.com/preview/9155263-store-front.jpg"
      }'

  3. Congratulations!
    ​

    You have succesfully integrated the Sub Account feature.

Still need help?

Help Image

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