Direct Payments
Collect a payment and check its status
List and filter payments
Retrieves a paginated list of payments with optional filtering capabilities. Perfect for building dashboards, reports, and reconciliation tools.
Filtering Options:
- Status: Filter by payment status (PENDING, SUCCESS, FAILED, etc.)
- Pagination: Control result set size and navigation via limit and offset
Pagination:
- Default limit: 10 items per page
- Maximum limit: 100 items per page
- Use offset for pagination navigation
Use Cases:
- Build payment dashboards
- Generate financial reports
- Perform reconciliation tasks
- Monitor payment trends
- Customer payment history
- Failed payment analysis
Performance Notes:
- Results are ordered by creation date (newest first)
- Consider using specific filters to improve response times
query Parameters
statusFilter by payment status
limitNumber of items per page (1-100)
offsetNumber of items to skip
List and filter payments › Responses
Create a new payment transaction
Charges a customer by prompting them on their phone.
The 201 is an acknowledgement, not a result. The payment is created as PENDING, the customer receives a USSD prompt, and the outcome arrives seconds to minutes later. Learn the result by receiving the payment.success / payment.failed webhook, or by polling GET /payments/{paymentId}/status.
Send an Idempotency-Key. Networks retry; without one a retried request charges the customer twice.
Payment IDs look like knpay_<32 hex chars> in live and knpay_test_<32 hex chars> in sandbox. They are opaque — do not parse them.
Say how they pay. payment_method is mobile_money (MTN Mobile Money) or orange_money (Orange Money). It replaced operator, which could only ever describe a wallet — cards and other instruments will arrive as values here rather than in a second field.
Failures carry failure_code and failure_message from a provider-agnostic vocabulary, so the same handling works as we add operators.
Headers
Idempotency-KeyA unique key you generate per operation (a UUID is ideal). If a request with the same key has already completed, its original response is replayed instead of the operation running twice, and the response carries Idempotent-Replayed: true. Keys are remembered for 24 hours and are scoped to your business. Reusing a key with a different body is an error.
Create a new payment transaction › Request Body
amountAmount to collect, in whole XAF. Minimum 100.
phone_numberCustomer's phone number in international format. The prompt is sent to this handset.
payment_methodHow the customer pays. mobile_money is MTN Mobile Money, orange_money is Orange Money. More instruments will be added here rather than in a second field.
Create a new payment transaction › Responses
Retrieve payment status
Retrieves the current status of a specific payment using its unique identifier (payment ID).
Payment Statuses:
PENDING: Payment is being processedSUCCESS: Payment completed successfullyFAILED: Payment failed or was declined
Use Cases:
- Check payment status after creation
- Poll for status before fulfilling orders
- Verify payment completion for customer support
- Reconcile with webhook notifications
Response: Returns the payment's current status and associated identifiers. Full payment details can be correlated with webhook events or list payments.
path Parameters
paymentIdUnique payment identifier (e.g. knpay_test_9f2c41a7b8e04d6fa1c3e58b7d92f014)