POST /api/v1/payment/collection — Collect a Payment

Use this endpoint to initiate a payment from your customer. You specify the payment method, amount, currency, and customer details. Kulmi Pay creates an invoice, triggers the appropriate payment network, and returns an invoice ID and JWT signature you use to track the transaction status. Method: POST
URL: https://app.kulmipay.com/api/v1/payment/collection/

Authentication

Authenticate with a Bearer token or by passing your public_key in the request body. Do not use both at the same time.

Authorization: Bearer <secret_key>

Request

Required fields

string

required

Payment method to use. Currently supported values are M-PESA and PESALINK.

string

required

Transaction currency. One of: KES, USD, EUR, GBP. M-Pesa and PesaLink always settle in KES — if you pass a different currency, Kulmi Pay converts the amount using live exchange rates.

string

required

Payment amount as a decimal string, for example "1500.00". For M-Pesa the minimum is KES 10 and the maximum is KES 150,000.

string

required

Your unique reference for this payment, up to 140 characters. Store this value — you use it to reconcile transactions on your side.

Customer identity

string

Customer phone number. Required for M-Pesa. Use international format, for example 254712345678.

string

Customer email address.

string

Customer first name.

string

Customer last name.

Authentication alternative

string

Your publishable API key. Use this instead of a Bearer token when calling from a client-side environment. Must match the environment (sandbox keys contain test, live keys contain live).

Fee configuration

string

default:"BUSINESS-PAYS"

Who pays the processing fee for mobile money payments. Either BUSINESS-PAYS (fee deducted from your settlement) or CUSTOMER-PAYS (fee added to the customer-facing amount).

string

default:"BUSINESS-PAYS"

Who pays the processing fee for PesaLink bank payments. Either BUSINESS-PAYS or CUSTOMER-PAYS.

Wallet routing

string

The alias ID of a specific wallet to receive the funds. If omitted, funds settle into your default settlement wallet for the transaction currency.

string

Two-letter ISO 3166-1 alpha-2 country code for the customer address.

string

Postal or ZIP code for the billing address.

string

City for the billing address.

string

State or region for the billing address.

string

Street address for billing, up to 140 characters.

Response

object

Details of the invoice created for this payment.

Show invoice properties

string

The invoice alias ID. Use this value with the payment status endpoint to poll for updates.

string

Current state of the invoice. One of PENDING, PROCESSING, COMPLETE, or FAILED. For M-Pesa the state is PENDING while the customer is entering their PIN.

string

The total amount charged, including any fees when CUSTOMER-PAYS is set.

string

The payment method used to process this invoice, for example M-PESA or PESALINK.

string

Your reference string as submitted in the request.

string

A JWT you use with the payment status endpoint to authenticate status checks without a server-side secret key. Store it alongside the invoice ID.

Code examples

curl --request POST \
  --url https://app.kulmipay.com/api/v1/payment/collection/ \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "M-PESA",
    "currency": "KES",
    "amount": "1500.00",
    "api_ref": "order_20240416_001",
    "phone_number": "254712345678",
    "first_name": "Jane",
    "last_name": "Doe",
    "mobile_tarrif": "BUSINESS-PAYS"
  }'

import requests

response = requests.post(
    "https://app.kulmipay.com/api/v1/payment/collection/",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json={
        "method": "M-PESA",
        "currency": "KES",
        "amount": "1500.00",
        "api_ref": "order_20240416_001",
        "phone_number": "254712345678",
        "first_name": "Jane",
        "last_name": "Doe",
        "mobile_tarrif": "BUSINESS-PAYS",
    },
)

data = response.json()
invoice_id = data["invoice"]["id"]
signature = data["signature"]

Example response

{
  "invoice": {
    "id": "GQ7KZ2XPNM",
    "state": "PENDING",
    "value": "1500.00",
    "currency": "KES",
    "provider": "M-PESA",
    "api_ref": "order_20240416_001",
    "created_at": "2024-04-16T08:23:11.042Z"
  },
  "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

For M-Pesa payments, the invoice state starts as PENDING. The customer receives an STK push prompt on their phone and must enter their PIN to complete the payment. Poll the payment status endpoint or use webhooks to detect when the state changes to COMPLETE or FAILED.

Collections

Send Money

Wallet as a Service

Webhooks

Refunds

Bring Your M-Pesa Till/PayBill Number

POST /api/v1/payment/collection — Collect a Payment

Authentication

Request

Required fields

Customer identity

Authentication alternative

Fee configuration

Wallet routing

Response

Code examples

Example response

​Authentication

​Request

​Required fields

​Customer identity

​Authentication alternative

​Fee configuration

​Wallet routing

​Response

​Code examples

​Example response

Authentication

Request

Required fields

Customer identity

Authentication alternative

Fee configuration

Wallet routing

Response

Code examples

Example response