​
Overview

A business registered on Nomba has the flexibility to establish multiple subaccounts, as detailed in this documentation. This feature enables you to seamlessly collect payments through Nomba Checkout for each individual subaccount. For instance, if you own and operate multiple stores, you can efficiently manage and collect online payments for each store independently, ensuring a streamlined and organized financial process.

​
Create a subaccount

Subaccounts in Nomba serve as additional entities that enhance the capabilities of your primary account. A business or primary account holder can establish multiple subaccounts within Nomba. For an in-depth understanding of what subaccounts entail, refer to the explanation provided here. Additionally, to learn about the requirements for creating a subaccount, visit this documentation.

Sample request

curl --request POST \
  --url https://api.nomba.com/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '{
  "accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
  "phoneNumber": "2348188667581",
  "email": "[email protected]",
  "bvn": "12234412345",
  "pin": "1234",
  "accountName": "Daniel Scorsese",
  "currency": "NGN",
  "callbackUrl": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7",
  "expiryDate": "2023-12-06T15:46:43.000Z"
}'

Sample response

{
  "code": "00",
  "description": "Success",
  "data": {
    "createdAt": "2023-09-04T07:09:06.900Z",
    "accountId": "fc81b80e-e607-4b86-8591-840925191733",
    "accountHolderId": "01a10aeb-d989-460a-bbde-9842f2b4320f",
    "accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
    "phoneNumber": "2348188667581",
    "email": "[email protected]",
    "bvn": "12234412345",
    "status": "ACTIVE",
    "type": "virtual",
    "accountName": "Daniel Scorsese",
    "currency": "NGN",
    "callbackUrl": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7",
    "expiryDate": "2023-12-06T15:46:43.000Z"
  }
}

​
Fetch accounts linked to your business

Refer to this documentation to understand how to retrieve all accounts associated with your business. Any of the listed accounts can serve as a source for your online payments. By specifying the accountId of a chosen account when creating a checkout order, the customer’s payment will be directed to your subaccount’s purse rather than your primary account’s purse.

Sample request

curl --request GET \
  --url https://api.nomba.com/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'accountId: <accountid>'

Sample response

{
  "results": [
    {
      "accountId": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d",
      "accountHolderId": "412316",
      "accountRef": "ACT_AMF0YN8UWH8CR8JZ",
      "phoneNumber": "2348188667580",
      "email": "[email protected]",
      "bvn": "12234412345",
      "type": "physical",
      "accountName": "Testing Testing123",
      "banks": [
        {
          "bankAccountNumber": "0554772814",
          "bankName": "Wema Bank",
          "bankAccountName": "M.A Animashaun"
        }
      ],
      "address": "4, Alagomeji, Yaba, Lagos",
      "status": "active",
      "currency": "NGN",
      "description": "Meat kebab spot",
      "createdAt": "2022-07-08T14:33:00Z",
      "updatedAt": "2022-07-08T14:33:00Z"
    }
  ],
  "cursor": "xchbaVFsjdsbaADddd"
}

​
Generate a checkout order for a subaccount

As explained in the preceding section, you can pass the accountId of any of your subaccounts into the checkout order creation flow as detailed in this documentation.

Sample request

curl --request POST \
  --url https://api.nomba.com/v1/checkout/order \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '{
  "order": {
      "orderReference": "testingref195",
      "callbackUrl": "https://www.nomba.com",
      "customerEmail": "[email protected]",
      "amount": 50,
      "currency": "NGN",
      "customerId": "identify123",
	  "accountId": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d"
  }
}'

Sample response

{
    "code": "00",
    "description": "checkout order created successful",
    "data": {
        "success": true,
        "message": "Success",
        "checkoutLink": "https://checkout.nomba.com/pay/testingref195",
        "orderReference": "testingref195"
    }
}

​
Fetch transactions for a subaccount

Explore the documentation to understand the process of verifying online payment transactions. Sample request and response snippets are provided below for reference.

Sample request

curl --request POST \
  --url https://api.nomba.com/v1/transactions/accounts/{accountId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '{
  "transactionRef": "POS-WITHDRAW-DFC05-693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea",
  "status": "SUCCESS",
  "source": "pos",
  "type": "withdrawal",
  "terminalId": "2KUD4AKB",
  "rrn": "230908202632",
  "merchantTxRef": "c90d-4b25-ad0f"
}'

Sample response

{
  "code": "00",
  "description": "Success",
  "data": {
    "results": [
      {
        "id": "POS-WITHDRAW-DFC05-693cd007-cd1e-4ea6-8b79-5f5c4d7a83ea",
        "status": "PAYMENT_FAILED",
        "amount": 4000,
        "fixedCharge": 123,
        "source": "pos",
        "type": "withdrawal",
        "gatewayMessage": "Insufficient funds",
        "customerBillerId": "539983 **** **** 5118",
        "timeCreated": "2023-09-08T19:26:34.657000Z",
        "posTid": "2KUD4AKB",
        "terminalId": "2KUD4AKB",
        "providerTerminalId": "2KUD4AKB",
        "rrn": "230908202632",
        "posSerialNumber": "91230309116826",
        "posTerminalLabel": "KEB MUSA ABUBAKAR",
        "stan": "556734",
        "paymentVendorReference": "2KUD4AKB230908202632",
        "userId": "dfc05ca1-4e75-41dd-8e41-2d362d565893",
        "posRrn": "230908202632",
        "merchantTxRef": "c90d-4b25-ad0f"
      }
    ],
    "cursor": "xchbaVFsjdsbaADddd"
  }
}
Processing recurring paymentsPagination