Skip to main content

​
Who is this feature for?

This feature is for platforms, marketplaces, PSPs, and merchants that need to onboard and manage multiple sub-merchants (sub-merchant) under a single Niobi account. Typical users:
  • Marketplaces that settle funds to individual vendors
  • Payment service providers integrating multiple merchants
  • Enterprises managing separate merchant accounts for reporting or compliance

​
Adding a sub-merchant

To add a sub-merchant via the Niobi portal:
  1. Log in to your Niobi dashboard.
  2. Navigate to Workspace > Sub-merchant. Sub merchant portal
  3. Click “Add New Sub-merchant”.
  4. Complete the form with the sub-merchant’s business and contact details:
  • Sub-merchant name
  • Business activity and website
  • Incoorporation and transaction country Sub merchant form
  1. Submit the form.
After submission the sub-merchant will be created in Pending status and will enter the review workflow (see Approval and review process).

​
Approval and review process

All newly created sub-merchants enter a review workflow before they can process live transactions.
  • Status: Pending — The sub-merchant has been created and awaits review by the compliance team.
  • Status: Approved — The sub-merchant passed review and can process transactions.
  • Status: Suspended — The sub-merchant has been blocked due to compliance issues, suspicious activity, or policy violations. Suspended sub-merchants cannot process live transactions. Contact support@niobi.co to understand the reason and appeal if applicable.
Review steps:
  1. Submit required business and KYC documents via the Niobi portal.
  2. Niobi performs identity and risk checks.
  3. Manual or automated approval is applied; the account moves to Approved or Suspended.

​
How to get and use the sub-merchant ID in API calls

Where to find the ID:
  • After creating a sub-merchant in the Niobi portal, the dashboard lists the sub_merchant_id in the Sub-merchant list. Sub merchant list
Include the sub_merchant_id in your payment payload to associate transactions. Sample Deposit request: 
{
  "client_id": "<REDACTED_CLIENT_ID>",
  "params": {
    "amount": "10",
    "callback_url": "https://webhook.site/<REDACTED>",
    "country_id": "1",
    "currency": "KES",
    "mobile": "2547xxxxxxx",
    "name": "Test Customer",
    "payment_method_type": "send money",
    "sub_merchant_id": "4resa-xxxx-xxxx-xxxx-vb67",
    "third_party_reference_1": "REF-123"
  },
  "salt": "<REDACTED>",
  "sender": "Sandbox",
  "timestamp": 1620000000,
  "signature": "<REDACTED_SIGNATURE>"
}
VariableDescription
client_idYour integration client_id provided by Niobi
sub_merchant_idThe unique identifier for the sub-merchant
callback_urlURL to receive asynchronous notifications
amountTransaction amount
currencyCurrency code (e.g., KES)
timestampUnix timestamp used when creating the signature
signatureHMAC signature for request validation

​
How to test?

  1. Create a test sub-merchant in the Niobi portal under sandbox mode.
  2. Retrieve the sub_merchant_id from the Sub-merchant list.
  3. Make a sandbox deposit or payout request including sub_merchant_id (use the sample request above).
  4. Verify the transaction shows the sub-merchant in the dashboard and webhooks.

​
Sub-merchant State Changes

  • Pending: Wait for approval. Do not send live transactions.
  • Approved: Proceed with live transactions and reporting.
  • Suspended: The sub-merchant is blocked. No live transactions can be processed. Contact support@niobi.co to understand the reason and request reinstatement.

​
Support

If you need assistance with sub-merchant management, contact our support team at support@niobi.co.