Calling this endpoint creates a payment file containing one or more transactions. The file starts in the PREVIEW-AND-APPROVE state — nothing is sent until you approve it. If you set requires_approval to "NO", Kulmi Pay approves and queues the file immediately after creation.
You must have the add_files permission on your API token to call this endpoint.
Request POST https://app.kulmipay.com/api/v1/send-money/initiation/Bearer token. Format: Bearer <token>.
The currency to disburse. Use "KES" for Kenyan shillings.
The payment provider to route the disbursement through. One of: Value Description MPESA-B2CSend to an M-Pesa mobile wallet MPESA-B2BPay to an M-Pesa PayBill or Till number PESALINKTransfer to a Kenyan bank account P2PTransfer between Kulmi Pay wallets AIRTIMETop up mobile airtime RTGSHigh-value real-time gross settlement
Whether the file requires a manual approval step before processing. Set to "NO" to skip approval and process immediately. Accepted values: "YES", "NO".
The ID of a specific wallet to debit. If omitted, Kulmi Pay uses your default KES settlement wallet. Use this when you have multiple wallets and need to debit a specific one.
Your internal reference for this batch, such as a payroll run ID or invoice number. Returned as-is in status and webhook responses.
A URL to receive webhook notifications when the file or individual transaction statuses change. Must be HTTPS.
List of transactions to include in this file. You can include one or many recipients in a single request. Show Transaction object fields
The recipient’s phone number (M-Pesa, Airtime) or bank account number (PesaLink). Use international format for phone numbers, e.g. 254712345678.
The amount to send. Must be a numeric string, e.g. "1000". Minimum amounts apply per provider:
MPESA-B2C: KES 10PESALINK: KES 100 The recipient’s display name. Used for record-keeping and visible in your Kulmi Pay dashboard.
A description for this payment. Appears on the recipient’s transaction record where the provider supports it.
For MPESA-B2B transactions, specifies how to treat the account. One of "PayBill" or "Till".
Required when account_type is "PayBill". This is the account number or bill reference the recipient uses to identify the payment on the PayBill.
The recipient’s national ID number. Required by some providers for identity verification.
A unique key you generate per transaction to prevent duplicates. If a transaction with the same key has already been submitted by your business, the request returns a 400 error instead of creating a duplicate.
Response A successful request returns HTTP 201 with the newly created file object.
The unique identifier for this payment file. Use this when calling the approve or cancel endpoints.
A UUID you can use to look up this file’s status. Use this with the status endpoint.
The current file state. Starts as PREVIEW-AND-APPROVE when approval is required, or moves to PROCESSING when requires_approval is "NO".
The sum of all transaction amounts in this file, as a string.
The number of transactions in the file.
The list of transactions created for this file. Each transaction includes a transaction_id and its current status. Show Transaction object fields
Unique identifier for this individual transaction.
Current status of the transaction: PENDING, PROCESSING, COMPLETE, or FAILED.
The recipient’s phone number or account number.
The idempotency key submitted with this transaction, if any.
The wallet that will be (or has been) debited for this file.
Estimated transaction charges for this file.
Estimated total deduction including charges.
Your batch reference, as submitted.
ISO 8601 timestamp when the file was created.
Examples curl -X POST https://app.kulmipay.com/api/v1/send-money/initiation/ \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "currency": "KES", "provider": "MPESA-B2C", "requires_approval": "NO", "transactions": [ { "account": "254712345678", "amount": "1000", "name": "John Doe", "narrative": "Salary - January" } ] }'
Sample response { "file_id" : "f8a2b1c3-..." , "tracking_id" : "d9e4f5a6-..." , "status" : "PROCESSING" , "batch_reference" : null , "total_amount" : "1000.00" , "transactions_count" : 1 , "charge_estimate" : "33.00" , "total_amount_estimate" : "1033.00" , "wallet" : { "currency" : "KES" , "wallet_type" : "SETTLEMENT" }, "transactions" : [ { "transaction_id" : "t1a2b3c4-..." , "status" : "PENDING" , "account" : "254712345678" , "amount" : "1000" , "name" : "John Doe" , "narrative" : "Salary - January" , "idempotency_key" : null } ], "created_at" : "2024-01-15T10:30:00Z" , "updated_at" : "2024-01-15T10:30:00Z" }
PesaLink example When sending to a bank account via PesaLink, include bank_code on every transaction. Fetch codes from the bank codes endpoint .
{ "currency" : "KES" , "provider" : "PESALINK" , "transactions" : [ { "account" : "1234567890" , "amount" : "5000" , "name" : "Jane Smith" , "bank_code" : "68" , "narrative" : "Vendor payment" } ] }
M-Pesa B2B PayBill example When paying a PayBill number, include both account_type and account_reference.
{ "currency" : "KES" , "provider" : "MPESA-B2B" , "transactions" : [ { "account" : "400200" , "amount" : "2500" , "account_type" : "PayBill" , "account_reference" : "INV-9901" } ] }
