Skip to main content
Use this endpoint to check the state of a payment file and each of its transactions. You can poll this endpoint after initiating or approving a disbursement to confirm whether individual transactions have completed, are still processing, or have failed. You must have the view_files permission on your API token to call this endpoint.

​
Request

POST https://app.kulmipay.com/api/v1/send-money/status/
​
Authorization
string
required
Bearer token. Format: Bearer <token>.
​
tracking_id
string
required
The UUID returned as tracking_id in the initiation response. Use this to identify the file to query.

​
Response

A successful request returns HTTP 200 with the full file object and its transactions.
​
file_id
string
The payment file identifier.
​
tracking_id
string
The file’s tracking UUID, matching what you submitted.
​
status
string
Overall status of the payment file. Common values:
StatusMeaning
PREVIEW-AND-APPROVEFile created, awaiting approval
PROCESSINGFile approved, transactions are being sent
COMPLETEAll transactions finished (with or without failures)
CANCELLEDFile was cancelled before processing
​
total_amount
string
Total value of all transactions in the file.
​
transactions_count
number
Number of transactions in the file.
​
transactions
array
The individual transactions and their statuses.
​
actual_charges
string
Total charges applied to the file.
​
paid_amount
string
Total amount successfully paid out.
​
failed_amount
string
Total amount from failed transactions.
​
wallet
object
The wallet debited for this file.
​
charge_estimate
string
Estimated charges at time of initiation.
​
batch_reference
string
Your batch reference, as submitted.
​
created_at
string
ISO 8601 timestamp when the file was created.
​
updated_at
string
ISO 8601 timestamp of the last file status update.

​
Examples

curl -X POST https://app.kulmipay.com/api/v1/send-money/status/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_id": "d9e4f5a6-1234-5678-abcd-ef0123456789"
  }'

​
Sample response

{
  "file_id": "f8a2b1c3-...",
  "tracking_id": "d9e4f5a6-1234-5678-abcd-ef0123456789",
  "status": "COMPLETE",
  "batch_reference": "PAYROLL-JAN-2024",
  "total_amount": "50000.00",
  "transactions_count": 2,
  "actual_charges": "66.00",
  "paid_amount": "25000.00",
  "failed_amount": "25000.00",
  "wallet": {
    "currency": "KES",
    "wallet_type": "SETTLEMENT"
  },
  "charge_estimate": "66.00",
  "total_amount_estimate": "50066.00",
  "transactions": [
    {
      "transaction_id": "t1a2b3c4-...",
      "status": "COMPLETE",
      "status_code": "0",
      "status_description": "The service request is processed successfully.",
      "account": "254712345678",
      "amount": "25000",
      "name": "John Doe",
      "narrative": "Salary - January",
      "provider_reference": "OKJ1234ABC",
      "provider_account_name": "JOHN DOE",
      "charge": "33.00",
      "currency": "KES",
      "idempotency_key": null,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:32:15Z"
    },
    {
      "transaction_id": "t5d6e7f8-...",
      "status": "FAILED",
      "status_code": "2001",
      "status_description": "The initiator information is invalid.",
      "account": "254798765432",
      "amount": "25000",
      "name": "Jane Smith",
      "narrative": "Salary - January",
      "provider_reference": null,
      "provider_account_name": null,
      "charge": "0.00",
      "currency": "KES",
      "idempotency_key": null,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:32:20Z"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:32:20Z"
}