KanaCash Partner API

The KanaCash Partner API allows approved partners to integrate KanaCash wallet services into their own platforms and applications. Once onboarded, your platform can perform two core operations:

How It Works

Your platform authenticates using a client ID and client secret provided by KanaCash. These credentials are exchanged for a short-lived access token, which you include in all subsequent API requests.

Your partner account holds a separate balance in LRD and USD. For disbursements, your balance must be funded in advance. Contact KanaCash operations to top up your partner balance via bank transfer.

Download the Postman collection to get all endpoints pre-configured with the correct URLs, request bodies, and automatic token handling. No manual setup required.

Setup in 3 steps

All Partner API endpoints are prefixed with the base URL for the environment you are targeting. Never use plain HTTP as requests will be rejected.

Example full URL (production):

POST  https://core.kanacash.com/api/v1/partner/v1/collection/request

Example full URL (sandbox):

POST  https://sandbox.kanacash.com/api/v1/partner/v1/collection/request

The KanaCash Partner API uses OAuth 2.0 Client Credentials. You exchange your client_id and client_secret for a Bearer token, then include that token in every API request.

Step 1 — Get an access token

Call the token endpoint with your credentials. You will receive an access token that is valid for 1 hour.

POST /api/v1/partner/auth/token
Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2 — Include the token in every request

Add the access token to the Authorization header of all subsequent requests.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token expiry

Tokens expire after 1 hour (expires_in: 3600). Your application should request a new token before the current one expires to avoid interruptions. A 401 response with code TOKEN_EXPIRED means you need to re-authenticate.

All request bodies must be JSON. All responses are JSON.

Successful response structure

{
  "success": true,
  "data": { /* response payload */ }
}

Error response structure

{
  "success": false,
  "message": "Human-readable description of the error",
  "code": "MACHINE_READABLE_CODE"
}

Each partner account has a default rate limit of 60 requests per minute. If your integration requires a higher limit, contact KanaCash to request an increase.

When you exceed the rate limit, the API returns HTTP 429 Too Many Requests. Your application should implement exponential backoff and retry after a short delay.

When the status of a collection or disbursement changes, KanaCash sends an HTTP POST request to your registered webhook URL. Webhooks are the recommended way to receive updates rather than polling the status endpoint.

Registering a Webhook URL

Contact KanaCash to register your webhook URL when setting up your partner account. Your endpoint must:

• Accept HTTP POST requests
• Respond with HTTP 200 within 10 seconds
• Be accessible over HTTPS

Webhook Payload

{
  "event": "collection.completed",
  "referenceId": "PKC-1751117862345-A1B2C3D4",
  "externalId": "ORDER-2026-00123",
  "amount": 500.00,
  "currency": "LRD",
  "fee": 5.00,
  "status": "completed",
  "transactionId": "TXN-A1B2C3D4E5F67890",
  "timestamp": "2026-06-28T12:15:43.000Z"
}

Webhook Event Types

Verifying Webhook Signatures

Every webhook includes an X-KanaCash-Signature header. This is an HMAC-SHA256 signature of the request body, computed using your webhook secret. Always verify this signature before processing the webhook.

X-KanaCash-Partner-Id: your-client-id
X-KanaCash-Signature: sha256=a4b7c2d1e8f3...
Content-Type: application/json

Signature Verification (Node.js example)

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, webhookSecret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Policy

If your endpoint does not respond with HTTP 200 within 10 seconds, KanaCash retries the webhook up to 3 times with increasing delays. After 3 failed attempts, no further retries are made. You can always check the current status using the status endpoints.

All error responses follow this format:

{
  "success": false,
  "code": "PKC_3001",
  "message": "No KanaCash account found for this phone number."
}

PKC_1XXX — Authentication

PKC_2XXX — Request Validation

PKC_3XXX — User / Account

PKC_4XXX — Balance / Limits

PKC_5XXX — Quote

PKC_6XXX — Transaction

PKC_7XXX — System / Rate

KanaCash applies per-user transaction limits to partner collection and disbursement. These limits are configured by KanaCash administrators per user tier (Basic, Silver, Gold, Platinum) and control how much a single user can have collected from or disbursed to their wallet by all partners combined.

How limits work

As of this version, all limit checks run at quote time (collection/quote and disbursement/quote), not just the per-transaction cap. A quote that succeeds means the transaction is expected to clear these checks at confirm time too.

Collection Request Statuses

Transaction Statuses