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

• API credentials - Make sure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Sub-accounts enabled - Contact the EBANX integration team at sales.engineering@ebanx.com to enable it.

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:

   Parameter	Description
   payment.sub_account	An object containing the sub account’s name. Required for payments where the sub-account feature is being used.
   payment.sub_account.name	Name of the sub-account that will be showed in the cash payment and e-mails.
   payment.sub_account.image_url	URL 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",
       "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": "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.ebanxpay.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?

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.