API Documentation

Authentication

All API requests require your API credentials sent as HTTP headers.

Authenticate every request by including these two headers:

Header	Description
X-API-Key	Your public API key from the dashboard
X-API-Secret	Your secret API key (keep this private)

HeadersX-API-Key:    pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-API-Secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

⚠️

Keep your secret key safe. Never expose it in client-side code, public repositories, or frontend applications. Use environment variables on your server.

Generate your API keys from the PayIn Dashboard under Settings → API Keys. You can also configure IP whitelisting and webhook secrets there.

Base URL

All API endpoints are relative to this base URL.

Production

https://api.payin.co.tz/api/v1

All requests must be made over HTTPS. HTTP requests will be rejected.

Idempotency

Prevent duplicate transactions with idempotency keys.

For POST requests (collection, invoice, disbursement), include an X-Idempotency-Key header to ensure the request is processed only once — even if you retry due to a timeout or network error.

Header	Description
X-Idempotency-Key	A unique string (max 255 chars) for this request. Use a UUID or your own reference.

How It Works

cURLcurl -X POST https://api.payin.co.tz/api/v1/collection \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"phone": "255714123456", "amount": 5000, "operator": "mpesa"}'

If you send the same X-Idempotency-Key again within 24 hours, the API returns the original response with an X-Idempotent-Replayed: true header instead of creating a duplicate transaction.

💡

Keys expire after 24 hours. After that, the same key can be reused. We recommend using UUIDs (e.g. 550e8400-e29b-41d4-a716-446655440000) or your internal order IDs as idempotency keys.

⚠️

Strongly recommended for payments. Without idempotency keys, retrying a timed-out request could double-charge your customer.

API Endpoints

Complete reference for all merchant-facing API endpoints.

POST /v1/collection Push USSD Collection

Initiate a USSD push collection. The customer receives a prompt on their phone to confirm the payment. Once confirmed, funds are deposited into your PayIn wallet and a webhook is sent to your callback URL.

Request Body

Parameter	Type	Required	Description
phone	string	Required	Customer phone number (10–15 digits). E.g. `255714123456`
amount	number	Required	Amount to collect. Min: 100, Max: 10,000,000
operator	string	Optional	Operator code: `mpesa`, `airtel`, `tigopesa`, `halopesa`. Auto-detected from phone number if omitted.
reference	string	Optional	Your internal reference. Max 100 characters.
description	string	Optional	Payment description. Max 255 characters.
currency	string	Optional	Currency code. Default: `TZS`
callback_url	string	Optional	Override the account-level callback URL for this request.

Example Request

cURLcurl -X POST https://api.payin.co.tz/api/v1/collection \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "255714123456",
    "amount": 5000,
    "operator": "mpesa",
    "reference": "INV-001",
    "description": "Monthly subscription"
  }'

Success Response

201 Created

JSON{
  "success": true,
  "message": "Collection request sent to operator. Waiting for customer confirmation.",
  "request_ref": "PAYABCDEF123456",
  "operator_ref": "12345678",
  "status": "processing",
  "phone": "255714123456",
  "amount": 5000,
  "operator": "M-Pesa"
}

Error Response

422 Validation failed or operator unavailable.

JSON{
  "message": "Operator not found or inactive.",
  "errors": { "operator": ["Invalid operator"] }
}

POST /v1/invoice Create Invoice (Manual C2B)

Create a payment invoice. The customer pays manually using the provided reference number through their mobile money provider. Ideal for e-commerce, invoicing, and point-of-sale.

Request Body

Parameter	Type	Required	Description
amount	number	Required	Amount to collect. Min: 100, Max: 10,000,000
reference	string	Required	Customer-facing payment reference. Max 100 chars.
description	string	Optional	Invoice description. Max 255 characters.
currency	string	Optional	Currency code. Default: `TZS`
phone	string	Optional	Customer phone for reference. 10–15 digits.
expires_in	integer	Optional	Expiry in minutes. Min: 1, Max: 43200. Default: 10080 (7 days).

Example Request

cURLcurl -X POST https://api.payin.co.tz/api/v1/invoice \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "reference": "INV-2026-001",
    "description": "Annual subscription",
    "expires_in": 1440
  }'

Success Response

201 Created

JSON{
  "success": true,
  "message": "Invoice created. Customer should pay using reference: INV-2026-001",
  "request_ref": "INVXYZ123456",
  "external_ref": "INV-2026-001",
  "amount": 50000,
  "currency": "TZS",
  "status": "waiting",
  "expires_at": "2026-04-20T10:30:00Z",
  "pay_url": "https://payin.co.tz/pay/a3f2b1c9d8e7..."
}

💡

The pay_url is a hosted payment page you can share with your customer. They can select their preferred operator and pay directly.

POST /v1/disbursement Send Payout

Send money to a mobile money number. The amount is deducted from your disbursement wallet. If your account has maker-checker enabled, the payout will require approval before processing.

Request Body

Parameter	Type	Required	Description
phone	string	Required	Recipient phone number. 10–15 digits.
amount	number	Required	Amount to send. Min: 100, Max: 10,000,000
operator	string	Optional	Operator code. Auto-detected from phone if not provided.
reference	string	Optional	Your internal reference. Max 100 characters.
description	string	Optional	Payout description. Max 255 characters.
currency	string	Optional	Currency code. Default: `TZS`
callback_url	string	Optional	Override the account-level callback URL for this payout.

Example Request

cURLcurl -X POST https://api.payin.co.tz/api/v1/disbursement \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "255714123456",
    "amount": 10000,
    "reference": "SALARY-001",
    "description": "March salary"
  }'

Success Response — Direct Send

201 Created

JSON{
  "success": true,
  "message": "Disbursement request sent to operator.",
  "request_ref": "PAY123ABC456",
  "status": "processing",
  "phone": "255714123456",
  "amount": 10000,
  "operator": "M-Pesa"
}

Success Response — Pending Approval

201 Created

JSON{
  "success": true,
  "message": "Payout request submitted for approval.",
  "request_ref": "PAY123ABC456",
  "status": "pending_approval",
  "requires_approval": true
}

Error — Insufficient Balance

422

JSON{
  "success": false,
  "message": "Insufficient wallet balance.",
  "required": 10500,
  "available": 8000
}

GET /v1/status/{request_ref} Payment Status

Check the current status of any payment request — collection, invoice, or disbursement.

Path Parameters

Parameter	Type	Description
request_ref	string	The `request_ref` returned when the payment was created.

Success Response

200 OK

JSON{
  "request_ref": "PAYABCDEF123456",
  "external_ref": "INV-001",
  "operator_ref": "12345678",
  "type": "collection",
  "phone": "255714123456",
  "amount": 5000,
  "charges": {
    "platform": 250.00,
    "operator": 75.00
  },
  "currency": "TZS",
  "operator": "M-Pesa",
  "status": "completed",
  "error": null,
  "created_at": "2026-04-19T10:15:00Z",
  "updated_at": "2026-04-19T10:20:00Z"
}

GET /v1/balance Account Balance

Retrieve your current wallet balances for collections and disbursements.

Success Response

200 OK

JSON{
  "account_id": "12345",
  "overall_balance": 250000.50,
  "collection_balance": 150000.00,
  "collection_held": 0.00,
  "disbursement_balance": 100000.50,
  "disbursement_held": 5000.00,
  "currency": "TZS",
  "updated_at": "2026-04-19T14:30:00Z"
}

GET /v1/transactions List Transactions

Retrieve a paginated list of your transactions with optional filtering by date, status, type, and operator.

Query Parameters

Parameter	Type	Default	Description
date_from	string	—	Filter from date (YYYY-MM-DD)
date_to	string	—	Filter to date (YYYY-MM-DD)
status	string	—	`completed`, `failed`, `processing`, `pending`
type	string	—	`collection`, `disbursement`, `manual_c2b`
operator	string	—	Filter by operator code
per_page	integer	20	Results per page (1–100)

Example Request

cURLcurl "https://api.payin.co.tz/api/v1/transactions?date_from=2026-04-01&status=completed&per_page=50" \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx"

Success Response

200 OK

JSON{
  "data": [
    {
      "request_ref": "PAYABCDEF123456",
      "type": "collection",
      "phone": "255714123456",
      "amount": 5000,
      "platform_charge": 250,
      "currency": "TZS",
      "operator": "M-Pesa",
      "status": "completed",
      "created_at": "2026-04-19T10:15:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 50,
    "total": 243
  }
}

GET /v1/transaction/{ref} Transaction Lookup

Look up a single transaction by request_ref, external_ref, or receipt_number.

Success Response

200 OK

JSON{
  "request_ref": "PAYABCDEF123456",
  "external_ref": "INV-001",
  "operator_ref": "12345678",
  "receipt_number": "MPI1234567890",
  "type": "collection",
  "phone": "255714123456",
  "amount": 5000,
  "platform_charge": 250,
  "operator_charge": 75,
  "currency": "TZS",
  "operator": "M-Pesa",
  "status": "completed",
  "callback_status": "sent",
  "created_at": "2026-04-19T10:15:00Z"
}

GET /v1/webhooks/{ref} Webhook Delivery Status

Check the webhook delivery status and attempt history for a specific transaction.

Success Response

200 OK

JSON{
  "request_ref": "PAYABCDEF123456",
  "callback_status": "sent",
  "callback_url": "https://merchant.com/webhook",
  "total_attempts": 2,
  "webhooks": [
    {
      "attempt": 1,
      "http_status": 500,
      "status": "failed",
      "response_time_ms": 5000,
      "sent_at": "2026-04-19T10:20:00Z"
    },
    {
      "attempt": 2,
      "http_status": 200,
      "status": "success",
      "response_time_ms": 250,
      "sent_at": "2026-04-19T10:21:30Z"
    }
  ]
}

GET /v1/operators List Operators

Get the list of active mobile money operators available for collections and disbursements.

Success Response

200 OK

JSON{
  "operators": [
    {
      "name": "M-Pesa",
      "code": "mpesa",
      "currency": "TZS",
      "status": "active",
      "maintenance_mode": false
    },
    {
      "name": "Airtel Money",
      "code": "airtel",
      "currency": "TZS",
      "status": "active",
      "maintenance_mode": false
    },
    {
      "name": "Tigo Pesa",
      "code": "tigopesa",
      "currency": "TZS",
      "status": "active",
      "maintenance_mode": false
    },
    {
      "name": "Halo Pesa",
      "code": "halopesa",
      "currency": "TZS",
      "status": "active",
      "maintenance_mode": false
    }
  ]
}

POST /v1/paylink Create Payment Page

Create a hosted payment page (paylink) with a unique URL. Share the link or display the QR code. When the customer pays, they are automatically redirected to your redirect_url with the payment status and receipt number.

Request Body

Parameter	Type	Required	Description
title	string	Required	Payment title shown to customer. Max 255 chars.
amount	number	Optional	Fixed amount. If omitted, customer enters their own amount.
redirect_url	string	Optional	URL to redirect customer after payment. Receives `?status=completed&ref=RECEIPT&code=PLXXXXXX` query params.
description	string	Optional	Description shown on the payment page. Max 1000 chars.
is_reusable	boolean	Optional	Allow multiple payments. Default: `false` (one-time).
max_uses	integer	Optional	Maximum number of payments allowed (for reusable links).
expires_in	integer	Optional	Expiry in minutes. Max: 525600 (1 year).
customer_name	string	Optional	Pre-fill customer name.
customer_email	string	Optional	Pre-fill customer email.
customer_phone	string	Optional	Pre-fill customer phone.
currency	string	Optional	Currency code. Default: `TZS`

Example Request

cURLcurl -X POST https://api.payin.co.tz/api/v1/paylink \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Order #1234",
    "amount": 25000,
    "redirect_url": "https://myshop.co.tz/order/1234/thankyou",
    "description": "Payment for Order #1234",
    "expires_in": 60
  }'

Success Response

201 Created

JSON{
  "success": true,
  "message": "Paylink created successfully.",
  "paylink": {
    "code": "PLABCD1234",
    "title": "Order #1234",
    "amount": 25000,
    "currency": "TZS",
    "status": "active",
    "redirect_url": "https://myshop.co.tz/order/1234/thankyou",
    "is_reusable": false,
    "expires_at": "2026-04-19T15:00:00Z"
  },
  "pay_url": "https://payin.co.tz/p/PLABCD1234"
}

💡

Share the pay_url with your customer — via email, SMS, WhatsApp, or as a QR code. They open it, enter their phone, confirm the USSD push, and get redirected to your site.

Redirect Flow

After successful payment, the customer is automatically redirected to your redirect_url with these query parameters:

Redirecthttps://myshop.co.tz/order/1234/thankyou?status=completed&ref=MPI1234567890&code=PLABCD1234

Parameter	Description
status	`completed` — payment was successful
ref	Operator receipt number (for verification)
code	Paylink code for matching to your order

⚠️

Always verify server-side. Don't trust the redirect query params alone. Use GET /v1/status/{request_ref} or your webhook callback to confirm the payment before fulfilling the order.

GET /v1/paylinks List Paylinks

Retrieve all paylinks for your account with pagination and optional search.

Query Parameters

Parameter	Type	Default	Description
search	string	—	Search by title, code, or description
per_page	integer	20	Results per page (1–100)

Success Response

200 OK

JSON{
  "data": [
    {
      "code": "PLABCD1234",
      "title": "Order #1234",
      "amount": 25000,
      "currency": "TZS",
      "status": "active",
      "uses_count": 3,
      "redirect_url": "https://myshop.co.tz/thankyou",
      "pay_url": "https://payin.co.tz/p/PLABCD1234",
      "created_at": "2026-04-19T10:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

GET /v1/paylink/{code} Paylink Details

Get details of a specific paylink and its recent payments.

Success Response

200 OK

JSON{
  "paylink": {
    "code": "PLABCD1234",
    "title": "Order #1234",
    "amount": 25000,
    "status": "active",
    "uses_count": 3,
    "redirect_url": "https://myshop.co.tz/thankyou"
  },
  "payments": [
    {
      "request_ref": "PLWXYZ123456",
      "phone": "255714123456",
      "amount": 25000,
      "status": "completed",
      "receipt_number": "MPI1234567890"
    }
  ],
  "pay_url": "https://payin.co.tz/p/PLABCD1234"
}

POST /v1/settlement Settle to Bank Account

Withdraw funds from your collection wallet to a bank account. The settlement goes through admin approval before being processed. You receive webhook callbacks at each stage: settlement.created, settlement.approved / settlement.rejected, settlement.completed.

Request Body

Parameter	Type	Required	Description
amount	number	Required	Amount to settle. Minimum: 1,000.
operator	string	Required	Source wallet operator (e.g. `M-Pesa`, `Tigo Pesa`).
bank_account_id	integer	Required	ID of your saved bank account. Use `GET /v1/bank-accounts` to list them.
description	string	Optional	Description / memo for this settlement.
callback_url	string	Optional	URL to receive webhook callbacks for this settlement at each stage (`settlement.created`, `settlement.approved`, `settlement.rejected`, `settlement.completed`). Overrides your account-level callback URL.

Example Request

cURLcurl -X POST https://api.payin.co.tz/api/v1/settlement \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "operator": "M-Pesa",
    "bank_account_id": 1,
    "description": "Weekly settlement"
  }'

Success Response

201 Created

JSON{
  "success": true,
  "message": "Settlement request created.",
  "settlement": {
    "settlement_ref": "STL-ABCD1234EFGH",
    "amount": 500000,
    "settlement_type": "bank",
    "operator": "M-Pesa",
    "currency": "TZS",
    "status": "pending",
    "bank_name": "CRDB Bank",
    "account_number": "0150123456789",
    "account_name": "My Company Ltd"
  },
  "charges": {
    "platform_charge": "2500.00",
    "operator_charge": "0.00",
    "total_debited": "502500.00"
  },
  "available_balance": "1497500.00"
}

💡

Settlement status flow: pending → approved → completed. If rejected, funds are refunded to your collection wallet. You'll receive webhooks at each step.

POST /v1/settlement/usdt Settle to USDT Wallet

Withdraw funds from your collection wallet to a USDT cryptocurrency wallet. Supports TRC20, ERC20, and BEP20 networks.

Request Body

Parameter	Type	Required	Description
amount	number	Required	Amount to settle (in local currency). Minimum: 1,000.
operator	string	Required	Source wallet operator (e.g. `M-Pesa`).
wallet_address	string	Required	USDT wallet address.
wallet_network	string	Required	Network: `TRC20`, `ERC20`, or `BEP20`.
description	string	Optional	Description / memo.
callback_url	string	Optional	URL to receive status webhooks for this settlement.

Example Request

cURLcurl -X POST https://api.payin.co.tz/api/v1/settlement/usdt \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000000,
    "operator": "M-Pesa",
    "wallet_address": "TXqH5j8k2n...",
    "wallet_network": "TRC20"
  }'

Success Response

201 Created

JSON{
  "success": true,
  "message": "Settlement request created.",
  "settlement": {
    "settlement_ref": "STL-WXYZ9876QRST",
    "amount": 1000000,
    "settlement_type": "usdt",
    "operator": "M-Pesa",
    "currency": "TZS",
    "status": "pending",
    "wallet_address": "TXqH5j8k2n...",
    "wallet_network": "TRC20"
  },
  "charges": { "platform_charge": "5000.00", "total_debited": "1005000.00" }
}

GET /v1/settlements List Settlements

Retrieve all your settlement requests with pagination.

Query Parameters

Parameter	Type	Default	Description
status	string	—	Filter by status: `pending`, `approved`, `rejected`, `completed`
search	string	—	Search by ref, bank name, or account name
per_page	integer	20	Results per page (max 100)

GET /v1/settlement/{ref} Settlement Details

Get details of a settlement by its reference (STL-XXXX).

POST /v1/transfer Transfer: Collection → Disbursement

Move funds from your collection wallet to your disbursement wallet. This allows you to fund payouts from collected payments. Requires admin approval.

Request Body

Parameter	Type	Required	Description
amount	number	Required	Amount to transfer.
operator	string	Required	Operator wallet to transfer within (e.g. `M-Pesa`).
description	string	Optional	Description for the transfer.
callback_url	string	Optional	URL to receive webhooks when transfer is approved or rejected.

Example Request

cURLcurl -X POST https://api.payin.co.tz/api/v1/transfer \
  -H "X-API-Key: pk_live_xxxx" \
  -H "X-API-Secret: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200000,
    "operator": "M-Pesa",
    "description": "Fund disbursement wallet for payroll"
  }'

Success Response

201 Created

JSON{
  "success": true,
  "message": "Transfer request submitted. Pending admin approval.",
  "transfer": {
    "reference": "TRF-ABCDEF123456",
    "operator": "M-Pesa",
    "amount": 200000,
    "status": "pending"
  }
}

💡

Use case: You collect payments from customers (collection wallet fills up). To send payouts, transfer funds to your disbursement wallet first, then call POST /v1/disbursement.

GET /v1/transfers List Transfers

List your internal transfer requests with pagination.

GET /v1/bank-accounts List Bank Accounts

List your saved bank accounts. Use the returned id when creating bank settlements.

Success Response

JSON{
  "bank_accounts": [
    {
      "id": 1,
      "bank_name": "CRDB Bank",
      "account_name": "My Company Ltd",
      "account_number": "0150123456789",
      "swift_code": "CORUTZTZ",
      "is_default": true
    }
  ]
}

Webhook Events

Receive real-time notifications when payments are completed or fail.

When a transaction completes, PayIn sends a POST request to your configured callback URL with the transaction details. You can set a default callback URL in your dashboard, or override it per-request using the callback_url parameter.

Webhook Payload

POST → Your Callback URL{
  "event": "payin.completed",
  "request_ref": "PAYABCDEF123456",
  "external_ref": "INV-001",
  "operator_ref": "12345678",
  "receipt_number": "MPI1234567890",
  "type": "collection",
  "phone": "255714123456",
  "gross_amount": 5000,
  "platform_charge": 250,
  "operator_charge": 75,
  "net_amount": 4750,
  "currency": "TZS",
  "operator": "M-Pesa",
  "status": "completed",
  "timestamp": "2026-04-19T10:20:30Z"
}

Webhook Events

Event	Description
payin.completed	A collection payment was successfully received
payout.completed	A disbursement was successfully sent
settlement.created	Settlement request submitted, funds debited from collection wallet
settlement.approved	Settlement approved by admin, being processed
settlement.rejected	Settlement rejected, funds refunded to collection wallet
settlement.completed	Settlement completed — bank transfer or USDT sent
transfer.approved	Internal transfer approved, funds moved to disbursement wallet
transfer.rejected	Internal transfer rejected

💡

Respond with HTTP 200. Your endpoint must return a 2xx status code within 15 seconds. If we don't receive a success response, we'll retry the webhook.

Signature Verification

Verify that webhooks are genuinely from PayIn using HMAC signatures.

Every webhook request includes two security headers:

Header	Description
X-Payin-Signature	HMAC-SHA256 signature of the payload
X-Payin-Timestamp	Unix timestamp when the webhook was sent

The signature is computed as: HMAC-SHA256(timestamp + "." + body, webhook_secret)

PHP Example

PHP$secret = 'your_webhook_secret';  // From Dashboard Settings
$signature = $_SERVER['HTTP_X_PAYIN_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_PAYIN_TIMESTAMP'] ?? '';
$body = file_get_contents('php://input');

$expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (hash_equals($expected, $signature)) {
    // Webhook is authentic
    $payload = json_decode($body, true);
    // Process the payment...
} else {
    http_response_code(401);
    exit('Invalid signature');
}

Node.js Example

JavaScriptconst crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-payin-signature'];
  const timestamp = req.headers['x-payin-timestamp'];
  const body = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

Python Example

Pythonimport hmac, hashlib

def verify_webhook(body, timestamp, signature, secret):
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{body}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

⚠️

Always verify signatures. Never trust webhook data without verifying the HMAC signature. Find your webhook secret in the Dashboard under Settings.

Error Handling

Understand HTTP status codes and error response formats.

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created (collection, invoice, disbursement)
400	Bad Request	Malformed request or invalid JSON body
401	Unauthorized	Missing or invalid API credentials
403	Forbidden	IP not whitelisted or account inactive
404	Not Found	Resource not found
422	Unprocessable	Validation failed, insufficient balance, operator down
429	Too Many Requests	Rate limit exceeded
502	Bad Gateway	Internal service temporarily unavailable
503	Service Unavailable	System under maintenance

Error Response Format

JSON{
  "message": "Human-readable error description",
  "errors": {
    "phone": ["The phone field is required."],
    "amount": ["The amount must be at least 100."]
  }
}

Payment Statuses

Every payment moves through a lifecycle of statuses.

Status	Description	Final?
`waiting`	Invoice created, waiting for customer to pay	No
`pending`	Request created, queued for operator	No
`processing`	Sent to operator, awaiting confirmation	No
`pending_approval`	Payout awaiting maker-checker approval	No
`completed`	Payment successful — funds transferred	Yes ✓
`failed`	Transaction failed or rejected by operator	Yes ✗
`expired`	Invoice expired without payment	Yes
`rejected`	Invalid amount or failed verification	Yes

✅

Poll or use webhooks. We recommend webhooks for real-time notifications. If you prefer polling, use GET /v1/status/{request_ref} — but avoid polling more than once every 5 seconds.

Rate Limits

API rate limits protect the system and ensure fair usage.

Rate limits are applied per account. When you exceed the limit, you'll receive a 429 Too Many Requests response.

Tier	Requests / Minute	Concurrent
Standard	60	10
Business	300	50
Enterprise	Custom	Custom

Need higher limits? Contact us to discuss enterprise plans.

Supported Operators

Mobile money operators available in Tanzania.

Operator	Code	Prefixes	Collection	Disbursement
M-Pesa (Vodacom)	`mpesa`	255 74/75/76	✓	✓
Airtel Money	`airtel`	255 68/69/78/79	✓	✓
Tigo Pesa (Yas)	`tigopesa`	255 71/65/67	✓	✓
Halo Pesa	`halopesa`	255 62	✓	✓

📡

Operator availability may change. Use GET /v1/operators to check real-time status including maintenance windows.

Build payments with PayIn API

Collect Payments

Send Payouts

Real-time Webhooks

Authentication

Base URL

Idempotency

How It Works

API Endpoints

Request Body

Example Request

Success Response

Error Response

Request Body

Example Request

Success Response

Request Body

Example Request

Success Response — Direct Send

Success Response — Pending Approval

Error — Insufficient Balance

Path Parameters

Success Response

Success Response

Query Parameters

Example Request

Success Response

Success Response

Success Response

Success Response

Request Body

Example Request

Success Response

Redirect Flow

Query Parameters

Success Response

Success Response

Request Body

Example Request

Success Response

Request Body

Example Request

Success Response

Query Parameters

Request Body

Example Request

Success Response

Success Response

Webhook Events

Webhook Payload

Webhook Events

Signature Verification

PHP Example

Node.js Example

Python Example

Error Handling

HTTP Status Codes

Error Response Format

Payment Statuses

Rate Limits

Supported Operators