Sub-Accounts

A sub-account is a partner who receives part of your payments. You set two things on it:

• Who gets paid: a mobile money account (settlement_code + account_number)
• How much: a percentage of each payment it is attached to

When a payment with a sub-account completes, Modem Pay moves that percentage into the sub-account’s balance and keeps the rest in yours. No manual transfers.

Need to pay several partners from one payment? Put them in a Sub-Account Group.

How it works

1. Create a sub-account

   Give it a name, a percentage and where its money should go. You get back an id.

2. Attach it to a payment

   Pass the id as sub_account when you create a payment intent.

3. Customer pays

   The sub-account’s share is added to its balance. The rest goes to your balance.

4. Sub-account is settled

   Once its balance reaches 10 GMD, it can be paid out to its account.

How the share is calculated

The percentage is applied to what you receive from the payment, after Modem Pay’s fee if your business pays the fee. If the customer pays the fee, it is applied to the full amount.

Shares are rounded to the nearest whole GMD, and every share is at least 1 GMD.

Payment	Fee paid by	Modem Pay fee	You receive	Sub-account (10%)	Your balance
1,000 GMD	Business	20 GMD	980 GMD	98 GMD	882 GMD
1,000 GMD	Customer	20 GMD (added to the customer’s total)	1,000 GMD	100 GMD	900 GMD

Fees shown are examples. Your actual fee depends on your pricing.

---

Create a sub-account

POST /v1/sub-accounts

Field	Type	Required	Description
business_name	string	Yes	Name of the partner. Shown on your dashboard and reports.
percentage	number	Yes	Share of each payment, greater than 0 and at most 100.
settlement_code	string	Yes	Where the money is settled, e.g. wave or afrimoney.
account_number	string	Yes	The partner’s account number on that provider.

nodejs

const subAccount = await modempay.subAccounts.create({
  business_name: "Hail-Ma",
  percentage: 10,
  settlement_code: "afrimoney",
  account_number: "7012345",
});

console.log(subAccount.id); // keep this, you'll attach it to payments

Double-check account_number. A wrong number means the sub-account’s payout fails or goes to the wrong person.

Retrieve a sub-account

GET /v1/sub-accounts/:id

Returns the sub-account, including its current balance.

nodejs

const subAccount = await modempay.subAccounts.retrieve("5bfcc08....810b");
console.log(subAccount);

List sub-accounts

GET /v1/sub-accounts

Query parameter	Default	Description
term	—	Search by business_name.
limit	15	How many to return.
offset	0	How many to skip, for paging.

nodejs

const { data, meta } = await modempay.subAccounts.list();
console.log(meta.total);

Response:

{
  "data": [
    {
      "id": "5bfcc08....810b",
      "business_name": "Hail-Ma",
      "percentage": 10,
      "balance": 98,
      "active": true
    }
  ],
  "meta": { "total": 1 }
}

Update a sub-account

PUT /v1/sub-accounts/:id

Send only the fields you want to change: percentage, account_number, settlement_code or active.

nodejs

const updated = await modempay.subAccounts.update("5bfcc08....810b", {
  percentage: 15,
  account_number: "7016789",
});

• Changes apply to future payments only. Completed payments keep the split they were made with.
• Set active to false to pause a sub-account. New payment intents that use it are rejected.
• Changing a sub-account’s percentage does not change its share inside a group. Groups store their own percentages.

Delete a sub-account

DELETE /v1/sub-accounts/:id

cURL

curl -X DELETE https://api.modempay.com/v1/sub-accounts/5bfcc08....810b \
 -H "Authorization:Bearer sk_test_..."

A sub-account can only be deleted when its balance is 0. Otherwise you get a 400. To stop using one that still has money, set active to false instead.

---

Rules at a glance

Rule	Value
Percentage	Greater than 0, at most 100
Smallest share per payment	1 GMD
Rounding	Nearest whole GMD
Balance needed before payout	10 GMD
Sub-accounts per payment	1 (use a group for more)
Test vs live	Test-mode sub-accounts only work with test keys, and live with live