Quickstart

KODIPAY v1 is designed for merchant backends that need a clean server-to-server payment flow. The integration is intentionally simple:

1. obtain your OAuth client credentials
2. request a Bearer token
3. create a payment with a merchant-unique reference
4. receive KODIPAY callbacks for lifecycle updates
5. poll status only when callback delivery is uncertain

1. Prerequisites

Before integrating, make sure you have:

• your client_id
• your client_secret
• a backend endpoint that can receive KODIPAY callbacks
• a strategy for generating a unique reference per payment

In v1, merchants integrate only with KODIPAY. Gateway-specific details remain internal to the platform.

2. Request a Bearer token

KODIPAY uses OAuth2 client_credentials. Your backend must first exchange its credentials for a Bearer token through POST /oauth/token.

curl -X POST https://api-kodipay.kodinet.cd/oauth/token \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

Use the returned token in every merchant API request:

Authorization: Bearer YOUR_ACCESS_TOKEN

3. Create a payment

The main public endpoint is POST /api/v1/payments. At minimum, send:

• payment_method
• amount
• currency
• reference

Add callback_url when you want KODIPAY to notify your backend on payment state changes.

curl -X POST https://api-kodipay.kodinet.cd/api/v1/payments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "payment_method": "mobile_money",
    "amount": "10.00",
    "currency": "USD",
    "reference": "ORDER-2026-0001",
    "walletID": "243891234567",
    "callback_url": "https://merchant.example.com/kodipay/callbacks"
  }'

4. Understand reference and orderNumber

KODIPAY exposes two important identifiers:

• reference: your business identifier, unique per merchant
• orderNumber: the KODIPAY technical identifier used for operational tracking

Use reference for reconciliation in your system. Use orderNumber when you need to track a payment with KODIPAY support tools or status endpoints. KODIPAY order numbers follow a compact 20-character format composed of a date segment, a random segment, and a method/time suffix.

5. Handle callbacks first

Callbacks are the primary integration mechanism.

When a payment changes state, KODIPAY sends an outbound callback to your callback_url. Your backend should:

• verify the request according to your callback handling strategy
• persist the new payment state
• reconcile by reference and orderNumber
• return a 2xx response when the callback was accepted

This is the recommended source of truth for completed, failed, refunded, or expired transitions.

6. Use polling as the fallback

If your callback endpoint was unavailable or you need to confirm the latest state, use the polling endpoint:

curl -X GET https://api-kodipay.kodinet.cd/api/v1/payments/20260415A7K9P2XM1140/status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Polling is a fallback, not the primary integration pattern.

7. Work with the payment lifecycle

At a high level, your integration should be ready to handle:

• pending
• processing
• completed
• failed
• refunded
• expired

Your application should treat completed as the point where the payment is successfully finalized.

8. Use the API Reference for exact contracts

This guide explains the integration journey. For exact request and response schemas, field definitions, and examples, use API Reference.