Payments

Create a payment intent

POST/v1/payment_intents

mpesa_stk sends an STK push to phone within 2 seconds; card returns a Paystack checkout_url. The intent stays pending until the provider confirms; a timeout is never a failure.

Parameters

Idempotency-Keystringin headerrequired: Unique per logical request, kept 24 hours. A retry with the same key and body replays the first response.

Body

amountintegerrequired: Integer minor units (cents). KSh 1,250.00 is 125000. At least 100.
currency"KES"required
methodstringrequired: One of mpesa_stk, card.
phonestring: Kenyan mobile number; 07…, 2547… and +2547… are accepted. Required for mpesa_stk.
customer_emailstring (email): Required for card.
referencestringrequired: Your reference, shown to the payer and used for reconciliation.
descriptionstring
metadataobject

Responses

200Replay of an identical request within 24 h
201Intent created with its first attempt
400Invalid request
401Missing, invalid or revoked API key
403business_initiation_disabled
409idempotency_conflict
422no_healthy_connection or capability_unsupported
429More than 100 requests in this minute for this keyRetry-After
500Internal error

Error bodies and every code are listed under Errors; limits under Rate limits and Idempotency.

curl -X POST http://localhost:3000/api/v1/payment_intents \ -H "Authorization: Bearer $DCP_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"amount":125000,"currency":"KES","method":"mpesa_stk","phone":"+254708374149","reference":"ORDER-1001"}'

{ "id": "pi_01JB8Q4Z2N5V7K3M9P6R0T1W8X", "object": "payment_intent", "livemode": false, "status": "pending", "amount": 125000, "currency": "KES", "method": "mpesa_stk", "reference": "ORDER-1001", "description": "description", "phone": "+254708374149", "customer_email": "amina@example.co.ke", "metadata": {}, "provider_code": "provider code", "receipt": "receipt", "checkout_url": "checkout url", "reconciliation_status": "matched_exact", "created_at": "2026-10-22T09:30:00.000Z", "succeeded_at": "2026-10-22T09:30:00.000Z", "attempts": [ { "id": "pa_01JB8Q4Z2N5V7K3M9P6R0T1W8X", "object": "payment_attempt", "provider": "daraja", "status": "pending", "provider_ref": "provider ref", "failure_code": "failure code", "created_at": "2026-10-22T09:30:00.000Z", "finished_at": "2026-10-22T09:30:00.000Z" } ] }