Payments

The Payments API allows you to collect money from customers through various channels.

Payment Types

Mobile Money

Airtel Money, M-Pesa, Tigo Pesa, Halotel. Customer receives USSD push to authorize.

Card Payments

Visa, Mastercard, local debit cards. Customer redirected to secure checkout.

Dynamic QR

QR code customers scan with their mobile money app to pay.

Payment Flow

1. Create Payment Intent
   └── POST /v1/payments

2. Customer Completes Payment
   └── Mobile: USSD push or prompt
   └── Card: Redirect to checkout page
   └── QR: Scan and pay

3. Receive Webhook Notification
   └── payment.completed or payment.failed

4. Verify Payment Status (optional)
   └── GET /v1/payments/{reference}

API Endpoints

Endpoint	Method	Auth	Description
`/v1/payments`	POST	API Key	Create payment intent
`/v1/payments/{reference}`	GET	None	Get payment status

Payment Status

Status	Description
`pending`	Payment created, awaiting customer action
`completed`	Payment successful, funds received
`failed`	Payment failed (declined, timeout, etc.)
`voided`	Payment cancelled before completion
`expired`	Payment expired (default: 1 hour timeout)

Idempotency

Use the Idempotency-Key header to safely retry requests without creating duplicate payments.

POST /v1/payments
Idempotency-Key: order-12345-attempt-1

Keys are valid for 24 hours
Same key + same request body = returns cached response
Same key + different body = returns error