Initiate a payment for an organization. The behavior depends on the method field in the request body. For mail subscriptions, the amount is always calculated server-side from the plan, seat count, and billing cycle — any client-provided amount is ignored.
Endpoint Bearer token. Format: Bearer <token>
The ID of the organization making the payment.
Request body Payment method to use. One of card, mobile_money, or saved_method.
Amount in KES (whole units, not cents). Required for non-subscription payments. Ignored for mail_subscription — the server enforces the price.
Kenyan M-Pesa phone number. Required when method is mobile_money. Only M-Pesa numbers are supported; Airtel numbers are rejected.
ID of a saved payment method. Required when method is saved_method.
Attach structured context to the payment. Required for mail subscription purchases. Set to mail_subscription to purchase a mailbox plan.
Plan tier. One of core, growth, or scale.
Number of mailboxes to purchase.
Billing frequency. One of monthly or yearly. Yearly billing applies a 2-month discount (10 months billed).
Pricing reference Prices are in KES per seat per month. The yearly total is 10× the monthly total.
Seats Core Growth Scale 1–50 100 150 220 51–500 80 130 200 501–5,000 60 110 180 5,001+ 40 90 160
Scenarios New card checkout
M-Pesa STK push
Saved payment method
Mail subscription
Redirects the user to a Paystack-hosted card checkout page. Use the returned checkoutUrl to complete payment. curl --request POST \ --url https://api.nyotaimara.com/v1/billing/pay \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: <org-id>' \ --header 'Content-Type: application/json' \ --data '{"method": "card", "amount": 5000}'
{ "success" : true , "checkoutUrl" : "https://checkout.paystack.com/..." , "reference" : "NI-550e8400-e29b-41d4-a716-446655440000" }
Sends an STK push prompt to the provided Kenyan M-Pesa number. The user enters their PIN on their phone to complete the payment. curl --request POST \ --url https://api.nyotaimara.com/v1/billing/pay \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: <org-id>' \ --header 'Content-Type: application/json' \ --data '{"method": "mobile_money", "phone": "0712345678", "amount": 5000}'
{ "success" : true , "message" : "STK Push sent! Please check your phone to enter your M-Pesa PIN." , "reference" : "NI-550e8400-e29b-41d4-a716-446655440000" }
Charges a previously saved card or triggers an STK push to a previously saved M-Pesa number — no redirect or manual entry required. curl --request POST \ --url https://api.nyotaimara.com/v1/billing/pay \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: <org-id>' \ --header 'Content-Type: application/json' \ --data '{"method": "saved_method", "paymentMethodId": "pm_01j9k2x...", "amount": 5000}'
{ "success" : true , "message" : "Payment processed successfully!" }
Purchases a mailbox plan. Set amount to 0 — the server calculates the final charge from metadata. Use method: "card" to open a checkout page. curl --request POST \ --url https://api.nyotaimara.com/v1/billing/pay \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: <org-id>' \ --header 'Content-Type: application/json' \ --data '{ "method": "card", "amount": 0, "metadata": { "type": "mail_subscription", "plan": "core", "seats": 10, "billingCycle": "monthly" } }'
{ "success" : true , "checkoutUrl" : "https://checkout.paystack.com/..." , "reference" : "NI-550e8400-e29b-41d4-a716-446655440000" }
Response fields true on a successful request.
Paystack-hosted checkout URL. Present for card method payments.
Unique payment reference in the format NI-<uuid>. Use this to reconcile the transaction.
Human-readable status message. Present for mobile_money and saved_method payments.
