Copy page

Payments & collections

Collections are Kwik Nkap's one public, developer-facing product. You create a collection, the customer approves the debit on their handset, and the payment settles to SUCCESS or FAILED. This page explains the concept, the surface, and the lifecycle. The how-to pages cover each step in depth.

What a collection is

A collection is a pull payment. Your server asks Kwik Nkap to debit a specific amount from a customer's Mobile Money wallet (MTN MoMo or Orange Money), and Kwik Nkap pulls the funds into your merchant balance once the customer approves on their phone.

You never touch card numbers or wallet PINs. You supply three things: an amount in XAF, the customer's phone_number, and the operator. The customer authorizes the debit with their Mobile Money PIN on their own handset. Kwik Nkap handles the provider rails behind that.

The public surface

The entire public API is three endpoints on the payment gateway. There is nothing else to learn.

Method	Path	Purpose
POST	/v1/payments	Create a collection (the pull payment)
GET	/v1/payments	List payments (filter by status, page with limit/offset)
GET	/v1/payments/{paymentId}/status	Retrieve a single payment's status

All requests go to the base URL:

Every call authenticates with your API key in the X-API-Key header. The key prefix selects the environment: kn_sk_test_… hits sandbox, kn_sk_live_… hits live. There is one secret key per environment — no publishable key, no Stripe-style key pair. See Authentication for the full model.

The collection lifecycle

A collection moves through a small, predictable set of states.

1. Create. You POST /v1/payments. Kwik Nkap creates the payment as PENDING and triggers a Mobile Money prompt on the customer's phone.
2. Customer approves. The customer sees an MTN MoMo or Orange Money prompt on their handset and enters their Mobile Money PIN to approve the debit.
3. Settle. The provider confirms or declines. The payment becomes SUCCESS (funds pulled, your balance credited net of fees) or FAILED (no money moved).

The POST returns immediately with status: "PENDING" — settlement is asynchronous, so the create response is never the final word.

Code
{
  "id": "knpay_test_9f2c41a7b8e04d6fa1c3e58b7d92f014",
  "status": "PENDING",
  "amount": 25000,
  "currency": "XAF",
  "payment_method": "mobile_money",
  "environment": "SANDBOX",
  "created_at": "2026-06-19T10:24:00Z",
  "internal_transaction_id": "...",
  "phone_number": "670123456",
  "payment_method": "mobile_money"
}

The full status enum (uppercase) is PENDING, SUCCESS, FAILED, and UNSPECIFIED. Payment IDs are prefixed knpay_ in live and knpay_test_ in sandbox.

You learn the outcome in one of three ways:

• Webhooks (preferred). Register an endpoint in the dashboard and receive a signed payment.success or payment.failed event the moment a collection settles. See Webhooks.
• Poll the status endpoint. GET /v1/payments/{paymentId}/status. See Payment status.
• List payments. GET /v1/payments?status=SUCCESS to sweep recent results.

Operators and providers

You name the customer's network in the operator field. Two values are accepted:

operator	Network
MTN	MTN Mobile Money (MoMo)
ORANGE	Orange Money

Which provider carries a given request is selected for you — you do not choose it, and it does not appear in the response. From your side there is only the operator value and the lifecycle above.

Fees

When a collection settles SUCCESS, an application fee is taken before your balance is credited. The fee is computed from your merchant charge tier, which is either a percentage of the amount or a fixed amount, configured for your business.

By default the customer's debit covers the fee. Merchants flagged to absorb fees pay the fee themselves instead of passing it to the customer.

Where to go next

Page	What it covers
Authentication	The X-API-Key header, sandbox vs live keys, environment selection
Create a payment	The POST /v1/payments request body and response, field by field
Payment status	Retrieving and listing payments, the status enum, pagination
Webhooks	payment.success / payment.failed, signing secrets, signature verification
Testing	Sandbox keys, simulated outcomes, guaranteed success/failure test numbers
Interactive reference	Try the three endpoints live against your key