Key Points

JWT auth with Bearer tokens

Tokens expire after 1 hour

Async operations via callbacks

Callbacks must accept POST

KES currency supported

Track via requestId & trackingReference

Authentication

The Pochipay API uses JWT for authentication. Retrieve an access token using your credentials — the token expires after 3600 seconds (1 hour).

POST

https://app.pochipay.com/api/v1/account/token

Get Access Token

Retrieve a JWT access token using your email and password.

Request Body

json

{
  "email": "[email protected]",
  "password": "YourPa$$w0d"
}

Field Notes

Save the accessToken and use it in the Authorization header for subsequent requests
Authorization: Bearer your-access-token
Token expires after 3600 seconds (1 hour)

Response

json

{
  "result": {
    "accessToken": "eyJhbGciOiJSUzI1....",
    "tokenType": "Bearer",
    "expiresIn": 3600
  },
  "errors": []
}

Disbursement

Send funds to mobile numbers, bank accounts, and businesses.

GET

https://app.pochipay.com/api/v1/disbursement/banks

Get Banks

Retrieves a list of available banks for disbursement.

Headers

Authorization

Response

json

{
  "result": [
    { "bankCode": "00", "name": "Example 1 Bank" },
    { "bankCode": "02", "name": "Example 2 Bank" }
  ],
  "message": "success",
  "errors": []
}

POST

https://app.pochipay.com/api/v1/disbursement/send-to-mobile

Send to Mobile

Sends funds to a valid Mpesa mobile number.

Headers

Authorization

Request Body

json

{
  "callbackUrl": "",
  "requestId": "",
  "disbursementTitle": "",
  "recipients": [
    {
      "amount": 0,
      "remarks": "",
      "trackingReference": "",
      "phoneNumber": ""
    }
  ]
}

Field Notes

callbackUrl — Your callback URL
requestId — Unique reference for the disbursement batch
disbursementTitle — A title for the disbursement
amount — An amount greater than 0
remarks — The narrations
trackingReference — Unique reference for this recipient
phoneNumber — Target phone number

Response

json

{ "result": { "isProcessing": true }, "message": null, "errors": [] }

POST

https://app.pochipay.com/api/v1/disbursement/send-to-bank

Send to Bank

Sends funds to a supported bank account.

Headers

Authorization

Request Body

json

{
  "callbackUrl": "",
  "requestId": "",
  "disbursementTitle": "",
  "recipients": [
    {
      "amount": 0,
      "remarks": "",
      "trackingReference": "",
      "bankCode": "",
      "accountNumber": ""
    }
  ]
}

Field Notes

bankCode — Bank code from the Get Banks endpoint
accountNumber — Bank account number

Response

json

{ "result": { "isProcessing": true }, "message": null, "errors": [] }

POST

https://app.pochipay.com/api/v1/disbursement/send-to-business

Send to Paybill or Till

Transfer funds to Mpesa Paybill and Till numbers.

Headers

Authorization

Request Body

json

{
  "callbackUrl": "",
  "requestId": "",
  "disbursementTitle": "",
  "recipients": [
    {
      "amount": 0,
      "remarks": "",
      "trackingReference": "",
      "shortCode": "",
      "accountNumber": null,
      "IsPaybill": false
    }
  ]
}

Field Notes

shortCode — Paybill or till number
accountNumber — Account number if paybill, or null
IsPaybill — true if shortcode is a paybill

Response

json

{ "result": { "isProcessing": true }, "message": null, "errors": [] }

POST

Your Callback URL

Disbursement Callback

Callback dispatched to your URL once processing completes. Ensure your endpoint accepts POST and is not behind authentication.

Field Notes

successful — true or false
thirdPartyReference — Transaction reference from Mpesa
failReason — Reason if successful was false

Response

json

{
  "successful": true,
  "requestId": "",
  "trackingReference": "",
  "thirdPartyReference": "",
  "failReason": null
}

POST

https://app.pochipay.com/api/v1/disbursement/transaction-status

Disbursement Status

Query the status of a disbursement when you missed the callback.

Headers

Authorization

Content-Type: application/json

Request Body

json

{ "trackingReference": "unique-ref-01-19" }

cURL Example

bash

curl -X 'POST' \
  'https://app.pochipay.com/api/v1/disbursement/transaction-status' \
  -H 'Authorization: Bearer eyJhbGciOi....' \
  -H 'Content-Type: application/json' \
  -d '{ "trackingReference": "unique-ref-01-19" }'

Response

json

{
  "result": {
    "trackingReference": "unique-ref-01-19",
    "status": "Pending",
    "message": "Transaction can be retried with the narrationId",
    "narrationId": "0199a09b-4716-77cb-9883-6bcd3876ce00"
  },
  "errors": []
}

POST

https://app.pochipay.com/api/v1/disbursement/execute-narration

Retry Pending Disbursement

Retries a pending disbursement using the narration ID.

Headers

Authorization

Content-Type: application/json

Request Body

json

{ "narrationId": "0199a09b-4716-77cb-9883-6bcd3876ce00" }

Response

json

{ "result": true, "message": "Disbursement list queued successfully", "errors": [] }

POST

https://app.pochipay.com/api/v1/disbursement/cancel

Cancel Pending Disbursement

Cancels a pending disbursement. Can only cancel if pending for at least 24 hours.

Headers

Authorization

Content-Type: application/json

Request Body

json

{ "trackingReference": "TX1234567" }

Response

json

{
  "result": {
    "narrationId": "01923da9-ddd0-729e-88fe-f063b1ba7648",
    "phoneNumber": "+2547xxxxxxxx",
    "amount": 10,
    "trackingReference": "TX1234567",
    "status": "Cancelled"
  },
  "message": "Transaction cancelled successfully",
  "errors": []
}

Account

Retrieve account information.

GET

https://app.pochipay.com/api/v1/account/balance

Get Balance

Retrieves the current account balance. Currently only KES is supported.

Headers

Authorization

Response

json

{
  "result": { "currency": "KES", "balance": 0.00 },
  "message": null,
  "errors": []
}

Transactions

Retrieve transaction summaries.

GET

https://app.pochipay.com/api/v1/transactions/summaries

Transaction Summaries

Retrieves aggregated transaction summaries.

Headers

Authorization

Field Notes

totalInternalCollections — Collections that top up your wallet
totalThirdPartyCollections — Collections redirected to your alternative paybill/till
totalDisbursements — Total disbursement value

Response

json

{
  "result": {
    "totalInternalCollections": 0,
    "totalThirdPartyCollections": 0,
    "totalDisbursements": 0
  },
  "errors": []
}

Collections

Initiate and query Mpesa collections.

POST

https://app.pochipay.com/api/v1/collections/mpesa

Initiate Mpesa Collection

Initiates an Mpesa STK push collection.

Headers

Authorization

Request Body

json

{
  "orderId": "",
  "billRefNumber": "",
  "phoneNumber": "",
  "amount": 0,
  "narration": "",
  "callbackUrl": ""
}

Field Notes

orderId — Your collection identifier
billRefNumber — A reference number for the payment
phoneNumber — Valid Mpesa phone number
amount — An amount greater than 0
narration — Description of the transaction
callbackUrl — Your callback URL

Response

json

{
  "result": {
    "collectionId": "xxxxxx-xxxxx-xxxx-xxxx",
    "isProcessing": true
  },
  "errors": []
}

POST

Your Callback URL

Collection Callback

Callback dispatched to your URL once collection processing completes.

Response

json

{
  "orderId": "",
  "billRefNumber": "",
  "phoneNumber": "",
  "amount": 0,
  "thirdPartyReference": "",
  "failReason": null,
  "isSuccessful": true
}

GET

https://app.pochipay.com/api/v1/collections/mpesa/collection-query

Collection Query

Query collections using MpesaReference, BillReferenceNumber, or OrderId.

Headers

Authorization

cURL Example

bash

# By MpesaReference
curl -X 'GET' \
  'https://app.pochipay.com/api/v1/collections/mpesa/collection-query?MpesaReference=TXXXX8KK3M' \
  -H 'Authorization: Bearer eyJhbGci...'
# By BillReferenceNumber
curl -X 'GET' \
  'https://app.pochipay.com/api/v1/collections/mpesa/collection-query?BillReferenceNumber=271025AAB58923ZY' \
  -H 'Authorization: Bearer eyJhbGci...'
# By OrderId
curl -X 'GET' \
  'https://app.pochipay.com/api/v1/collections/mpesa/collection-query?OrderId=271025AAB58923ZY' \
  -H 'Authorization: Bearer eyJhbGci...'

Response

json

{
  "result": {
    "phoneNumber": "2547xxxxxxxx",
    "orderId": "271025AAB58923ZY",
    "billReferenceNumber": "ABC947578",
    "narration": "test",
    "amount": 10,
    "resultCode": "0",
    "resultDescription": "The service request is processed successfully.",
    "mpesaReference": "TXXXX8KK3M",
    "isSuccessful": true,
    "status": "Complete",
    "isOfflinePayment": false
  },
  "errors": []
}

POST

https://app.pochipay.com/api/v1/collections/mpesa/transaction-status

Collection Status

Check the status of an Mpesa collection when you missed the callback.

Headers

Authorization

Request Body

json

{ "collectionId": "" }

Response

json

{
  "result": {
    "orderId": "your-order-id",
    "billRefNumber": "bill-ref",
    "phoneNumber": "254712345678",
    "amount": 100,
    "thirdPartyReference": "mpesa-reference",
    "failReason": null,
    "isSuccessful": true
  },
  "message": "success",
  "errors": []
}

API Reference

Key Points

Authentication

Get Access Token

Disbursement

Get Banks

Send to Mobile

Send to Bank

Send to Paybill or Till

Disbursement Callback

Disbursement Status

Retry Pending Disbursement

Cancel Pending Disbursement

Account

Get Balance

Transactions

Transaction Summaries

Collections

Initiate Mpesa Collection

Collection Callback

Collection Query

Collection Status