# 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**:

```json
{
  "email": "your@email.address",
  "password": "YourPa$$w0d"
}
```

**Response (200 OK - Success)**:

```json
{
  "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)**:

```json
{
  "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**:

```json
{
  "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)**:

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

**Response (400 - Bad Request)**:

```json
{
  "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**:

```json
{
  "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)**:

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

**Response (400 Bad Request)**:

```json
{
    "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**:

```json
{
  "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)**:

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

**Response (400 Bad Request)**:

```json
{
  "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:

```json
{
  "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**:

```bash
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**:

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

**Response with Pending Status (200 OK)**:

```json
{
  "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)**:

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

**Response (404 Not Found)**:

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

**Response (400 Bad Request)**:

```json
{
  "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**:

```bash
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**:

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

**Response (200 OK)**:

```json
{
  "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**:

```bash
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**:

```json
{
  "trackingReference": "TX1234567"
}
```

**Response (200 OK)**:

```json
{
  "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)**:

```json
{
  "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)**:

```json
{
    "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**:

```json
{
  "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)**:

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

**Response (400 Bad Request)**:

```json
{
  "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:

```json
{
  "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**:

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

**Using BillReferenceNumber**:

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

**Using OrderId**:

```bash
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)**:

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

**Failed Response (200 OK)**:

```json
{
  "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)**:

```json
{
  "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)**:

```json
{
  "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**:

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

**Response (200 OK)**:

```json
{
  "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)**:

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

**Response (400 Bad Request)**:

```json
{
  "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*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.pochipay.com/pochipay-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.