PalmPesa Payments API v2

How a payment works

• 1
  Your server requests a payment

  Send the amount, the customer's phone number and your callback_url. PalmPesa answers 202 Accepted with an order_id straight away and sends the prompt in the background.

• 2
  The customer approves on their phone

  The customer receives a mobile-money prompt (USSD push) and enters their PIN. Supported wallets include M-Pesa, Mixx by Yas (Tigo Pesa), Airtel Money and HaloPesa.

• 3
  PalmPesa notifies your server

  When the payment reaches a final state, PalmPesa sends a callback to your callback_url. You can also check the status at any time. Only COMPLETED means the money was received.

• 1
  Create a developer account

  Register at palmpesa.co.tz and complete the developer registration and verification.

• 2
  Get your API token

  After your account is approved, generate your API token from the dashboard. Requests made before approval return 403.

• 3
  Prepare a callback endpoint

  Expose a public HTTPS URL on your server that accepts POST requests and answers 200 OK quickly. See Callbacks.

• 4
  Test with a small amount

  Send a real payment of a few hundred TZS to your own phone and confirm your callback handler records it before going live.

Try it in Postman

These are real payments: each one charges amount TZS (1,000 by default) to payer_phone. Don't share or export the collection after adding your token.

Send your API token as a Bearer token in the Authorization header of every request. Always send Accept: application/json so that errors come back as JSON.

Authorization: Bearer YOUR_API_TOKEN
Content-Type:  application/json
Accept:        application/json

Prepend the base URL to every path on this page, for example https://palmpesa.co.tz/api/v2/async/payments.

Starts a mobile-money payment. PalmPesa records the request and answers 202 Accepted straight away, then sends the prompt to the customer's phone in the background. Follow the payment with callbacks or the Payment Status endpoint.

Request Headers

Request Body

Example Request

curl -X POST 'https://palmpesa.co.tz/api/v2/async/payments' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "transaction_id": "ORDER-2026-000123",
    "amount": 10000,
    "currency": "TZS",
    "phone": "255712345678",
    "name": "Juma Hassan",
    "email": "juma@example.com",
    "callback_url": "https://shop.example.com/palmpesa/callback",
    "buyer_remarks": "Payment for order 123"
  }'

Response 202 Accepted

{
  "success": true,
  "message": "Payment accepted.",
  "data": {
    "transaction_id": "ORDER-2026-000123",
    "order_id":       "PALMPESAV2A20261008120000123EFGH5678",
    "status":         "INITIATING",
    "failure_reason": null,
    "amount":         10000,
    "currency":       "TZS",
    "reference":      null,
    "channel":        null,
    "created_at":     "2026-10-08 12:00:00",
    "updated_at":     "2026-10-08 12:00:00",
    "status_url":     "https://palmpesa.co.tz/api/v2/async/payments/PALMPESAV2A20261008120000123EFGH5678"
  }
}

Store transaction_id and order_id with your order. A 202 and INITIATING do not mean the money was received: wait for a payment.completed callback.

Response fields

If the prompt cannot be sent

The request itself still succeeds with 202. If the mobile-money provider refuses the payment or is unavailable, the payment becomes INITIATION_FAILED with a failure_reason, and you receive a payment.initiation_failed callback. Nothing was charged. To try again, send a new request with a new transaction_id.

Retries and duplicate requests

Your account plus transaction_id identify a payment. If your request times out, send the same request again:

• Same transaction_id and same details: 202 Accepted with the original order_id and the payment's current status. The customer is not prompted a second time.
• Same transaction_id with different details: 409 Conflict {"message":"This transaction_id was already used with different payment details."}
• A transaction_id belongs to one payment for good. To charge the customer again after INITIATION_FAILED, CANCELLED, REJECTED or EXPIRED, use a new transaction_id.

Returns the current status of a payment created with Request Payment. Use the status_url from that response, or put the order_id in the path.

Example Request

curl 'https://palmpesa.co.tz/api/v2/async/payments/PALMPESAV2A20261008120000123EFGH5678' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

Response 200 OK

{
  "success": true,
  "data": {
    "transaction_id": "ORDER-2026-000123",
    "order_id":       "PALMPESAV2A20261008120000123EFGH5678",
    "status":         "COMPLETED",
    "failure_reason": null,
    "amount":         10000,
    "currency":       "TZS",
    "reference":      "0289999288",
    "channel":        "TIGOPESATZ",
    "created_at":     "2026-10-08 12:00:00",
    "updated_at":     "2026-10-08 12:01:30",
    "status_url":     "https://palmpesa.co.tz/api/v2/async/payments/PALMPESAV2A20261008120000123EFGH5678"
  }
}

The fields are the same as in the Request Payment response.

Response 404 Not Found

The order does not exist or belongs to another account.

{ "message": "Payment not found.", "order_id": "PALMPESAV2A20261008120000123EFGH5678" }

Failure reasons

When a payment is INITIATION_FAILED, failure_reason explains why:

Expired payments

If the customer hasn't paid within about an hour, the payment becomes EXPIRED and you receive a payment.expired callback. A mobile-money payment request stays open for 30 minutes, and PalmPesa waits a further grace period for late confirmations. Then, if the payment is still INITIATING, PENDING or AMBIGUOUS, PalmPesa checks it with the network one last time:

• Paid: it becomes COMPLETED and you receive payment.completed.
• Cancelled or rejected: it becomes CANCELLED or REJECTED, with the matching callback.
• Anything else: it becomes EXPIRED and you receive a payment.expired callback.

This usually happens 45 to 60 minutes after the payment was created, occasionally later if the network cannot be reached. EXPIRED means no payment was received: do not fulfil the order. To collect the money, create a new payment with a new transaction_id.

When a payment reaches a final status, PalmPesa sends a POST request with a JSON body to the callback_url you supplied. There are no callbacks for INITIATING, PENDING or AMBIGUOUS.

Request headers sent to you

Body

{
  "event":            "payment.completed",
  "event_id":         "82c12c18a92fc6f3bfb61f89bbf0b8f10f7790a3cfe7b0940734eb43eca87eb1",
  "transaction_id":   "ORDER-2026-000123",
  "order_id":         "PALMPESAV2A20261008120000123EFGH5678",
  "selcom_reference": "0289999288",
  "status":           "COMPLETED",
  "amount":           10000,
  "currency":         "TZS",
  "channel":          "TIGOPESATZ",
  "phone":            "255712345678",
  "processed_at":     "2026-10-08T12:01:31+03:00"
}

Events

Every event has the same fields. channel and selcom_reference may be null for payments that did not complete.

Responding and retries

• Answer with any 2xx status within 10 seconds, for example 200 {"received": true}. Do slow work after you respond.
• If your endpoint is unreachable or answers with a non-2xx status, PalmPesa retries delivery (up to 5 attempts in total).
• You can receive the same event more than once. Use event_id as an idempotency key and process each event only once.
• A payment.completed event is never followed by a different final status for the same payment. The reverse can happen: in rare cases payment.completed arrives after payment.expired. Treat it as paid.

Verifying a callback

Before you fulfil an order, check that the callback matches your records:

• transaction_id and order_id belong to an order you created.
• amount and currency equal what you requested.
• You can also confirm with the Payment Status endpoint before fulfilling.

Signed callbacks (optional)

Signing is off unless PalmPesa has issued you a signing secret. Without one, callbacks carry no signature headers; rely on the checks above. With one, every callback also carries X-PalmPesa-Timestamp and X-PalmPesa-Signature, computed over the exact raw request body:

signed_data = X-PalmPesa-Timestamp + "." + raw_request_body
signature   = "sha256=" + hex( HMAC-SHA256(signed_data, YOUR_SIGNING_SECRET) )

Example callback handler (PHP)

<?php
$rawBody = file_get_contents('php://input');
$secret  = getenv('PALMPESA_SIGNING_SECRET'); // only if one was issued to you

if ($secret) {
    $timestamp = $_SERVER['HTTP_X_PALMPESA_TIMESTAMP'] ?? '';
    $received  = $_SERVER['HTTP_X_PALMPESA_SIGNATURE'] ?? '';
    $expected  = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    if ($timestamp === '' || abs(time() - (int) $timestamp) > 300 || !hash_equals($expected, $received)) {
        http_response_code(401);
        exit;
    }
}

$event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);

// 1. Ignore events you have already processed (look up $event['event_id']).
// 2. Match transaction_id, order_id, amount and currency with your order.
// 3. Mark the order paid only when $event['status'] === 'COMPLETED',
//    even if it arrives after a payment.expired event.

http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['received' => true]);

Validation error 422

{
  "message": "The callback URL must be a publicly reachable HTTPS URL.",
  "errors": {
    "callback_url": ["The callback URL must be a publicly reachable HTTPS URL."]
  }
}

Rate limits

When a payment reaches a final status, PalmPesa sends a POST request with a JSON body to the callback_url supplied when initiating payment. No callbacks are sent for INITIATING, PENDING, or AMBIGUOUS statuses.

Request Headers

Example Callback Body — payment.completed

{
  "event": "payment.completed",
  "event_id": "82c12c18a92fc6f3bfb61f89bbf0b8f10f7790a3cfe7b0940734eb43eca87eb1",
  "transaction_id": "ORDER-2026-000123",
  "order_id": "PALMPESAV2A20261008120000123EFGH5678",
  "selcom_reference": "0289999288",
  "status": "COMPLETED",
  "amount": 10000,
  "currency": "TZS",
  "channel": "TIGOPESATZ",
  "phone": "255712345678",
  "processed_at": "2026-10-08T12:01:31+03:00"
}

Events

Our team is available to help you integrate PalmPesa into your platform.

Integration Checklist