Payer Gateway API Documentation

Authentication

To perform API operations, you need to first generate a token using the username and password issued during setup. The token will be used in the Authorization header for subsequent operations.

GET https://api.payer-gateway.com/api/v1

Headers

Authorization: Basic Y29sbHM6Y29tZXRhcHBtYWlu

Example cURL Request

curl --location 'https://api.payer-gateway.com/api/v1' \
--header 'Authorization: Basic Y29sbHM6Y29tZXRhcHBtYWlu'

Mobile APIs

STK Push (C2B)

Initiate an STK push to request payment from a customer's mobile money account.

POST https://api.payer-gateway.com/api/v1/mobile/initiate

Headers

Authorization: Bearer <token>

Request Body

{
  "impalaMerchantId": "{{username}}",
  "displayName": "AVIATOR",
  "currency": "KES",
  "amount": 10,
  "payerPhone": "254768899729",
  "mobileMoneySP": "M-Pesa",
  "externalId": "ImpadlTdest2",
  "callbackUrl": "https://97e6-217-21-116-242.ngrok-free.app/"
}

Sample Response

{
  "message": "Payment initiation successful",
  "secureId": "qdml8553ZeInavKorBHzLA==",
  "transactionId": "ImpadlTdest2"
}

Callback Success Response

{
  "amount": 10,
  "currency": "KES",
  "externalId": "ImpadlTdest25",
  "netAmount": 10,
  "secureId": "i1FHTQgFpHP0g-MRacZXUQ==",
  "transactionReport": "COMPLETE",
  "transactionStatus": "COMPLETE"
}

Callback Failed Response

{
  "amount": 10,
  "currency": "KES",
  "externalId": "ImpadlTdest25",
  "netAmount": 10,
  "secureId": "6S4mi15UgO2xYkjjyqH4gA==",
  "transactionReport": "FAILED",
  "transactionStatus": "FAILED"
}

Money Transfer (B2C)

Transfer money from your merchant account to a customer's mobile money account.

POST https://api.payer-gateway.com/api/v1/mobile/transfer

Headers

Authorization: Bearer <token>

Request Body

{
  "impalaMerchantId": "{{username}}",
  "currency": "KES",
  "amount": 10,
  "recipientPhone": "254768899729",
  "mobileMoneySP": "M-Pesa",
  "externalId": "joeltest404",
  "callbackUrl": "https://97e6-217-21-116-242.ngrok-free.app/"
}

Sample Response

{
  "message": "Payment initiation successful",
  "secureId": "qdml8553ZeInavKorBHzLA==",
  "transactionId": "a392-45d1-93c1-58f9447915e717138558"
}

Callback Success Response

{
  "amount": 10,
  "currency": "KES",
  "externalId": "joeltest404",
  "netAmount": 10,
  "receiverPartyPublicName": "07688XXXX - Collins Williams",
  "secureId": "4p-LIGOa5iO-1xjDR_bZZg==",
  "transactionCompletedDateTime": "11.02.2025 01:44:17",
  "transactionReceipt": "TBB8KE0GQW",
  "transactionReport": "COMPLETE",
  "transactionStatus": "COMPLETE"
}

Callback Failed Response

{
  "amount": 10,
  "currency": "KES",
  "externalId": "ImpadlTdest2",
  "netAmount": 10,
  "secureId": "ldFuXRQn_JmCVoili4ItEw==",
  "transactionReport": "FAILED",
  "transactionStatus": "FAILED"
}

Card Transaction

Process card payments through a secure payment gateway.

POST https://api.payer-gateway.com/api/v1/card/initiate

Headers

Authorization: Bearer <token>

Request Body

{
  "impalaMerchantId": "{{username}}",
  "currency": "USD",
  "amount": 1,
  "mobileMoneySP": "card",
  "externalId": "ImpadlTdest2",
  "redirectUrl": "backtoyoursite.com",
  "callbackUrl": "https://8bd0-2c0f-fe38-2413-2c98-7114-6990-db59-11c.ngrok-free.app/mc/log.php"
}

Sample Response

{
  "cardLink": "https://api.payer-gateway.com/uba.php?data=YW1vdW50PTEuMDAmbWVyY2hhbnQ9YXBwJmNhbGxiYWNrPWh0dHBzOi8vOGJkMC0yYzBmLWZlMzgtMjQxMy0yYzk4LTcxMTQtNjk5MC1kYjU5LTExYy5uZ3Jvay1mcmVlLmFwcC9tYy9sb2cucGhwJnJlZGlyZWN0PU9XWEpKRFVNZ1B2aDlYUWhTQnk5eGc9PSZleHRlcm5hbGlkPUltcGFkbFRkZXN0Mg==",
  "message": "card Payment initiation successful",
  "secureId": "OWXJJDUMgPvh9XQhSBy9xg=="
}

Callback Success Response

{
  "transactionStatus": "COMPLETED",
  "transactionReport": "SUCCESS",
  "currency": "KES",
  "amount": "5.00",
  "netAmount": "5.00",
  "secureId": "8e6bfa77-4f2a-4ff6-af48-ef774f2178ca",
  "externalId": "BoomW",
  "redirectUrl": "bRbHRh6Tmi1mBNUzKKTtzA=="
}

Callback Failed Response

{
  "transactionStatus": "FAILED",
  "transactionReport": "N/A",
  "currency": "KES",
  "amount": "5.00",
  "netAmount": "5.00",
  "secureId": "8e6bfa77-4f2a-4ff6-af48-ef774f2178ca",
  "externalId": "BoomW",
  "redirectUrl": "bRbHRh6Tmi1mBNUzKKTtzA=="
}

Bank Transfer

Initiate a bank transfer payment request. This endpoint follows the same structure as the STK Push initiate endpoint, but uses bank-specific fields instead of mobile money fields.

Key Differences from Mobile Initiate
mobileMoneySP is replaced with bankName, and payerPhone is replaced with accountNumber.

POST https://api.payer-gateway.com/api/v1/bank/initiate

Headers

Authorization: Bearer <token>

Request Body

{
  "impalaMerchantId": "{{username}}",
  "displayName": "AVIATOR",
  "currency": "KES",
  "amount": 10,
  "accountNumber": "1234567890",
  "bankName": "Equity Bank",
  "externalId": "ImpadlTdest2",
  "callbackUrl": "https://97e6-217-21-116-242.ngrok-free.app/"
}

Field Descriptions

accountNumber: The bank account number
bankName: The name of the bank
All other fields remain the same as the mobile initiate endpoint

Sample Response

{
  "message": "Payment initiation successful",
  "secureId": "qdml8553ZeInavKorBHzLA==",
  "transactionId": "ImpadlTdest2"
}

Callback Success Response

{
  "amount": 10,
  "currency": "KES",
  "externalId": "ImpadlTdest25",
  "netAmount": 10,
  "secureId": "i1FHTQgFpHP0g-MRacZXUQ==",
  "transactionReport": "COMPLETE",
  "transactionStatus": "COMPLETE"
}

Callback Failed Response

{
  "amount": 10,
  "currency": "KES",
  "externalId": "ImpadlTdest25",
  "netAmount": 10,
  "secureId": "6S4mi15UgO2xYkjjyqH4gA==",
  "transactionReport": "FAILED",
  "transactionStatus": "FAILED"
}

Balance APIs

Payins Balance

Retrieve your current payins balance across all supported currencies.

GET https://api.payer-gateway.com/api/v1/read/payins/balance

Headers

Authorization: Bearer <token>

Example cURL Request

curl --location 'https://api.payer-gateway.com/api/v1/read/payins/balance' \
--header 'Authorization: Bearer <your_token_here>'

Sample Response

{
  "Balances": {
    "baseCurrency": "KES",
    "eurBalance": 0,
    "gbpBalance": 0,
    "impaBalance": 0,
    "kesBalance": 6020.95,
    "lumenBalance": 0,
    "merchantId": "app",
    "totalBalance": 27476.126842105266,
    "tzsBalance": 0,
    "ugxBalance": 0,
    "usdBalance": 0,
    "usdcBalance": 0,
    "usdtBalance": 0,
    "xafBalance": 99064
  },
  "baseCurrency": "KES",
  "merchantId": "app"
}

Payouts Balance

Retrieve your current payouts balance across all supported currencies.

GET https://api.payer-gateway.com/api/v1/read/payouts/balance

Headers

Authorization: Bearer <token>

Example cURL Request

curl --location 'https://api.payer-gateway.com/api/v1/read/payouts/balance' \
--header 'Authorization: Bearer <your_token_here>'

Sample Response

{
  "Balances": {
    "baseCurrency": "KES",
    "eurBalance": 1.24,
    "gbpBalance": 1.28,
    "impaBalance": 299999740,
    "kesBalance": 6180,
    "lumenBalance": 0,
    "merchantId": "app",
    "totalBalance": 740700119774.2283,
    "tzsBalance": 0,
    "ugxBalance": 200,
    "usdBalance": 6043.45,
    "usdcBalance": 68.993935,
    "usdtBalance": 2.43,
    "xafBalance": 400
  },
  "baseCurrency": "KES",
  "merchantId": "app"
}

Transaction Status

Check the status of a transaction using the secure ID returned during transaction initialization.

GET https://api.payer-gateway.com/api/v1/transaction?merchant=<your_merchant_id>&secureId=<secure_id>

Headers

Authorization: Bearer <token>

Notes

Replace <your_merchant_id> with your actual merchant ID
Replace <secure_id> with the secure ID returned during transaction initialization

Example Request

https://api.payer-gateway.com/api/v1/transaction?merchant=impala&secureId=d4XeBKNruNJnvhOMOd8RLg==

Sample Response

{
  "transaction": {
    "amount": 1,
    "callback_url": "https://f0d6-197-232-22-252.ngrok-free.app",
    "currency": "USD",
    "date_added": 1741675246,
    "external_id": "ImpadlTdest2",
    "impalaMerchantId": "impala",
    "secure_id": "d4XeBKNruNJnvhOMOd8RLg==",
    "source_of_funds": "card",
    "transaction_report": "collection",
    "transaction_status": "PENDING"
  }
}

Transaction Status Values

Status	Description
`PENDING`	Transaction is being processed
`COMPLETED`	Transaction was successful
`FAILED`	Transaction failed

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
500	Internal Server Error

Rate Limits

Mobile APIs: Not specified
Card Transactions: Not specified
Balance APIs: Not specified
Transaction Status: Not specified

Support

Payer Gateway Team

Documentation Version

3.0.0

Transaction Search API Documentation

The Transaction Search API allows you to search and filter transactions based on multiple criteria including merchant ID, phone number, amount, currency, status, and more.

GET /api/v1/transactions/search

Authentication

Authorization: Bearer <your_token>

Query Parameters

Parameter	Type	Description	Example
`merchantId`	string	Filter by merchant ID	`merchant123`
`phone`	string	Search by phone number	`254712345678`
`amount`	integer	Filter by exact transaction amount	`1000`
`currency`	string	Filter by currency code	`KES`
`status`	string	Filter by transaction status	`SUCCESS`
`report`	string	Filter by transaction report type	`collection`
`externalId`	string	Search by exact external ID	`ImpadlTdest25`
`secureId`	string	Search by exact secure ID	`6S4mi15UgO2xYkjjyqH4gA==`
`sourceOfFunds`	string	Filter by source of funds	`MPESA`
`startDate`	integer	Unix timestamp from	`1704067200`
`endDate`	integer	Unix timestamp to	`1704153600`
`page`	integer	Page number	`1`
`page_size`	integer	Results per page	`20`

Request Examples

Example 1: Search by Merchant and Status

curl -X GET "https://api.example.com/api/v1/transactions/search?merchantId=merchant123&status=SUCCESS&page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example 2: Search by Phone Number

curl -X GET "https://api.example.com/api/v1/transactions/search?phone=254712345678" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example 3: Search by Amount and Currency

curl -X GET "https://api.example.com/api/v1/transactions/search?amount=1000&currency=KES" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example 4: Search by Date Range

curl -X GET "https://api.example.com/api/v1/transactions/search?startDate=1704067200&endDate=1704153600&status=SUCCESS" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example 5: Complex Search with Multiple Filters

curl -X GET "https://api.example.com/api/v1/transactions/search?merchantId=merchant123&phone=254712345678&amount=1000&currency=KES&status=SUCCESS&report=collection&sourceOfFunds=MPESA&page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200 OK)

{
  "transactions": [
    {
      "id": 1234,
      "impalaMerchantId": "merchant123",
      "transactionStatus": "SUCCESS",
      "transactionReport": "collection",
      "currency": "KES",
      "amount": 1000,
      "msisdn": "254712345678",
      "netAmount": 1000.0,
      "secureId": "6S4mi15UgO2xYkjjyqH4gA==",
      "sourceOfFunds": "MPESA",
      "externalId": "ImpadlTdest25",
      "callbackUrl": "https://merchant.com/callback",
      "dateAdded": 1704067200,
      "merchantRequestID": "AG_20240101_123456",
      "checkoutRequestID": "ws_CO_01012024123456",
      "responseCode": "0",
      "responseDescription": "Success",
      "callbackStatus": "SENT"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 5,
    "total_items": 100
  }
}

Error Responses

401 Unauthorized

{
  "error": "Missing authentication details"
}

400 Bad Request

{
  "error": "Invalid request format",
  "details": "Invalid page number"
}

500 Internal Server Error

{
  "error": "Failed to search transactions",
  "details": "Database connection error"
}

Response Fields

Field	Type	Description
`id`	integer	Unique transaction ID
`impalaMerchantId`	string	Merchant identifier
`transactionStatus`	string	Current transaction status
`transactionReport`	string	Transaction type
`currency`	string	Currency code
`amount`	integer	Transaction amount
`msisdn`	string	Phone number associated with the transaction
`netAmount`	float	Net amount after fees
`secureId`	string	Secure transaction identifier
`sourceOfFunds`	string	Payment source
`externalId`	string	External transaction identifier
`callbackUrl`	string	Merchant callback URL
`dateAdded`	integer	Unix timestamp when transaction was created
`merchantRequestID`	string	Merchant request identifier
`checkoutRequestID`	string	Checkout request identifier
`responseCode`	string	Response code from payment provider
`responseDescription`	string	Response description
`callbackStatus`	string	Callback delivery status

Pagination Object

Field	Type	Description
`current_page`	integer	Current page number
`per_page`	integer	Number of items per page
`total_pages`	integer	Total number of pages
`total_items`	integer	Total number of matching transactions

Transaction Status Values

Status	Description
`PENDING`	Transaction is pending processing
`SUCCESS`	Transaction completed successfully
`FAILED`	Transaction failed
`COMPLETE`	Transaction completed (synonym for SUCCESS)
`processing`	Transaction is being processed

Transaction Report Types

Type	Description
`collection`	Collection/payment received
`withdraw`	Withdrawal/payout
`deposit`	Deposit transaction

Source of Funds Values

MPESA - M-Pesa mobile money
CARD - Card payment
CRYPTO - Cryptocurrency payment
ECITIZEN - eCitizen payment

Notes

Phone Number Search: The phone parameter uses partial matching, so you can search with partial phone numbers.
Date Range: Both startDate and endDate should be Unix timestamps.
Pagination: Default page size is 20, maximum page size is 100, and results are ordered by dateAdded in descending order.
Merchant ID: If authenticated, the merchantId parameter is automatically set from your token.
Combining Filters: All filters are combined with AND logic.
Empty Results: If no transactions match your criteria, you will receive an empty array with pagination metadata.

Rate Limiting

This endpoint may be subject to rate limiting. Check response headers for:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Payer Gateway API Documentation

Getting Started

Authentication

Headers

Example cURL Request

Mobile APIs

STK Push (C2B)

Headers

Request Body

Sample Response

Callback Success Response

Callback Failed Response

Money Transfer (B2C)

Headers

Request Body

Sample Response

Callback Success Response

Callback Failed Response

Card Transaction

Headers

Request Body

Sample Response

Callback Success Response

Callback Failed Response

Bank Transfer

Headers

Request Body

Field Descriptions

Sample Response

Callback Success Response

Callback Failed Response

Balance APIs

Payins Balance

Headers

Example cURL Request

Sample Response

Payouts Balance

Headers

Example cURL Request

Sample Response

Transaction Status

Headers

Notes

Example Request

Sample Response

Transaction Status Values

Error Codes

Rate Limits

Support

Transaction Search API Documentation

Authentication

Query Parameters

Request Examples

Example 1: Search by Merchant and Status

Example 2: Search by Phone Number

Example 3: Search by Amount and Currency

Example 4: Search by Date Range

Example 5: Complex Search with Multiple Filters

Success Response (200 OK)

Error Responses

401 Unauthorized

400 Bad Request

500 Internal Server Error

Response Fields

Pagination Object

Transaction Status Values

Transaction Report Types

Source of Funds Values

Notes

Rate Limiting