Skip to main content

Initiate Mobile Money Inflow

​
POST /v1/global-collection/inflow/initiate

Trigger a mobile money collection from your customer. This endpoint initiates an inflow request through the supported mobile money flow, prompting the customer to complete the payment on their end. 
curl --request POST \
  --url https://api.nomba.com/v1/global-collection/inflow/initiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountId>' \
  --data '{
    "phoneNumber": "0980802xxx",
    "callbackUrl": "https://your-server.com/webhook/collection",
    "amount": 10,
    "currency": "CDF",
    "topupVendor": "AIRTEL",
    "idempotencyKey": "your-unique-key-here"
  }'

​
Idempotency

This endpoint supports idempotent requests. You can pass a client-generated idempotencyKey in the request body to safely retry a request without risk of duplicate charges. If you omit the key, the server generates a UUID automatically and returns it in the response. Store the idempotencyKey from the response and include it on any retry for the same operation. If two requests carrying the same idempotencyKey arrive concurrently, the second request receives HTTP 409 with the message “Request with this idempotency key is currently being processed; please retry.”

​
Request body

​
phoneNumber
string
required
The customer’s mobile money phone number.
​
callbackUrl
string
required
The URL Nomba will POST to when the transaction status changes. Must be publicly accessible.
​
amount
number
required
The amount to collect from the customer.
​
currency
string
required
ISO 4217 currency code for the collection (e.g., CDF).
​
topupVendor
string
required
The mobile money network provider (e.g., AIRTEL, MPESA).
​
idempotencyKey
string
A client-generated key used to safely retry the request without risk of duplicate charges. If not provided, the server generates one automatically.

​
Response body

​
transactionReference
string
required
Unique reference for this collection. Use this with Fetch Transaction to check the status.
​
status
string
required
Initial status of the inflow request (e.g., PENDING).
​
message
string
A message describing the outcome.
​
idempotencyKey
string
The idempotency key used for this request — either the value you provided or a server-generated UUID. Store this and pass it on retry.