Pochipay Apis

Pochipay Payment Gateway Integration

Welcome to the Pochipay Payment Gateway API docs. This guide provides details on how to integrate with Pochipay for various payment and disbursement functionalities. The APIs are designed to be asynchronous by default which means the final status of a transaction is communicated back to the client through a http callback.

Getting Started

Before you start integrating with Pochipay, ensure you have the following:

• Your API credentials (email, password)

• Proper authorization headers in each request using the Bearer token

Authentication

The Pochipay API uses JWT for authentication. To interact with the endpoints, you must first retrieve an access token using the /account/token endpoint. The token expires after 3600 seconds.

Token Request

• Endpoint: POST https://app.pochipay.com/api/v1/account/token

• Headers: None

• Body Parameters:

  • email: Your email address

  • password: Your password

Sample Request/Response

Request:

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

Response (200 OK - Success):

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

Save the access_token and use it in the Authorization header for subsequent requests: Bearer your-access-token

---

Disbursement

Get Banks

• Endpoint: GET https://app.pochipay.com/api/v1/disbursement/banks

• Description: Retrieves a list of available banks for disbursement

• Headers: Authorization

Sample Response (200 OK - Success):

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

Send to Mobile

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

• Description: Sends funds to a valid Mpesa mobile number

• Headers: Authorization

Sample Request/Response

Request:

{
  "callbackUrl": "", //your callback url
  "requestId": "", //unique reference to identify the disbursement batch
  "disbursementTitle": "", // a title for the disbursement
  "recipients": [
    {
      "amount": 0, // an amount greater than 0
      "remarks": "", //the narrations
      "trackingReference": "", // a unique reference for this specific recipient
      "phoneNumber": "" // target phone number
    }
  ]
}

Response (200 OK - Success):

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

Response (400 - Bad Request):

{
  "result": null,
  "message": "An error message",
  "errors": []
}

---

Send to Bank

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

• Description: Sends funds to a supported bank account. See Get Banks above to fetch a list of supported banks

• Headers: Authorization

Sample Request/Response

Request:

{
  "callbackUrl": "", //your callback url
  "requestId": "", //unique reference to identify the disbursement batch
  "disbursementTitle": "", // a title for the disbursement
  "recipients": [
    {
      "amount": 0, // an amount greater than 0
      "remarks": "", //the narrations
      "trackingReference": "", // a unique reference for this specific recipient
      "bankCode": "", // bank code obtained from the get banks endpoint
      "accountNumber": "" // bank account number
    }
  ]
}

Response (200 OK - Success):

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

Response (400 Bad Request):

{
    "result": null,
    "message": "An error message",
    "errors": ["validation","errors"]
}

---

Send to Paybill or Till Number

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

• Description: Allows funds transfer to Mpesa Paybill and Till numbers

• Headers: Authorization

Sample Request/Response

Request:

{
  "callbackUrl": "", //your callback url
  "requestId": "", //unique reference to identify the disbursement batch
  "disbursementTitle": "", // a title for the disbursement
  "recipients": [
    {
      "amount": 0,
      "remarks": "", //the narrations
      "trackingReference": "", // a unique reference for this specific recipient
      "shortCode": "", // paybill or till number
      "accountNumber": null, // account number if paybill or leave null
      "IsPaybill": false //true if shortcode is a paybill
    }
  ]
}

Response (200 OK - Success):

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

Response (400 Bad Request):

{
  "result": null,
  "message": "An error message",
  "errors": []
}

Disbursement Callback

A callback is dispatched to your callback URL once transaction processing is completed. Please ensure that your endpoint accepts POST request and is not behind any authentication.

The structure of the json is shown below:

{
  "successful": true, // true or false
  "requestId": "", // your disbursement batch id
  "trackingReference": "", //your recipient tracking reference
  "thirdPartyReference": "", //Transaction reference from third party such as Mpesa
  "failReason": null //Reason for failure if value of successful was false
}

Disbursement Status

You can call this endpoint in cases where you have missed your disbursement callback.

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

• Description: Retrieves the status of a disbursement

• Headers:

  • Authorization: Bearer {token}

  • Content-Type: application/json

  • accept: text/plain

Sample cURL Request:

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

Request Body:

{
  "trackingReference": "unique-ref-01-19" // your recipient tracking reference
}

Response with Pending Status (200 OK):

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

Response with Completed Status (200 OK):

{
  "result": {
    "trackingReference": "unique-ref-01",
    "status": "Complete",
    "thirdPartyReference": "TG1957228P"
  },
  "message": "success",
  "errors": []
}

Response (404 Not Found):

{
  "result": null,
  "message": "Transaction not found",
  "errors": []
}

Response (400 Bad Request):

{
  "result": null,
  "message": "Invalid request",
  "errors": ["Validation errors"]
}

Retry Pending Disbursement

If the status is pending and has a narrationId, the transaction can be retried using the endpoint below:

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

• Description: Retries a pending disbursement using the narration ID

• Headers:

  • Authorization: Bearer {token}

  • Content-Type: application/json

  • accept: text/plain

Sample cURL Request:

curl -X 'POST' \
  'https://app.pochipay.com/api/v1/disbursement/execute-narration' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json' \
  -d '{
  "narrationId": "0199a09b-4716-77cb-9883-6bcd3876ce00"
}'

Request Body:

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

Response (200 OK):

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

Cancel Pending Disbursement

A transaction can only be cancelled if it's been pending for at least 24 hours.

• Endpoint: POST https://app.pochipay.com/api/v1/disbursement/cancel

• Description: Cancels a pending disbursement transaction

• Headers:

  • Authorization: Bearer {token}

  • Content-Type: application/json

  • accept: text/plain

Sample cURL Request:

curl -X 'POST' \
  'https://app.pochipay.com/api/v1/disbursement/cancel' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJ....' \
  -H 'Content-Type: application/json' \
  -d '{
  "trackingReference": "TX1234567"
}'

Request Body:

{
  "trackingReference": "TX1234567"
}

Response (200 OK):

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

---

Account

Balance

• Endpoint: GET https://app.pochipay.com/api/v1/account/balance

• Description: Retrieves the current balance

• Headers: Authorization

Sample Response (200 OK - Success):

{
  "result": {
    "currency": "KES", //currently only KES is supported
    "balance": 0.00
  },
  "message": null,
  "errors": []
}

Transactions

Summaries

• Endpoint: GET https://app.pochipay.com/api/v1/transactions/summaries

• Description: Retrieves transaction summaries

• Headers: Authorization

Sample Response (200 OK - Success):

{
    "result": {
        "totalInternalCollections": 0, //total collections that topup your wallet
        "totalThirdPartyCollections": 0, //total collections redirected to your alternative paybill or till
        "totalDisbursements": 0 //total disbursement value
    },
    "errors": []
}

Collections

Mpesa Collections

• Endpoint: POST https://app.pochipay.com/api/v1/collections/mpesa

• Description: Initiates an Mpesa collection

• Headers: Authorization

Sample Request/Response

Request:

{
  "orderId": "", //your collection identifier
  "billRefNumber": "", // a reference number for the payment
  "phoneNumber": "", // valid mpesa phone number
  "amount": 0, //an amount greater than 0
  "narration": "", // description of the transaction
  "callbackUrl": "" // your callback URL
}

Response (200 OK - Success):

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

Response (400 Bad Request):

{
  "result": null,
  "message": "An error message",
  "errors": []
}

Collection Callback

A callback is dispatched to your callback URL once transaction processing is completed. Please ensure that your endpoint accepts POST request and is not behind any authentication.

The structure of the json is shown below:

{
  "orderId": "", //your order id
  "billRefNumber": "", //bill reference number
  "phoneNumber": "", //phone number of the payer
  "amount": 0, //collection amount
  "thirdPartyReference": "", // reference from provider
  "failReason": null, //fail reason if any
  "isSuccessful": true // true if successful, false if not
}

Collection Query

You can query collections using different parameters: MpesaReference, BillReferenceNumber, or OrderId.

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

• Description: Query collection details using various reference parameters

• Headers:

  • Authorization: Bearer {token}

  • accept: */*

Sample cURL Requests:

Using MpesaReference:

curl -X 'GET' \
  'https://app.pochipay.com/api/v1/collections/mpesa/collection-query?MpesaReference=TXXXX8KK3M' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGci...'

Using BillReferenceNumber:

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

Using OrderId:

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

Success Response (200 OK):

{
  "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": []
}

Failed Response (200 OK):

{
  "result": {
    "phoneNumber": "+2547xxxxxxxx",
    "orderId": "019a2449-0433-7182-892d-b6df3456d262",
    "billReferenceNumber": "TXXTXTXTX",
    "narration": "Some narration",
    "amount": 10,
    "resultCode": "1032",
    "resultDescription": "Request Cancelled by user.",
    "mpesaReference": "",
    "isSuccessful": false,
    "status": "Failed",
    "isOfflinePayment": false
  },
  "errors": []
}

Pending Response (200 OK):

{
  "result": {
    "phoneNumber": "+2547xxxxxxxx",
    "orderId": "0199df93-8131-7661-ac11-2c27d1f542ee",
    "billReferenceNumber": "TXXTXTXTXY",
    "narration": "Some Narration",
    "amount": 10,
    "isSuccessful": false,
    "status": "Pending",
    "isOfflinePayment": false
  },
  "errors": []
}

Not Found Response (404):

{
  "message": "No Mpesa collections found matching the criteria",
  "errors": []
}

Collection Status

This endpoint can be called to query the status of a collection in cases where you have missed the collection callback.

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

• Description: Checks status of a mpesa collection

• Headers: Authorization

Sample Request/Response

Request:

{
  "collectionId": "" //id of the collection
}

Response (200 OK):

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

Response (404 Not Found):

{
  "result": null,
  "message": "Collection not found",
  "errors": []
}

Response (400 Bad Request):

{
  "result": null,
  "message": "Invalid request",
  "errors": ["Validation errors"]
}

Conclusion

This documentation outlines the main endpoints available in the Pochipay API, covering authentication, disbursement, account balance, transactions, and collections.

Always ensure your requests include the proper authorization headers using the Bearer token.

For more details, refer to the specific endpoint sections above and the sample requests/responses provided.

Key Points to Remember:

• All APIs use JWT authentication with Bearer tokens

• Tokens expire after 3600 seconds (1 hour)

• Most operations are asynchronous and use callbacks

• Currently only KES currency is supported

• Ensure callback URLs accept POST requests and are not behind authentication

• Keep track of your requestId and trackingReference for status queries

Base URL

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

Support

For additional support or questions about the API, please contact the Pochipay support team.

---

Last updated: October 2025