KanaCash Digit9 Send Money API Documentation

Base URLs

Use the correct base URL for sandbox and production environments.

Environment	Base URL
Production	`https://core.kanacash.com/api/v1`
Sandbox	`https://sandbox.kanacash.com/api/v1`

i

All protected requests must include Authorization: Bearer <access_token>. Tokens expire after 1 hour.

Usage Flow

Digit9 should call the APIs in this order for each send-money transaction.

1

Get Token

Exchange client credentials for a bearer token.

2

Create Quote

Validate receiver phone, USD wallet, amount, and hardcoded limits.

3

Send Money

Use the quote ID and external ID to credit the user's USD wallet.

4

Check Status

Check by KanaCash reference ID or by Digit9 external ID.

!

Each quote is single-use and expires after 10 minutes. If a quote expires, create a new quote before sending money.

Limits & Rules

These rules apply to all Digit9 send-money API requests.

Currency is always USD.
Minimum amount is 1 USD.
Maximum amount is 50,000 USD per transaction.
No fee is charged. Response fields fee and totalFeeAmount are 0.
The receiver must be an active KanaCash user with an active USD wallet.
The send API creates a digit9_send_money transaction and credits the receiver wallet ledger.
externalId must be unique per Digit9 client and should be reused for idempotency/status checks.

Token API

Generate a bearer token using Digit9 client credentials.

POST /digit9/auth/token Client credential authentication

Use the client ID and client secret issued by KanaCash.

Request Body

Field	Type	Description
client_idrequired	string uuid	Digit9 API client ID.
client_secretrequired	string	Digit9 API client secret.

Request
{
  "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "client_secret": "issued-client-secret"
}

Response 200
{
  "access_token": "jwt-token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Quote API

Validate the receiver and amount before sending money.

POST /digit9/v1/send/quote Bearer token Create send-money quote

This endpoint checks phone number, receiver status, receiver USD wallet, and the hardcoded amount limit.

Request Body

Field	Type	Description
phonerequired	string	Receiver phone number. Accepted examples: `0881234567`, `231881234567`, `+231881234567`.
amountrequired	number	USD amount. Minimum `1`, maximum `50000`.
currencyoptional	string	Only `USD` is supported. If sent, it must be `USD`.

Request
{
  "phone": "+231881234567",
  "amount": 125.50,
  "currency": "USD"
}

Response 200
{
  "success": true,
  "data": {
    "quoteId": "D9Q-1784283000000-AB12CD34EF56",
    "expiresAt": "2026-07-17T10:15:30.000Z",
    "amount": 125.50,
    "currency": "USD",
    "fee": 0,
    "totalDebit": 125.50,
    "recipient": {
      "name": "Customer Name",
      "phone": "+231881234567",
      "accountStatus": "active",
      "walletId": "231881234567@kcu"
    },
    "limits": {
      "min": 1,
      "max": 50000,
      "currency": "USD"
    }
  }
}

Send API

Credit the receiver's KanaCash USD wallet using a valid quote.

POST /digit9/v1/send Bearer token Execute send-money transaction

The send request consumes the quote and creates a completed KanaCash transaction if the wallet credit succeeds.

Request Body

Field	Type	Description
quoteIdrequired	string	Quote ID returned by the Quote API.
externalIdrequired	string	Digit9 transaction/order reference. Maximum 100 characters.
noteoptional	string	Optional transaction note. Maximum 200 characters.

Request
{
  "quoteId": "D9Q-1784283000000-AB12CD34EF56",
  "externalId": "D9-ORDER-10001",
  "note": "Optional reference"
}

Response 200
{
  "success": true,
  "data": {
    "referenceId": "D9S-1784283090000-AB12CD34",
    "externalId": "D9-ORDER-10001",
    "transactionId": "TXN-ABCDEF1234567890",
    "status": "completed",
    "amount": 125.50,
    "currency": "USD",
    "fee": 0,
    "totalDebit": 125.50,
    "completedAt": "2026-07-17T10:16:04.000Z"
  }
}

OK

On success, KanaCash credits the receiver's USD wallet and writes a digit9_send_money transaction with a wallet ledger credit.

Status API

Check transaction status using either KanaCash reference ID or Digit9 external ID.

GET /digit9/v1/send/{referenceId} Bearer token Status by KanaCash reference

Example
GET /api/v1/digit9/v1/send/D9S-1784283090000-AB12CD34
Authorization: Bearer <access_token>

GET /digit9/v1/send/status?externalId={externalId} Bearer token Status by Digit9 external ID

Example
GET /api/v1/digit9/v1/send/status?externalId=D9-ORDER-10001
Authorization: Bearer <access_token>

Response 200
{
  "success": true,
  "data": {
    "referenceId": "D9S-1784283090000-AB12CD34",
    "externalId": "D9-ORDER-10001",
    "transactionId": "TXN-ABCDEF1234567890",
    "status": "completed",
    "amount": 125.50,
    "currency": "USD",
    "fee": 0,
    "totalDebit": 125.50,
    "recipient": {
      "name": "Customer Name",
      "phone": "+231881234567",
      "customerId": "KC123"
    },
    "createdAt": "2026-07-17T10:16:04.000Z",
    "completedAt": "2026-07-17T10:16:04.000Z"
  }
}

Errors

All errors use the same JSON structure.

Error Format
{
  "success": false,
  "code": "D9_2004",
  "message": "Amount exceeds the maximum of $50,000 USD per transaction."
}

Status	Meaning	Common Cases
400	Request validation failed	Invalid phone, invalid amount, expired quote, unsupported currency
401	Authentication failed	Missing token, expired token, invalid credentials
404	Resource not found	User wallet not found, status transaction not found
409	Duplicate request	A transaction already exists for the same `externalId`