Create a transfer
Pay the merchant behind `recipient_merchant_code`. The `Idempotency-Key` header is required: a retry with the same key and the same amount, currency, recipient and reference answers the first transfer and moves nothing more; the same key with any of those different answers 409 `idempotency_key_reused`. Answers 201 `{data: transfer}` where transfer is `{id: "tr_…", object: "transfer", direction: "sent", status: "succeeded", failure_reason: null, amount, currency, mode, simulated, reference, description, metadata, sender: {merchant_code, name}, recipient: {merchant_code, name}, created_at}`. Refused when the money was due to move, the transfer is recorded with `status: "failed"` and answered with `{error, data: transfer}`: 402 `insufficient_funds`, 403 `identity_verification_required`, 409 `wallet_frozen` (a replay gets the same answer; use a new key after fixing it). Refused before anything is recorded, `{error}`: 400 `idempotency_key_required`, 409 `idempotency_key_reused`, 422 `recipient_not_found` / `cannot_pay_self` / `invalid_amount` / `invalid_currency` / `invalid_reference` / `invalid_description` / `invalid_metadata`. Sends `transfer.succeeded` (or `transfer.failed`) to your key's webhook and `transfer.received` to the recipient's.
Parameters
The recipient's six-digit merchant code.
Minor units, 1 to 100,000,000 (1,000,000.00).
ISO-4217 code. Paid from your Business Wallet in this currency.
Your reference (e.g. a settlement run id), max 255. Shown to the recipient.
What it is for, max 255. Shown to the recipient.
Your own key/values. Never shown to the recipient.
curl https://malaleem.com/api/v1/gateway/transfers \
-H "Authorization: Bearer {key_id}:{secret}" \
-H "Idempotency-Key: settle-2026-10-27-elgin" \
-H "Content-Type: application/json" \
-d '{"recipient_merchant_code":"482731","amount":4200,"currency":"CAD",
"reference":"COD-2026-10-27","description":"Cash collected on delivery"}'