Quickstart

1. Create a key

Open Developers → API keys in the merchant dashboard. Create a server key with these permissions:

• balances:read
• collections:write
• collections:read

Save the key when it is displayed. It cannot be retrieved again. Keep it in your server's secret manager.

2. Configure your server

Set DERIPAY_API_BASE_URL to the complete URL shown in Developers and DERIPAY_API_KEY to the secret you generated. Do not put either a live key or webhook signing secret in a NEXT_PUBLIC_* variable.

3. Check the connection

curl --fail-with-body "$DERIPAY_API_BASE_URL/balance" \
  -H "X-API-Key: $DERIPAY_API_KEY"

Example response:

{
  "data": {
    "currency": "KES",
    "available_minor": 500000,
    "reserved_minor": 0,
    "funding_pending_minor": 0,
    "payout_available_minor": 500000
  }
}

These are illustrative values, not a starting balance.

4. Request an STK push

Use a sandbox account and a phone number approved for that environment. This command initiates a payment request when used against an enabled API.

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"
  }'

10000 means KES 100.00. Amounts must be divisible by 100. Your approved merchant limits may be lower than the API ceiling.

5. Track the outcome

Save data.id from the response with your order. Set PAYMENT_ID to that exact value, then query it with:

curl --fail-with-body "$DERIPAY_API_BASE_URL/collections/$PAYMENT_ID" \
  -H "X-API-Key: $DERIPAY_API_KEY"

Wait for succeeded or failed, or configure webhooks. If a request times out, retry with the same idempotency key and body.

Next steps