Authenticating with the paylod M-Pesa API

Base URL

Every endpoint is under /functions/v1.

https://paylod.dev/functions/v1

API keys

Authenticate every request with a paylod API key as a bearer token.

Authorization: Bearer mp_live_YOUR_API_KEY

Create API keys on the application's API Keys tab. paylod shows an API key once. The API key encodes two things:

• The application that the request runs against. You therefore never send a shortcode.
• The environment that the request runs in. You therefore never send a ?sandbox=true flag.

Your Daraja consumer key, secret and passkey stay in encrypted storage on the server. They never travel over the network. No endpoint reads them back.

Idempotency

POST /collect accepts an Idempotency-Key header. It also accepts an idempotencyKey field in the body. The idempotency key names one payment attempt. Send the idempotency key, and duplicate deliveries of that attempt collapse into a single payment and a single STK Push. A double-click, a refreshed tab, a redelivered job and an internal network retry are all duplicate deliveries.

// The SDK sends an Idempotency-Key on every collect() — pass one per attempt.
const ack = await paylod.collect({
  amount: 10,
  phone: "254712345678",
  idempotencyKey: attempt.id,
});

curl -X POST https://paylod.dev/functions/v1/collect \
  -H "Authorization: Bearer mp_live_YOUR_API_KEY" \
  -H "Idempotency-Key: att_9f2c1b40" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10, "phone": "254712345678" }'

// The SDK sends an Idempotency-Key on every collect() — pass one per attempt.
$ack = $paylod->collect([
    'amount' => 10,
    'phone' => '254712345678',
    'idempotencyKey' => $attempt->id,
]);

# The SDK sends an Idempotency-Key on every collect() — pass one per attempt.
ack = paylod.collect(
    amount=10,
    phone="254712345678",
    idempotency_key=attempt.id,
)

// The SDK sends an Idempotency-Key on every collect() — pass one per attempt.
CollectAck ack = paylod.collect(
    CollectParams.builder("254712345678", 10)
        .idempotencyKey(attempt.id())
        .build());

// The SDK sends an Idempotency-Key on every collect() — pass one per attempt.
val ack = paylod.collect(
    amount = 10,
    phone = "254712345678",
    idempotencyKey = attempt.id,
)

Make one idempotency key for each attempt, not for each order and not for each product. paylod reserves the idempotency key before it calls Daraja. Ten simultaneous requests with the same key therefore produce exactly one payment and one push. All ten requests return the same paymentId. A key is also spent once you use it. If you key on an order id, a retry of that order replays the failed first attempt. If you key on a product id, every later customer replays the first payment for that product. A retry after a wrong PIN is a new charge and needs a new key.

paylod rejects a reused idempotency key in three cases. All three cases return 409:

Rate limits

paylod limits the rate of POST /collect for each API key and for each phone number. A burst returns 429 Too Many Requests. Back off when you receive a 429. paylod refuses a 429 before the request reaches Daraja. A rate-limited request does not spend the idempotency key. You can therefore retry with the same Idempotency-Key after a short delay.

Errors

paylod returns conventional HTTP status codes.

M-Pesa also has its own result codes: 1032 customer cancelled, 1037 timeout, 2001 wrong PIN. The error reference decodes every one of these codes.