Pay Hero

https://docs.payhero.co.ke/
Admin
Pay Hero is a payment gateway and aggregation service that enables businesses to seamlessly...
Tokens:8,775
Snippets:69
Trust Score:4.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### API Request with Basic Authentication

Source: https://docs.payhero.co.ke/docs/authorization

Example of a GET request to the payment channels endpoint using cURL with the required Authorization header.

```bash
curl -X GET "https://backend.payhero.co.ke/api/v2/payment_channels"   -H "Authorization: Basic YOUR_AUTH_TOKEN"   -H "Content-Type: application/json"
```

--------------------------------

### Get Service Wallet Balance cURL Request

Source: https://docs.payhero.co.ke/docs/get-service-wallet-balance

Example cURL command to fetch the service wallet balance.

```bash
curl -X GET \
  'https://backend.payhero.co.ke/api/v2/wallets?wallet_type=service_wallet' \
```

--------------------------------

### Get Payment Channels cURL Request

Source: https://docs.payhero.co.ke/docs/get-payment-channels

Example cURL command to retrieve active payment channels.

```bash
curl -X GET \
  'https://backend.payhero.co.ke/api/v2/payment_channels?is_active=true' \
  -H 'Content-Type: application/json' \
```

--------------------------------

### Initiate STK Push with cURL

Source: https://docs.payhero.co.ke/docs/post-initiate-mpesa-stk-push-request

Example request using cURL to trigger an MPESA STK push.

```bash
curl -X POST \
  'https://backend.payhero.co.ke/api/v2/payments' \
  -H 'Content-Type: application/json' \
  -d '{"amount":100,"phone_number":"0787677676","channel_id":133,"provider":"m-pesa","external_reference":"INV-009","customer_name":"John Doe","callback_url":"https://example.com/callback.php"}'
```

--------------------------------

### Get Payment Channels Success Response

Source: https://docs.payhero.co.ke/docs/get-payment-channels

Example of a successful 200 OK response containing a list of payment channels and pagination metadata.

```json
{
  "payment_channels": [
    {
      "id": 26703032,
      "transaction_type": "CustomerPayBillOnline",
      "channel_type": "bank",
      "account_id": 18563,
      "short_code": "522522",
      "account_number": "232323232",
      "description": "PESA BANK",
      "is_active": true,
      "balance_plain": null,
      "created_at": "2024-02-07T07:18:33.815944Z",
      "updated_at": "2024-02-07T07:18:33.814576Z"
    }
  ],
  "pagination": {
    "count": 1,
    "next_page": null,
    "num_pages": 1,
    "page": 1,
    "per": 20,
    "prev_page": null
  }
}
```

--------------------------------

### Customized Lipwa Link Example

Source: https://docs.payhero.co.ke/docs/lipwa-link

A sample URL demonstrating how to pass pre-filled payment parameters to a Lipwa link.

```text
https://lipwa.link/5?amount=500&phone=254712345678&name=JohnDoe&channel_id=100&reference=Invoice123&success_url=https://yourwebsite.com/success&failed_url=https://yourwebsite.com/failed
```

--------------------------------

### Get Account Transactions Response

Source: https://docs.payhero.co.ke/docs/get-account-transactions

Example JSON response structure containing transaction details and pagination metadata.

```json
{
  "transactions": [
    {
      "id": 451,
      "account_id": 183,
      "invoice_id": null,
      "transaction_type": "service_charge",
      "description": "Received KES 50 from ",
      "amount": -6,
      "transaction_reference": "EB7C4Z7RXC",
      "provider_reference": "cost_EB7C4Z7RXC",
      "goal_id": null,
      "gateway": "sasapay",
      "cost": 6,
      "wallet_balance": 6775,
      "transaction_name": "Transaction Fee",
      "created_at": "2024-01-19T15:13:11.203273Z",
      "updated_at": "2024-01-19T15:13:11.202741Z"
    }
  ],
  "pagination": {
    "count": 284,
    "next_page": 3,
    "num_pages": 142,
    "page": 2,
    "per": 2,
    "prev_page": 1
  }
}
```

--------------------------------

### Get Transaction Status via cURL

Source: https://docs.payhero.co.ke/docs/get-transaction-status

Example request to fetch transaction status using the cURL command-line tool.

```bash
curl -X GET \
  'https://backend.payhero.co.ke/api/v2/transaction-status?reference=9c1c61dd-2085-4137-9b01-8f7fde01c567' \
```

--------------------------------

### Get Payment Channels Error Response

Source: https://docs.payhero.co.ke/docs/get-payment-channels

Example of a 400 Bad Request error response.

```json
{
  "error_message": "Invalid request"
}
```

--------------------------------

### Get Transaction Fees cURL Request

Source: https://docs.payhero.co.ke/docs/get-transaction-fees

Example cURL command to fetch transaction fees from the API endpoint.

```bash
curl -X GET \
  'https://backend.payhero.co.ke/api/transaction_fees' \
  -H 'Content-Type: application/json' \
```

--------------------------------

### Successful Response Example

Source: https://docs.payhero.co.ke/docs/post-initiate-mpesa-stk-push-request

The JSON response returned upon a successful STK push request.

```json
{
  "success": true,
  "status": "QUEUED",
  "reference": "E8UWT7CLUW",
  "CheckoutRequestID": "ws_CO_15012024164321519708344109"
}
```

--------------------------------

### Successful Response Example

Source: https://docs.payhero.co.ke/docs/register-payment-channel

The JSON structure returned upon a successful 200 OK registration of a payment channel.

```json
{
  "id": 2429,
  "transaction_type": "CustomerPayBillOnline",
  "channel_type": "bank",
  "account_id": 5000,
  "short_code": "522522",
  "account_number": "1280006242",
  "description": "KCB Bank",
  "is_active": true,
  "balance_plain": null,
  "created_at": "2025-06-05T14:56:01.513658753Z",
  "updated_at": "2025-06-05T14:56:01.513658753Z"
}
```

--------------------------------

### Get Account Transactions cURL Request

Source: https://docs.payhero.co.ke/docs/get-account-transactions

Example cURL command to retrieve transactions with specific page and per-page parameters.

```bash
curl -X GET \
  'https://backend.payhero.co.ke/api/v2/transactions?page=2&per=20' \
```

--------------------------------

### Install Pay Hero SDK

Source: https://docs.payhero.co.ke/docs/payment-button

Include the Pay Hero Button SDK script in your HTML file to enable widget functionality.

```html
<script src="https://applet.payherokenya.com/cdn/button_sdk.js?v=3.1"></script>
```

--------------------------------

### Get Transaction Fees Response Example

Source: https://docs.payhero.co.ke/docs/get-transaction-fees

The response returns an array of objects defining fee tiers with amount ranges and associated pricing.

```json
[
  {
    "amount_from": 1,
    "amount_to": 49,
    "price": 0
  },
  {
    "amount_from": 50,
    "amount_to": 499,
    "price": 6
  },
  {
    "amount_from": 500,
    "amount_to": 999,
    "price": 10
  },
  {
    "amount_from": 1000,
    "amount_to": 1499,
    "price": 15
  },
  {
    "amount_from": 1500,
    "amount_to": 2499,
    "price": 20
  }
]
```

--------------------------------

### Transaction Status Response Example

Source: https://docs.payhero.co.ke/docs/get-transaction-status

The JSON structure returned upon a successful 200 OK response.

```json
{
  "transaction_date": "2024-11-26T08:41:14.160604Z",
  "provider": "m-pesa",
  "success": true,
  "merchant": "Ron Doe",
  "payment_reference": "",
  "third_party_reference": "SKQ96C7K7H",
  "status": "SUCCESS",
  "reference": "6b71cb8b-638d-4b6e-9c7c-b0334a641e3a",
  "CheckoutRequestID": "",
  "provider_reference": "SKQ96C7K7H"
}
```

--------------------------------

### Service Wallet Top Up cURL Request

Source: https://docs.payhero.co.ke/docs/post-service-wallet-top-up

Example cURL command to perform a POST request to the top-up endpoint with required JSON body.

```bash
curl -X POST \
  'https://backend.payhero.co.ke/api/v2/topup' \
  -H 'Content-Type: application/json' \
  -d '{"amount":100,"phone_number":"0787677676"}'
```

--------------------------------

### Success Callback Payload Structure

Source: https://docs.payhero.co.ke/docs/payment-button

Example of the JSON payload sent to the configured callback URL upon a successful payment.

```json
{
  "paymentSuccess": true,
  "reference": "c632-4e27-9718-f9fcdec511d826234",
  "user_reference": "buttonTesting",
  "provider": "m-pesa",
  "providerReference": "TCT3K99UFZ",
  "amount": 1,
  "phone": "0708344101",
  "customerName": "Good Samaritan",
  "channel": "100"
}
```

--------------------------------

### GET https://backend.payhero.co.ke/api/v2/wallets

Source: https://docs.payhero.co.ke/docs/get-service-wallet-balance

Retrieves the balance and details of the service wallet.

```APIDOC
## GET https://backend.payhero.co.ke/api/v2/wallets

### Description
Query your service wallet balance.

### Method
GET

### Endpoint
https://backend.payhero.co.ke/api/v2/wallets

### Parameters
#### Headers
- **Authorization** (String) - Required - Basic auth token

#### Query Parameters
- **wallet_type** (String) - Required - Value: service_wallet

### Response
#### Success Response (200)
- **id** (Integer) - Wallet ID
- **account_id** (Integer) - Account ID
- **wallet_type** (String) - Type of wallet
- **currency** (String) - Currency code
- **available_balance** (Float) - Current available balance
- **created_at** (String) - Creation timestamp
- **updated_at** (String) - Last update timestamp

#### Response Example
{
  "id": 22156,
  "account_id": 22183,
  "wallet_type": "service_wallet",
  "currency": "KES",
  "available_balance": 15101.36,
  "created_at": "2024-01-12T08:36:38.209573Z",
  "updated_at": "2024-01-15T12:40:33.157508Z"
}
```

--------------------------------

### GET https://backend.payhero.co.ke/api/v2/payment_channels

Source: https://docs.payhero.co.ke/docs/get-payment-channels

Retrieve all payment channels associated with the authenticated account.

```APIDOC
## GET https://backend.payhero.co.ke/api/v2/payment_channels

### Description
Retrieve all your payment channels.

### Method
GET

### Endpoint
https://backend.payhero.co.ke/api/v2/payment_channels

### Parameters
#### Headers
- **Authorization** (String) - Required - Basic auth token
- **Content-Type** (String) - Required - application/json

#### Query Parameters
- **is_active** (boolean) - Optional - Filter active or inactive channels

### Response
#### Success Response (200)
- **payment_channels** (array) - List of payment channel objects
- **pagination** (object) - Pagination metadata

#### Response Example
{
  "payment_channels": [
    {
      "id": 26703032,
      "transaction_type": "CustomerPayBillOnline",
      "channel_type": "bank",
      "account_id": 18563,
      "short_code": "522522",
      "account_number": "232323232",
      "description": "PESA BANK",
      "is_active": true,
      "balance_plain": null,
      "created_at": "2024-02-07T07:18:33.815944Z",
      "updated_at": "2024-02-07T07:18:33.814576Z"
    }
  ],
  "pagination": {
    "count": 1,
    "next_page": null,
    "num_pages": 1,
    "page": 1,
    "per": 20,
    "prev_page": null
  }
}
```

--------------------------------

### GET https://backend.payhero.co.ke/api/v2/transactions

Source: https://docs.payhero.co.ke/docs/get-account-transactions

Retrieve all account transactions with pagination support.

```APIDOC
## GET https://backend.payhero.co.ke/api/v2/transactions

### Description
Retrieve all account transactions with pagination support.

### Method
GET

### Endpoint
https://backend.payhero.co.ke/api/v2/transactions

### Parameters
#### Headers
- **Authorization** (String) - Required - Basic auth token

#### Query Parameters
- **page** (Integer) - Optional - The page number that you want to fetch data for
- **per** (Integer) - Optional - The total records per page

### Response
#### Success Response (200)
- **transactions** (Array) - List of transaction objects
- **pagination** (Object) - Pagination metadata including count, next_page, num_pages, page, per, and prev_page

#### Response Example
{
  "transactions": [
    {
      "id": 451,
      "account_id": 183,
      "invoice_id": null,
      "transaction_type": "service_charge",
      "description": "Received KES 50 from ",
      "amount": -6,
      "transaction_reference": "EB7C4Z7RXC",
      "provider_reference": "cost_EB7C4Z7RXC",
      "goal_id": null,
      "gateway": "sasapay",
      "cost": 6,
      "wallet_balance": 6775,
      "transaction_name": "Transaction Fee",
      "created_at": "2024-01-19T15:13:11.203273Z",
      "updated_at": "2024-01-19T15:13:11.202741Z"
    }
  ],
  "pagination": {
    "count": 284,
    "next_page": 3,
    "num_pages": 142,
    "page": 2,
    "per": 2,
    "prev_page": 1
  }
}
```

--------------------------------

### GET https://backend.payhero.co.ke/api/transaction_fees

Source: https://docs.payhero.co.ke/docs/get-transaction-fees

Retrieves the pricing structure for MPESA transactions. This endpoint does not require authentication.

```APIDOC
## GET https://backend.payhero.co.ke/api/transaction_fees

### Description
Get pricing for MPESA to Bank, Paybill, or Till number. This endpoint requires no authentication.

### Method
GET

### Endpoint
https://backend.payhero.co.ke/api/transaction_fees

### Headers
- **Content-Type** (String) - Required - application/json

### Response
#### Success Response (200)
- **amount_from** (Number) - The lower bound of the transaction amount range.
- **amount_to** (Number) - The upper bound of the transaction amount range.
- **price** (Number) - The fee associated with the transaction range.

#### Response Example
[
  {
    "amount_from": 1,
    "amount_to": 49,
    "price": 0
  },
  {
    "amount_from": 50,
    "amount_to": 499,
    "price": 6
  }
]
```

--------------------------------

### Get Service Wallet Balance Response

Source: https://docs.payhero.co.ke/docs/get-service-wallet-balance

The JSON structure returned upon a successful 200 OK request.

```json
{
  "id": 22156,
  "account_id": 22183,
  "wallet_type": "service_wallet",
  "currency": "KES",
  "available_balance": 15101.36,
  "created_at": "2024-01-12T08:36:38.209573Z",
  "updated_at": "2024-01-15T12:40:33.157508Z"
}
```

--------------------------------

### cURL Request for Bank Paybills

Source: https://docs.payhero.co.ke/docs/get-ph-bank-paybills

A cURL command to perform a GET request to the bank paybills endpoint.

```bash
curl -X GET \
  'https://backend.payhero.co.ke/api/v2/bank_paybills' \
  -H 'Content-Type: application/json' \
```

--------------------------------

### GET https://backend.payhero.co.ke/api/v2/bank_paybills

Source: https://docs.payhero.co.ke/docs/get-ph-bank-paybills

Fetch all Pay Hero registered bank paybills for your reference when registering payment channels.

```APIDOC
## GET https://backend.payhero.co.ke/api/v2/bank_paybills

### Description
Fetch all Pay Hero registered bank paybills for your reference when registering payment channels.

### Method
GET

### Endpoint
https://backend.payhero.co.ke/api/v2/bank_paybills

### Headers
- **Authorization** (String) - Required - Basic auth token
- **Content-Type** (String) - Required - application/json

### Response
#### Success Response (200)
- **bank_paybills** (Array) - A list of bank paybill objects containing id, name, paybill, created_at, and updated_at fields.

#### Response Example
{
  "bank_paybills": [
    {
      "id": "a46b4e6f-350e-4816-88eb-16bdaea2a437",
      "name": "Rafiki Micro Finance",
      "paybill": "802200",
      "created_at": "2024-01-21T18:01:16.478031Z",
      "updated_at": "2024-01-21T18:01:16.478031Z"
    },
    {
      "id": "6b308233-64a4-4049-9441-7d75315cbbd0",
      "name": "Citi Bank",
      "paybill": "100229",
      "created_at": "2024-01-21T18:01:16.91431Z",
      "updated_at": "2024-01-21T18:01:16.914311Z"
    }
  ]
}
```

--------------------------------

### GET https://backend.payhero.co.ke/api/v2/transaction-status

Source: https://docs.payhero.co.ke/docs/get-transaction-status

Fetch the status of any payment transaction using a reference ID or MPESA code.

```APIDOC
## GET https://backend.payhero.co.ke/api/v2/transaction-status

### Description
Fetch the status of any payment transaction.

### Method
GET

### Endpoint
https://backend.payhero.co.ke/api/v2/transaction-status

### Parameters
#### Headers
- **Authorization** (String) - Required - Basic auth token

#### Query Parameters
- **reference** (String) - Required - The reference that was returned in the original transaction request. You can also pass in the MPESA code of the transaction

### Response
#### Success Response (200)
- **transaction_date** (String) - The date the transaction occurred
- **provider** (String) - The payment provider (e.g., m-pesa)
- **success** (Boolean) - Whether the transaction was successful
- **merchant** (String) - The merchant name
- **payment_reference** (String) - Payment reference string
- **third_party_reference** (String) - Third party reference code
- **status** (String) - The status of the payment (QUEUED, SUCCESS, FAILED)
- **reference** (String) - The transaction reference ID
- **CheckoutRequestID** (String) - The checkout request ID
- **provider_reference** (String) - The provider reference code

#### Response Example
{
  "transaction_date": "2024-11-26T08:41:14.160604Z",
  "provider": "m-pesa",
  "success": true,
  "merchant": "Ron Doe",
  "payment_reference": "",
  "third_party_reference": "SKQ96C7K7H",
  "status": "SUCCESS",
  "reference": "6b71cb8b-638d-4b6e-9c7c-b0334a641e3a",
  "CheckoutRequestID": "",
  "provider_reference": "SKQ96C7K7H"
}
```

--------------------------------

### PayHero.init(config)

Source: https://docs.payhero.co.ke/docs/payment-button

Initializes the Pay Hero payment widget within a specified HTML container.

```APIDOC
## PayHero.init(config)

### Description
Initializes the Pay Hero payment widget. This method injects the payment interface into the specified container element.

### Parameters
- **paymentUrl** (string) - Required - Your Pay Hero Lipwa payment link
- **containerId** (string) - Required - The HTML element ID where the button will be injected
- **channelID** (number) - Required - Your unique payment channel ID
- **amount** (number) - Required - The amount to be paid
- **buttonName** (string) - Required - The text displayed on the payment button
- **buttonColor** (string) - Required - The color of the payment button
- **width** (string) - Optional - Width of the button (default: 100%)
- **height** (string) - Optional - Height of the button (default: 100%)
- **phone** (string) - Optional - Customer's phone number
- **name** (string) - Optional - Customer's name
- **reference** (string) - Optional - A unique reference for tracking payments
- **successUrl** (string) - Optional - URL to redirect the user upon a successful payment
- **failedUrl** (string) - Optional - URL to redirect the user if the payment fails
- **callbackUrl** (string) - Optional - Webhook URL where Pay Hero sends the payment details upon success

### Usage Example
```javascript
PayHero.init({
    paymentUrl: "https://lipwa.link/5",
    containerId: "payHero",
    channelID: 100,
    amount: 1,
    buttonName: "Pay Now KES 1",
    buttonColor: "#00a884"
});
```
```

--------------------------------

### Initialize Payment Widget

Source: https://docs.payhero.co.ke/docs/payment-button

Insert the container element and initialize the PayHero object with required configuration parameters and event listeners.

```html
<!-- PayHero Payment Container -->
<div id="payHero"></div>

<script>
    PayHero.init({
        paymentUrl: "https://lipwa.link/5", // Replace with your Lipwa link
        width: "100%",
        height: "100%",
        containerId: "payHero",
        channelID: 100, // Your payment channel ID
        amount: 1, // Payment amount
        phone: "0712345678", // (Optional) Customer phone
        name: "Good Samaritan", // (Optional) Customer name
        reference: "buttonTesting", // (Optional) Payment reference
        buttonName: "Pay Now KES 1", // Button text
        buttonColor: "#00a884", // Button color
        successUrl: null, // (Optional) Redirect URL after success
        failedUrl: null, // (Optional) Redirect URL after failure
        callbackUrl: null // (Optional) Webhook URL to receive payment payload
    });

    // Handling payment success or failure
    window.addEventListener('message', function(event) {
        if (event.data.paymentSuccess) {
            console.log("Payment Successful:", event.data);
            alert('Payment successful!');
        } else {
            alert('Oopsie! Payment failed');
        }
    });
</script>
```

--------------------------------

### POST https://backend.payhero.co.ke/api/v2/topup

Source: https://docs.payhero.co.ke/docs/post-service-wallet-top-up

Initiates a top-up request for the service wallet, triggering an MPESA prompt on the specified phone number.

```APIDOC
## POST https://backend.payhero.co.ke/api/v2/topup

### Description
Top up your service wallet on Pay Hero. The phone number you provide will get an MPESA prompt to enter PIN to complete the top-up request.

### Method
POST

### Endpoint
https://backend.payhero.co.ke/api/v2/topup

### Headers
- **Authorization** (String) - Required - Basic auth token
- **Content-Type** (String) - Required - application/json

### Request Body
- **amount** (Integer) - Required - The amount you want to top up (e.g., 100)
- **phone_number** (String) - Required - The phone number that will be used to facilitate the top up payment via MPESA (e.g., 0787677676)

### Request Example
{
  "amount": 100,
  "phone_number": "0787677676"
}

### Response
#### Success Response (200)
- **success** (Boolean) - Indicates if the request was successful
- **status** (String) - The status of the request (e.g., QUEUED)
- **reference** (String) - Unique reference for the transaction
- **CheckoutRequestID** (String) - The MPESA checkout request ID

#### Response Example
{
  "success": true,
  "status": "QUEUED",
  "reference": "09b8794f-4da0-4c93-af9b-43bdcdb58ea2",
  "CheckoutRequestID": "ws_CO_15012024161614816708344101"
}
```

--------------------------------

### Service Wallet Top Up Response

Source: https://docs.payhero.co.ke/docs/post-service-wallet-top-up

The successful response returns a status of QUEUED along with a reference and CheckoutRequestID for tracking.

```json
{
  "success": true,
  "status": "QUEUED",
  "reference": "09b8794f-4da0-4c93-af9b-43bdcdb58ea2",
  "CheckoutRequestID": "ws_CO_15012024161614816708344101"
}
```

--------------------------------

### Basic Authentication Header Format

Source: https://docs.payhero.co.ke/docs/authorization

The required format for the Authorization header in all API requests.

```http
Authorization: Basic YOUR_AUTH_TOKEN
```

--------------------------------

### POST https://backend.payhero.co.ke/api/v2/payments

Source: https://docs.payhero.co.ke/docs/post-initiate-mpesa-stk-push-request

Initiate an MPESA STK Push request to a customer's phone.

```APIDOC
## POST https://backend.payhero.co.ke/api/v2/payments

### Description
Initiate an MPESA STK Push request to a customer's phone number.

### Method
POST

### Endpoint
https://backend.payhero.co.ke/api/v2/payments

### Parameters
#### Headers
- **Authorization** (String) - Required - Basic auth token
- **Content-Type** (String) - Required - application/json

#### Request Body
- **amount** (Integer) - Required - Payment amount (e.g., 100)
- **phone_number** (String) - Required - Customer phone number (e.g., 0787677676)
- **channel_id** (Integer) - Required - Your registered payment channel ID
- **provider** (String) - Required - Value: m-pesa
- **external_reference** (String) - Optional - Your unique reference to track this transaction
- **customer_name** (String) - Optional - Customer name
- **callback_url** (String) - Optional - Your endpoint URL for payment status response
- **credential_id** (String) - Optional - ID of your registered credential

### Request Example
{
  "amount": 100,
  "phone_number": "0787677676",
  "channel_id": 133,
  "provider": "m-pesa",
  "external_reference": "INV-009",
  "customer_name": "John Doe",
  "callback_url": "https://example.com/callback.php"
}

### Response
#### Success Response (201)
- **success** (Boolean) - Status of the request
- **status** (String) - Current status (e.g., QUEUED)
- **reference** (String) - Transaction reference
- **CheckoutRequestID** (String) - Unique ID for the STK push request

#### Response Example
{
  "success": true,
  "status": "QUEUED",
  "reference": "E8UWT7CLUW",
  "CheckoutRequestID": "ws_CO_15012024164321519708344109"
}
```

--------------------------------

### POST https://backend.payhero.co.ke/api/v2/payment_channels

Source: https://docs.payhero.co.ke/docs/register-payment-channel

Registers a new payment channel (paybill, till, or bank) in the Pay Hero system.

```APIDOC
## POST https://backend.payhero.co.ke/api/v2/payment_channels

### Description
Register a new payment channel (paybill, till, or bank).

### Method
POST

### Endpoint
https://backend.payhero.co.ke/api/v2/payment_channels

### Headers
- **Authorization** (String) - Required - Basic auth token
- **Content-Type** (String) - Required - application/json

### Request Body
- **channel_type** (string) - Required - Can be: paybill, till or bank
- **account_id** (number) - Required - Your Pay Hero account ID
- **short_code** (number) - Required - Your MPESA paybill, till or bank paybill number
- **account_number** (string) - Required - Your bank account number or paybill account number (if any)
- **description** (string) - Required - Your bank name or beneficiary name for till or paybill

### Response
#### Success Response (200)
- **id** (number) - Channel ID
- **transaction_type** (string) - Transaction type
- **channel_type** (string) - Channel type
- **account_id** (number) - Account ID
- **short_code** (string) - Short code
- **account_number** (string) - Account number
- **description** (string) - Description
- **is_active** (boolean) - Active status
- **balance_plain** (null) - Balance
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Update timestamp

#### Response Example
{
  "id": 2429,
  "transaction_type": "CustomerPayBillOnline",
  "channel_type": "bank",
  "account_id": 5000,
  "short_code": "522522",
  "account_number": "1280006242",
  "description": "KCB Bank",
  "is_active": true,
  "balance_plain": null,
  "created_at": "2025-06-05T14:56:01.513658753Z",
  "updated_at": "2025-06-05T14:56:01.513658753Z"
}
```

--------------------------------

### Register Payment Channel cURL Request

Source: https://docs.payhero.co.ke/docs/register-payment-channel

A cURL command to register a payment channel by sending a POST request to the API endpoint with the required JSON body.

```bash
curl -X POST \
  'https://backend.payhero.co.ke/api/v2/payment_channels' \
  -H 'Content-Type: application/json' \
  -d '{"channel_type":"bank","account_id":5000,"short_code":522522,"account_number":"1280006242","description":"KCB Bank"}'
```

--------------------------------

### Payment Callback Response

Source: https://docs.payhero.co.ke/docs/payment-callback

The structure of the JSON payload sent to the callback_url after a payment is processed.

```APIDOC
## Payment Callback Response

### Description
This represents the JSON that will be sent to your request callback_url. It contains the ExternalReference provided in the initial request and the CheckoutRequestID returned in the request response to help track and update payments in your system.

### Response
- **forward_url** (string) - URL for forwarding
- **response** (object) - The payment details object
  - **Amount** (number) - The transaction amount
  - **CheckoutRequestID** (string) - Unique ID for the checkout request
  - **ExternalReference** (string) - The reference provided in the request
  - **MerchantRequestID** (string) - Unique ID for the merchant request
  - **MpesaReceiptNumber** (string) - The receipt number for the transaction
  - **Phone** (string) - The phone number used for payment
  - **ResultCode** (number) - The result code of the transaction
  - **ResultDesc** (string) - Description of the transaction result
  - **Status** (string) - The status of the payment
- **status** (boolean) - Indicates if the callback status is successful

### Response Example
{
  "forward_url": "",
  "response": {
    "Amount": 10,
    "CheckoutRequestID": "ws_CO_14012024103543427709099876",
    "ExternalReference": "INV-009",
    "MerchantRequestID": "3202-70921557-1",
    "MpesaReceiptNumber": "SAE3YULR0Y",
    "Phone": "+254709099876",
    "ResultCode": 0,
    "ResultDesc": "The service request is processed successfully.",
    "Status": "Success"
  },
  "status": true
}
```

--------------------------------

### Payment Callback JSON Response Structure

Source: https://docs.payhero.co.ke/docs/payment-callback

This JSON object is sent to the callback_url upon successful payment processing. Use the ExternalReference and CheckoutRequestID fields to reconcile the transaction in your system.

```json
{
  "forward_url": "",
  "response": {
    "Amount": 10,
    "CheckoutRequestID": "ws_CO_14012024103543427709099876",
    "ExternalReference": "INV-009",
    "MerchantRequestID": "3202-70921557-1",
    "MpesaReceiptNumber": "SAE3YULR0Y",
    "Phone": "+254709099876",
    "ResultCode": 0,
    "ResultDesc": "The service request is processed successfully.",
    "Status": "Success"
  },
  "status": true
}
```

--------------------------------

### Retrieve Bank Paybills Response

Source: https://docs.payhero.co.ke/docs/get-ph-bank-paybills

The JSON response structure containing a list of bank paybills with their respective IDs, names, and paybill numbers.

```json
{
  "bank_paybills": [
    {
      "id": "a46b4e6f-350e-4816-88eb-16bdaea2a437",
      "name": "Rafiki Micro Finance",
      "paybill": "802200",
      "created_at": "2024-01-21T18:01:16.478031Z",
      "updated_at": "2024-01-21T18:01:16.478031Z"
    },
    {
      "id": "6b308233-64a4-4049-9441-7d75315cbbd0",
      "name": "Citi Bank",
      "paybill": "100229",
      "created_at": "2024-01-21T18:01:16.91431Z",
      "updated_at": "2024-01-21T18:01:16.914311Z"
    }
  ]
}
```
Tokens:
Raw