POST
/
collections
/
push
/
direct
/
initiate
cURL
curl -X POST "https://dev.api.onekhusa.com/sandbox/v1/collections/push/direct/initiate" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: en" \
  --header "X-Idempotency-Key: your-idempotency-key" \
  -d '{
    "merchantAccountNumber": 12345678,
    "connectorId": 550044,
    "payerAccountNumber": "0999000000",
    "sourceReferenceNumber": "OKPG90WOIJD98JKSJKH",
    "transactionDescription": "Groceries Order Payment",
    "transactionAmount": 100.00,
    "capturedBy": "john.doe@onekhusa.com"
  }'
{
  "merchantAccountNumber": 12345678,
  "sourceReferenceNumber": "OKPG90WOIJD98JKSJKH",
  "responseCode": "I100",
  "feeRuleCode": "CC",
  "transactionAmount": 100,
  "totalCharges": 2.5,
  "amountToPay": 102.5
}

ā€‹
Webhook Event Notifications

Because MoMo (Mobile Money) payment authorization relies on user PIN entry on their handset, final transaction outcomes are delivered asynchronously through OneKhusa webhooks. Register an HTTP POST endpoint to listen for the following three events:
  • pushpayment.success: Triggered when the customer enters their PIN and the payment successfully settles.Refer to the Push Payment Webhook for the event headers and JSON payload.
  • pushpayment.failed: Triggered if the customer cancels the prompt, enters an incorrect PIN, times out, or has insufficient funds etc.Refer to the Push Payment Webhook for the event headers and JSON payload.
  • pushpayment.reversed: Triggered if a previously successful payment is reversed by the MoMo operator (e.g., due to duplicate debit reconciliation).Refer to the Push Payment Webhook for the event headers and JSON payload.

ā€‹
Implementation Guidelines

  • Idempotency: Ensure sourceReferenceNumber is unique per payment request to prevent accidental duplicate prompts.
  • Synchronous vs Asynchronous handling: Treat the /collections/push/direct/initiate response as acknowledgment of prompt delivery only. Do not fulfill orders or grant service access until receiving a pushpayment.success webhook.
  • Webhook Verification: Verify incoming webhook signatures using the X-OneKhusa-Webhook-Signature header to ensure authenticity.
  • Simulate Payment Authorization: Once the payment is initiated in sandbox environment, login to OneKhusa merchant portal, navigate to Test Your Integration -> Simulate Push Payment page. Perform the actions expected from MoMo providers to hard-proof your integrations.

Authorizations

ā€‹
Authorization
string
header
required

Bearer authentication header of the form Bearer Token, Where accessToken is the access token used to authenticate the request.

Headers

ā€‹
Accept-Language
string
default:en

Preferred language for the response

ā€‹
X-Idempotency-Key
string

A unique key to ensure idempotent requests

Body

application/json
ā€‹
merchantAccountNumber
integer
required

Your unique OneKhusa merchant account number.

Example:

12345678

ā€‹
connectorId
integer
required

Identifier for the targeted Mobile Money connector/provider, for example TNM Mpamba or Airtel Money. Use the Get All Connectors endpoint to look up the connector identifier.

Example:

550044

ā€‹
payerAccountNumber
string
required

Mobile Money phone number of the payer (MSISDN).

Example:

"0999000000"

ā€‹
sourceReferenceNumber
string
required

Unique reference number generated by your merchant system. Keep it unique per payment request to prevent accidental duplicate prompts.

Required string length: 5 - 25
Example:

"OKPG90WOIJD98JKSJKH"

ā€‹
transactionDescription
string
required

Narrative or memo for the transaction shown to the customer.

Example:

"Groceries Order Payment"

ā€‹
transactionAmount
number<decimal>
required

Payment amount requested.

Example:

100

ā€‹
capturedBy
string<email>
required

User email initiating the API request.

Example:

"john.doe@onekhusa.com"

Response

200 - application/json

The request was validated and the USSD prompt was dispatched to the Mobile Money provider. This response does not confirm payment completion, use the push payment webhooks to receive the final transaction status.

ā€‹
merchantAccountNumber
integer
required

Associated merchant account number.

Example:

12345678

ā€‹
sourceReferenceNumber
string
required

The unique reference number passed in the request.

Example:

"OKPG90WOIJD98JKSJKH"

ā€‹
responseCode
string
required

Internal status code, where I100 indicates successful push initiation.

Example:

"I100"

ā€‹
feeRuleCode
string
required

Applied fee calculation structure code, i.e. CC - Charge To Customer and CM - Charge To Merchant.

Example:

"CC"

ā€‹
transactionAmount
number<decimal>
required

Original transaction amount requested.

Example:

100

ā€‹
totalCharges
number<decimal>
required

Processing charges and gateway fees calculated for this payment request.

Example:

2.5

ā€‹
amountToPay
number<decimal>
required

Total amount to be debited/collected from the customer.

Example:

102.5