Skip to main content
After you initiate a disbursement with requires_approval set to "YES" (or omitted), the file waits in the PREVIEW-AND-APPROVE state. Calling this endpoint confirms the transactions and releases the file for processing. Kulmi Pay then debits your wallet and routes each payment through the selected provider. You must have the change_files permission on your API token to call this endpoint.
If you set requires_approval: "NO" when creating the file, the file is approved automatically and you do not need to call this endpoint.

​
Request

POST https://app.kulmipay.com/api/v1/send-money/approve/
​
Authorization
string
required
Bearer token. Format: Bearer <token>.
​
file_id
string
The file_id returned when you initiated the payout. Use either file_id or tracking_id — you do not need both.
​
tracking_id
string
The tracking_id returned when you initiated the payout. Use as an alternative to file_id.
​
transactions
array
required
An array of transaction IDs confirming which transactions you are approving. The number of IDs must exactly match the number of transactions in the file. This acts as an explicit confirmation that you have reviewed the batch.

​
Response

A successful request returns HTTP 200 with the updated file object.
​
file_id
string
The payment file identifier.
​
tracking_id
string
The file’s tracking UUID.
​
status
string
The updated file state. Moves to PROCESSING after successful approval.
​
total_amount
string
Total amount across all transactions in the file.
​
transactions_count
number
Number of transactions in the file.
​
transactions
array
The full list of transactions with their individual statuses.
​
actual_charges
string
Actual charges applied to the file at time of processing.
​
paid_amount
string
Amount successfully paid out so far.
​
failed_amount
string
Amount from transactions that failed processing.
​
wallet
object
The wallet debited for this file.
​
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 status change.

​
Examples

curl -X POST https://app.kulmipay.com/api/v1/send-money/approve/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "f8a2b1c3-...",
    "transactions": [
      "t1a2b3c4-...",
      "t5d6e7f8-..."
    ]
  }'

​
Sample response

{
  "file_id": "f8a2b1c3-...",
  "tracking_id": "d9e4f5a6-...",
  "status": "PROCESSING",
  "batch_reference": "PAYROLL-JAN-2024",
  "total_amount": "50000.00",
  "transactions_count": 2,
  "actual_charges": "66.00",
  "paid_amount": "0.00",
  "failed_amount": "0.00",
  "wallet": {
    "currency": "KES",
    "wallet_type": "SETTLEMENT"
  },
  "transactions": [
    {
      "transaction_id": "t1a2b3c4-...",
      "status": "PENDING",
      "account": "254712345678",
      "amount": "25000",
      "name": "John Doe"
    },
    {
      "transaction_id": "t5d6e7f8-...",
      "status": "PENDING",
      "account": "254798765432",
      "amount": "25000",
      "name": "Jane Smith"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:31:05Z"
}