Create a collection
POST /collections: request an M-Pesa STK push.
Endpoint
POST /api/v1/collections
Required scope: collections:write. Include X-API-Key, Content-Type: application/json, and Idempotency-Key.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
amount_minor | integer | Yes | KES cents, divisible by 100. Between 100 and 25000000; merchant limits also apply. |
currency | string | Yes | KES |
method | string | Yes | stk |
phone | string | Yes | Kenyan M-Pesa mobile number, preferably 2547… or 2541…. Local formats are normalized. |
quoted_fee_minor | integer | No | Expected deposit fee in cents (10% of amount_minor); a mismatch returns 409 MERCHANT_CONFLICT. |
reference | string | No | Your business reference, up to 80 UTF-8 bytes after trimming |
Unknown and duplicate JSON fields are rejected. The reference is not an idempotency key.
Example request
curl --fail-with-body "$DERIPAY_API_BASE_URL/collections" \
-H "X-API-Key: $DERIPAY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-2026-000123" \
--data '{"amount_minor":10000,"currency":"KES","method":"stk","phone":"254712345678","reference":"ORDER-000123"}'Response
New payment: 202 Accepted. Idempotent replay: 200 OK.
{
"data": {
"id": "507f1f77bcf86cd799439011",
"kind": "collection",
"method": "stk",
"status": "queued",
"amount_minor": 10000,
"currency": "KES",
"fee_minor": 1000,
"provider_fee_minor": 0,
"phone": "254712345678",
"reference": "ORDER-000123",
"shortcode": "600000",
"created_at": "2026-09-05T12:00:00Z",
"updated_at": "2026-09-05T12:00:00Z"
},
"replayed": false
}Fees and shortcode are illustrative. Returned values reflect your merchant policy. The response may include an account_reference.
Deposit fee
A 10% fee is deducted from the gross deposit only when payment succeeds. For a KES 100 deposit, the payer approves KES 100, the fee is KES 10, and the merchant receives KES 90 of available balance. Failed or unconfirmed payments do not earn fees. Accepted requests retain their recorded fee on retry.
Confirm payment
Store the payment ID. Read GET payment using collections:read, or receive a signed webhook. Do not fulfil an order on queued, submitted, or unknown.
Only STK push funding is supported. Bank deposits and manual C2B reconciliation are not collection methods in this API.
Errors
See errors for validation, account limits, and permission failures. Reuse the original idempotency key and body after an uncertain network outcome.