Introduction

Welcome

The PalmKash API lets you collect payments from and send payouts to mobile money wallets in Rwanda — MTN MoMo and Airtel Money — over one signed, asynchronous REST API.

What is PalmKash

PalmKash is a payment gateway for merchants, agents and POS terminals in Rwanda. Through a single API and dashboard you can charge customers, disburse funds, run palm-biometric checkout, and reconcile every transaction. Money settles in Rwandan francs (RWF).

Collect payments

Charge a customer's mobile wallet and track it to settlement.

Make a payment →

Send payouts

Disburse from your PalmKash balance to any mobile wallet.

Make a withdrawal →

Signed requests

Every call is authenticated and HMAC-SHA256 signed.

How auth works →

Callbacks

Get a POST to your server the moment a transaction resolves.

See callbacks →

How it works

The API is asynchronous. When you start a payment or withdrawal it is accepted as pending and returns a reference; the final completed / failed outcome arrives moments later on your callback URL (or by polling the matching status endpoint).

Initiate — POST the payment or withdrawal with your own client_reference. You get back a reference (a UUID) and an initial status.

Customer acts — for payments, the customer approves the MoMo / Airtel prompt on their handset.

Resolve — PalmKash settles with the operator; the transaction becomes completed or failed.

Notify — PalmKash POSTs the outcome to your callback_url. Match it on reference and fulfil the order.

Authentication

Requests carry three things: your API token (as a Bearer header), your merchant_id in the body, and an HMAC signature across the timestamp and body. Full details — including copy-paste PHP and Node signing code — live in the reference.

The signature protects your requests even if a token leaks. See Signing a request for the exact algorithm.

Your first payment

Once you have a merchant key and API token, a collection is a single POST. The interactive Try it console on the reference page will sign and send this for you.

cURL · make-payment

curl --request POST \
  --url https://dashboard.palmkash.com/api/v1/payments/make-payment \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'X-Merchant-Key: PK_34556ardeaaa' \
  --header 'X-Timestamp: 1699999999' \
  --header 'X-Signature: <hmac-sha256>' \
  --data '{
    "merchant_id": "PK_34556ardeaaa",
    "phone_number": "250789777777",
    "amount": 10000,
    "currency": "RWF",
    "client_reference": "INV-123456",
    "callback_url": "https://shop.com/callback"
  }'

Going live

Before you move real money, confirm a few things:

Your callback_url is reachable over HTTPS and returns 200 quickly.
You store the returned reference against your order and treat callbacks as idempotent.
Your signing produces the exact bytes you send (see the reference note on canonical JSON).
You handle the pending → completed / failed lifecycle rather than assuming instant success.

Ready for endpoint-level detail? Head to the API Reference, or learn the dashboard in Dashboard Docs.