Sub-accounts are the backbone of Split Payments. They define who receives a portion of a transaction and where that money should go. Each sub-account can have a percentage of the transaction and a settlement destination. With sub-accounts, you can:
  • Automate revenue sharing
  • Maintain a transparent audit trail for settlements
  • Track balances for each partner before actual payout
The minimum split amount per transaction is 1 GMD.
Before a sub-account can receive a payout, it must have accumulated at least 10 GMD in its balance. This ensures efficient settlement and reduces transaction costs.

​
Create a Sub-Account

Creates a new recipient account that can be used in split payments. 
const subAccount = await modempay.subAccounts.create({
  business_name: "Hail-Ma",
  percentage: 10,             // Revenue share (integer %)
  settlement_code: "afrimoney", // Settlement provider (wave or afrimoney)
  account_number: 7012345,      // Account to receive funds
});
Notes & Best Practices:
  • Ensure the percentage is appropriate; total splits should not exceed 100%.
  • The settlement_code must match an active payment provider integrated with Modem Pay.
  • Keep the account_number accurate to avoid failed settlements.
  • You can create multiple sub-accounts and reuse them across payment intents.

​
Retrieve a Sub-Account

Fetch details for a specific sub-account using its unique ID. Useful for confirming configuration or checking balances. 
const subAccount = await modempay.subAccounts.retrieve("5bfcc08....810b");
console.log(subAccount);

​
List All Sub-Accounts

Get a list of all sub-accounts associated with your business. This is helpful for dashboards or automated scripts. 
const allSubAccounts = await modempay.subAccounts.list();
console.log(allSubAccounts);
Notes:
  • Can be filtered by search term.
  • Supports pagination using offset and limit parameters
  • Returns pagination info if there are many sub-accounts.

​
Update a Sub-Account

Modify a sub-account’s properties like percentage share or settlement destination. 
const updatedSubAccount = await modempay.subAccounts.update("5bfcc08....810b", {
  percentage: 15,         // Update revenue share
  account_number: 7016789, // Update account number
});
console.log(updatedSubAccount);
Notes:
  • You can update the fields: active, percentage, account_number, and settlement_code.
  • Updates take effect on future transactions, not on already processed ones.
  • Avoid reducing percentages that would make total splits exceed 100%.

​
Additional Tips

  • Balances: Each sub-account maintains an internal balance until settlement occurs.
  • Audit: Always store sub-account IDs and percentages used per payment intent to keep your records consistent.
  • Multiple Sub-Accounts: Currently, a payment intent supports one sub-account. Future updates will allow multiple sub-accounts per transaction.