Disbursement Channel API

Disbursement Channel API

Author: Josh — Lead Backend Team
Last Updated: 2026-03-06
Version: v1.0

Base URL: https://api.nextgate.co.tz/api/v1

Short Description: The Disbursement Channel API manages theManages withdrawal destinations for NextGate users. A channel representsis a verified mobile money account or bank account to which a user can withdraw their wallet balance. Channels require OTP verification to add and have a cooling period before first use.

HintsKey notes:

• Adding a channel is a two-three-step flow:flow: initiate-/lookup → /add (sends OTP) then→ confirm-/add/confirm
• The /lookup step returns a signed confirmationToken required by /add (verifies— OTP)
expires
• Newlyin added10 channels have a cooling period (default 24 hours) before they can be used for withdrawalsminutes
• Selcom name lookup is performed beforeat OTPboth is/lookup sentand /add — theverified twice server-side
• The first channel on an account holderactivates nameimmediately is— verified24-hour automaticallycooling applies to all subsequent channels
• Deleting a channel also requires OTP confirmation — two-stepstep: flowDELETE same/{channelId} as→ addingDELETE /{channelId}/confirm
• Deleted channels cannot be used for new withdrawals — in-flight disbursements snapshot channel data at initiation time and are unaffected

Security & Client Guidelines

Authentication

All endpoints in this API are protected. The client must includerequire a valid JWT Bearer token in every request header:token:

Authorization: Bearer <your_token>

The token is obtained from the NextGate authentication API after login. When a request returnsOn 401 UNAUTHORIZED, the client must silently refresh the token and retry the original request once. If the refresh also fails, redirect the user to the login screen.login.

Never store the JWT token in alocalStorage place accessible to third-party scripts. On mobile,— use secure device storage.storage Onon web, prefer memorymobile, or HttpOnly cookies overon localStorage.web.

OTP Token Handling

TheBoth OTPthe flow is two-step for both addingadd and deletingdelete aflows channel.are two-step. The first step (initiate-add or initiate delete) returns an otpToken. string.Store This token must be storedthis in memory and passedpass it to the secondconfirm step (confirm-add or confirm delete) along with the OTP code the user receives via SMS.

The otpToken is not a security credential on its own — it is a session reference that ties theSMS OTP codecode. to the specific channel action. However, treat it with care: doDo not log it,it door not storepersist it beyond the duration of the OTP confirmation flow.

The OTP code itself expires after a short window (typically ~5 minutes).minutes. If the user takesis too long to enter the code,slow, the confirm step will returnreturns an error.error In— thisprompt case,them to restart the client should prompt the user to restart theentire flow from initiate-addthe orbeginning. initiateThe deleteserver —must doclean not allowup the userprevious topending requestchannel record before a new OTPone without starting over, as the previous channel record mustcan be cleaned up server-side.created.

If the user enters the wrong OTP codeis multipleentered too many times, the OTP will beis locked after the maximum attempts are exceeded. The confirm endpoint will return an OTP locked error. In this caseand the flow is terminatedterminated. —The the clientuser must start over from the beginning.over.

Name Lookup Beforeand AddConfirmation Token

The lookup step is separate from the initiate-add step intentionally. Its purpose is to let the user see and confirm the account holder name before committing to adding the channel. The client must always call /lookup first,step displayreturns a signed confirmationToken that encodes the returneddestination, channel type, and account ID. It is valid for 10 minutes.

The client must pass this token to /add. The server rejects the request if the token is missing, expired, or does not match the destination and channel type in the request body.

Always display accountHolderName prominently to the user,user and require explicit confirmation before proceeding tocalling /initiate-add.

This protects the userusers from accidentally adding a wrong destination by mistake — for example a typo in the phone number that happens to belong to someone else. The name displayed is fetched directly from Selcom's registry and reflects the actual registered owner of that number or account.destination.

Cooling Period UX

After aOTP channel is successfully added, it is not immediately usable for withdrawals. The activatesAt field in the confirm response tells you exactly when the cooling period ends. Theconfirmation, isUsable field will beis false until thatactivatesAt. time.

The client should communicate this clearly to the user — do not simply show the channel as active and let them discover it is not usable when they try to withdraw. A good UX shows a countdown orShow a message likelike:

"This channel will be ready for withdrawals on {activatesAt date}".

When

Visually distinguish usable channels from those still in the cooling period.period when listing.

Exception: The first channel added to an account activates immediately (isUsable: true, activatesAt set to now).

Deleting a Channel

Deleting a channelDeletion is irreversibleirreversible. and also requires OTP confirmation. The client should show the userShow a clear confirmation dialog before initiating the delete flow, explaining that the channel will be permanently removed.flow.

If athe userdeleted haschannel anywas pendingthe primary channel, the server automatically promotes another active channel as primary.

Pending disbursements that reference a deleted channel they are trying to delete, those disbursements are not affected — the disbursement entity holds a snapshot of the channel data atfrom theinitiation time of initiation. The delete only prevents future withdrawals to that destination.time.

Network Error Handling

Standard Response Format

Success Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2026-03-06T10:30:45",
  "data": {}
}

Error Response

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2026-03-06T10:30:45",
  "data": "Error description"
}

Flow Diagram

ADD CHANNEL FLOW
----------------
User
 |
 |--- POST /channel/disbursement/channels/lookup ------------> Selcom Name Lookup
 API
 |       ({ channelType, destination)destination, bankCode? }          |
 |<-- { accountHolderNameaccountHolderName, }destinationDisplay,    Returns verified name
 |       channelType, confirmationToken }
 |                                            <-- store confirmationToken (expires 10 min)
 |   [User reviews name, confirms]
 |
 |--- POST /channel/initiate-disbursement/channels/add ----------> Validate channelconfirmationToken
 |       ({ channelType, destination,               CheckRe-verify duplicatename with Selcom
 |         accountHolderName,bankCode?, bankCode)confirmationToken Name}           lookupCheck againfor |                                        Generate OTPduplicate
 |                                                  Save channel (PENDING_OTP)record
 |                                                  Generate + send OTP
 |<-- { otpToken }
 Send OTP to verified phone
 |
 |--- POST /channel/confirm-adddisbursement/channels/add/confirm -------> Verify OTP
 |       (otpToken, otpCode)?otpToken=...&otpCode=...                 Activate channel (ACTIVE)
 |<-- { channelId, isUsable, activatesAt, ... }    Set (cooling period24h, (24h)except first channel)
 |
 |   [Cooling period: 24 hours]
 |   [Channel becomes usable forafter withdrawals]activatesAt]
 |
 |--- GET /channel/my-disbursement/channels ---------------> List useractive channels
 |<-- [ { channelId, isUsable, activatesAt, ... } ]


DELETE CHANNEL FLOW
-------------------
User
 |
 |--- DELETE /channel/disbursement/channels/{id}/initiatechannelId} ---------> Generate + send OTP
 |<-- { otpToken }
 Send OTP to verified phone
 |
 |--- DELETE /channel/disbursement/channels/{id}channelId}/confirm ----> Verify OTP
 |       (otpToken, otpCode)?otpToken=...&otpCode=...                          Soft delete channel
 |<-- 200 OK                                                Reassign primary if needed

Channel Status Reference

A cleanup job runs nightly and soft-deletes any channel records whose OTP was never verified (i.e. the add flow was abandoned before confirm).

Endpoints

1. Lookup Account Name

Purpose: Verifies a destination account and returns the registered account holder name from Selcom.Selcom, Callalong with a signed confirmationToken required for the next step. Always call this before initiating /add so the user can confirm the name before proceeding..

Endpoint: POST /disbursement/channels/lookup

{
  "channelType": "MPESA",
  "destination": "255712345678",
  "bankCode": null
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Account found"verified successfully",
  "action_time": "2026-03-06T10:30:45",
  "data": {
    "accountHolderName": "JOHN DOE",
    "destination"destinationDisplay": "255712345678"2557****678",
    "channelType": "MPESA",
    "confirmationToken": "<signed-token>"
  }
}

{not "success":verify false,
  "httpStatus": "BAD_REQUEST",
  "message": "Name lookup failed.account. Please check the details and try again.",

{
  "channelType": "MPESA",
  "destination": "255712345678",
  "accountHolderName"bankCode": null,
  "confirmationToken": "JOHN<token DOE",from /lookup>"bankCode": null
}

{
  "channelType": "BANK",
  "destination": "0012345678901",
  "accountHolderName": "JOHN DOE",
  "bankCode": "CRDB",
  "confirmationToken": "<token from /lookup>"
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "OTP sent to your verified phone number",
  "action_time": "2026-03-06T10:30:45",
  "data": {
    "otpToken": "otp-token-uuid-here"
  }
}

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Bank code is required for BANK channels.",
  "action_time": "2026-03-06T10:30:45",
  "data": "Bank code is required for BANK channels."
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Withdrawal channelChannel added successfully",
  "action_time": "2026-03-06T10:30:45",
  "data": {
    "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "channelType": "MPESA",
    "destinationDisplay": "255712*2557****78"678",
    "accountHolderName": "JOHN DOE",
    "bankCode"bankName": null,
    "isPrimary": false,
    "status": "ACTIVE",
    "isUsable": false,
    "activatesAt": "2026-03-07T10:31:00",
    "createdAt": "2026-03-06T10:31:00"
  }
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Channels retrieved successfully",
  "action_time": "2026-03-06T10:30:45",
  "data": [
    {
      "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "channelType": "MPESA",
      "destinationDisplay": "255712*2557****78"678",
      "accountHolderName": "JOHN DOE",
      "bankCode"bankName": null,
      "isPrimary": true,
      "status": "ACTIVE",
      "isUsable": true,
      "activatesAt": "2026-03-05T10:31:00",
      "createdAt": "2026-03-04T10:31:00"
    },
    {
      "channelId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "channelType": "BANK",
      "destinationDisplay": "0012****789",
      "accountHolderName": "JOHN DOE",
      "bankCode"bankName": "CRDB"CRDB Bank",
      "isPrimary": false,
      "status": "ACTIVE",
      "isUsable": false,
      "activatesAt": "2026-03-07T08:00:00",
      "createdAt": "2026-03-06T08:00:00"
    }
  ]
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "OTP sent to your verified phone number",
  "action_time": "2026-03-06T10:30:45",
  "data": {
    "otpToken": "otp-token-uuid-here"
  }
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Withdrawal channelChannel deleted successfully",
  "action_time": "2026-03-06T10:30:45",
  "data": null
}