Skip to main content

​
API Integration

The submerchant feature uses the HUB2 API. The available endpoints are listed in the following documentation:

API Submerchant

​
Authentication

Your integration uses the same HUB2 API keys for authentication. The key must have the following permissions:
  • Api.submerchant_create
  • Api.submerchant_list
  • Api.submerchant_update
To process payments or transfers for a submerchant, the same key also needs the payment and transfer permissions you already use (for example Api.payment_intent_create, Api.transfer_create).

Permissions configuration

​
API Endpoints

​
Submerchants

  • POST /submerchants: create a submerchant. name and description are required; address, zipcode, city, phoneNumber and legalInfo are optional. Example:
  • PATCH /submerchants/{submerchantId}: update a submerchant
  • GET /submerchants: list your submerchants
Rate limits: GET /submerchants is limited to 1 request per 5 seconds. POST /submerchants and PATCH /submerchants/{submerchantId} are limited to 1 request per second. Beyond these limits, the API responds with HTTP 429 Too Many Requests.
The response contains the submerchant id. Keep it to process transactions on behalf of the submerchant.

​
Transactions for a submerchant

To create a payment or a transfer for a submerchant, call the usual payment or transfer endpoints with your own API key and set the MerchantId header to the submerchant id. The transaction is booked for the submerchant and its subMerchantId field is filled in. A parent merchant that calls the transaction endpoints with its own MerchantId receives a 403 error with the code group_owner_transaction_forbidden. Always set the MerchantId header to the submerchant id.

​
Webhooks

Payments and transfers made for a submerchant use the standard payment and transfer webhooks. If you have already configured them, no additional step is required. Otherwise, see:

Webhooks Integration Guide