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.

Create a sub account

Use the Sub Account Onboarding API to programmatically create sub-accounts under your primary merchant account.

1. Select your environment

   Environment	Method	URL
   Sandbox	POST	https://sandbox.ebanxpay.com/ws/subaccount/create
   Production	POST	https://api.ebanxpay.com/ws/subaccount/create

2. Define your parameters

   The following parameters are required to create a sub-account:

   Parameter	Format	Required	Description
   integration_key	string	Yes	Your EBANX integration key.
   legal_name	string	Yes	The legal name of the sub-account entity.
   trade_name	string	No	The trade or brand name of the sub-account.
   website	string	No	The sub-account website URL (e.g. https://www.example.com).
   sub_account_code	string	Yes	A unique identifier for the sub-account (max 50 characters, only letters, digits, -, _).
   country	string	Yes	Country code in ISO 3166-1 alpha-2 format (e.g. br, ar, co, cn, hk, sg, us).
   documents	array	Yes	Array of document objects (see document parameters below).
   shareholders	array	Yes	Array of shareholder objects (see shareholder parameters below).

   Document parameters

   Parameter	Format	Required	Accepted values	Description
   type	string	Yes	NATIONAL_IDENTIFIER	The type of document.
   subtype	string	Yes	UNKNOWN	The subtype of document.
   value	string	Yes	-	The document number (e.g. tax ID).

   Shareholder parameters

   Parameter	Format	Required	Description
   name	string	Yes	The shareholder's full name.
   documents	array	Yes	Array of document objects (same structure as document parameters).

3. Send the request

   Use the following example to create a sub-account.

   curl -X POST \
     --location 'https://sandbox.ebanxpay.com/ws/subaccount/create' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "legal_name": "legal name",
       "trade_name": "trade name",
       "website": "https://www.example.com",
       "sub_account_code": "your-sub-account-identifier",
       "country": "br",
       "documents": [
         {
           "type": "NATIONAL_IDENTIFIER",
           "subtype": "UNKNOWN",
           "value": "00000009000125"
         }
       ],
       "shareholders": [
         {
           "name": "Shareholder Name",
           "documents": [
             {
               "type": "NATIONAL_IDENTIFIER",
               "subtype": "UNKNOWN",
               "value": "29388566521"
             }
           ]
         }
       ]
     }'

4. Handle the response

   A successful request returns HTTP status 201 with the created sub-account details.

   {
     "status": "success",
     "sub_account": {
       "country": "br",
       "name": "Your Sub account name",
       "legal_name": "legal name",
       "trade_name": "trade name",
       "website": "https://www.example.com",
       "enabled": "ENABLED",
       "sub_account_code": "your-sub-account-identifier",
       "shareholders": [
         {
           "country": "br",
           "name": "Shareholder Name",
           "document_number": "29388566521",
           "document_type": "UNKNOWN"
         }
       ]
     }
   }

Disable a sub account

You can disable an existing sub-account by calling the disable endpoint. Once disabled, the sub-account status changes to INACTIVE.

1. Select your environment

   Environment	Method	URL
   Sandbox	POST	https://sandbox-local-latam.ebanxpay.com/ws/recipient/disable/
   Production	POST	https://api-local-latam.ebanxpay.com/ws/recipient/disable/

2. Send the request

   Provide your integration key and the sub-account code to disable.

   curl -X POST \
     --location 'https://sandbox-local-latam.ebanxpay.com/ws/recipient/disable/' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "code": "your-sub-account-code"
     }'

3. Handle the response

   A successful request returns the recipient details with the status set to INACTIVE.

   {
     "status": "success",
     "recipient": {
       "recipient_code": "your-sub-account-code",
       "name": "SUB ACCOUNT NAME",
       "email": null,
       "phone": "",
       "status": "INACTIVE",
       "country": "br",
       "type": "business",
       "document": "00000000000",
       "birth_date": null,
       "bank_account": {
         "bank_account_code": "00000000",
         "bank_account_verification_code": "9",
         "bank_code": "000",
         "bank_branch_code": "0000",
         "bank_branch_verification_code": "1",
         "bank_account_type": "checking",
         "bank_account_id": "qwerw2342424"
       },
       "activated_date": "2025-11-19 03:08:50",
       "shareholders": [
         {
           "name": "NAME",
           "document": "00000000",
           "document_type": "cpf",
           "birth_date": null,
           "email": null,
           "phone": null,
           "ownership_percent": null,
           "country": "br"
         }
       ]
     }
   }

   Failure scenarios

   Code	Description
   RCP-41	Recipient not found.
   RCP-42	Consistency check failed. The operation to disable the recipient could not complete.
   RCP-43	Recipient is already disabled (INACTIVE).

Use sub accounts in payments

Once a sub-account is created, you can route payments to it by including the sub-account information in your payment requests.

1. Provide the sub account information

   When using sub accounts in payments, include the following 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 displayed in the cash payment voucher and e-mails.
   payment.sub_account.image_url	URL of the logo of the sub-account. 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": "John Doe",
         "email": "john.doe@example.com",
         "document": "{{tax_id}}",
         "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": "John Doe",
       "email": "john.doe@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 successfully integrated the Sub Account feature.

Error codes

The following error codes may be returned when creating a sub-account.

Code	Message
MSA-01	Empty integration_key value.
MSA-02	Parameter integration_key is invalid.
MSA-03	Merchant is not enabled.
MSA-04	The sub account code is already in use. Choose another code identifier.
MSA-05	The sub_account_code parameter cannot be empty.
MSA-06	The sub account code must be less than 50 characters.
MSA-07	Sub account code has invalid characters. Only letters, digits, - and _ are accepted.
MSA-08	The legal_name parameter cannot be empty.
MSA-09	If informed, the trade_name parameter cannot be empty.
MSA-10	The country parameter cannot be empty.
MSA-11	The country parameter is invalid.
MSA-12	Parameter shareholder cannot be empty.
MSA-13	Only one shareholder can be informed.
MSA-14	Sub Accounts process not allowed.
MSA-15	National identifier document is required.
MSA-16	The value field is required for the national identifier document.
MSA-17	Invalid value for the national identifier document.
MSA-18	Shareholder national identifier fields are required.
MSA-19	The value field is required for the shareholder national identifier document.
MSA-20	Invalid value for the shareholder national identifier document.
MSA-21	The type field is required for the shareholder national identifier document.
MSA-22	The subtype field is required for the shareholder national identifier document.
MSA-23	The shareholder name field is required.
MSA-24	The website parameter cannot be empty (only when the website field is provided but empty).

Error response example

{
  "status": "error",
  "message": "Parameter integration_key is invalid",
  "status_code": "MSA-02"
}

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.