Skip to main content
Use this endpoint to move funds between two wallets that belong to your account. The transfer is atomic — both the debit and credit are applied in the same transaction, so you will never see funds in transit. Both wallets must be in the same currency and must belong to your business. Method: POST
URL: https://app.kulmipay.com/api/v1/wallets/{wallet_id}/intra_transfer/ Replace {wallet_id} with the wallet_id of the source wallet you want to debit.
The transfer will fail if the source wallet’s available_balance is less than the requested amount. Always check available_balance — not current_balance — before initiating a transfer, as holds and uncleared funds reduce the available amount.

​
Request parameters

​
wallet_id
string
required
The alias ID of the destination wallet. Must belong to your account and share the same currency as the source wallet.
​
amount
string
required
The amount to transfer, as a decimal string. Must be greater than zero, for example "5000.00". Maximum value is 999999.00.
​
narrative
string
required
A description for this transfer. Appears in the transaction statement for both the origin and destination wallets. Alphanumeric and standard punctuation characters only.

​
Code examples

curl --request POST \
  --url https://app.kulmipay.com/api/v1/wallets/wlt_abc123/intra_transfer/ \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "wallet_id": "wlt_def456",
    "amount": "5000.00",
    "narrative": "Payroll funding"
  }'

​
Response

The response returns the updated state of both wallets after the transfer is applied.
​
origin
object
The source wallet after the debit is applied.
​
destination
object
The destination wallet after the credit is applied.

​
Example response

{
  "origin": {
    "wallet_id": "wlt_abc123",
    "label": "Settlement KES",
    "can_disburse": true,
    "currency": "KES",
    "wallet_type": "SETTLEMENT",
    "current_balance": "95000.00",
    "available_balance": "95000.00",
    "updated_at": "2024-04-16T10:15:00Z"
  },
  "destination": {
    "wallet_id": "wlt_def456",
    "label": "Payroll Wallet",
    "can_disburse": true,
    "currency": "KES",
    "wallet_type": "WORKING",
    "current_balance": "55000.00",
    "available_balance": "55000.00",
    "updated_at": "2024-04-16T10:15:00Z"
  }
}