AI-Powered Financial InfrastructureGlobal PaymentsSecure & Trusted
Developers · Payout APIsPayout APIs: send money from your own systems — exactly once.
Pay vendors, staff, sellers and partners to a bank account or UPI ID with a single call, follow every payout by webhook, and retry safely with an idempotency key.
- Bank accounts
- UPI IDs
- Single or bulk
- Idempotent
$payout = $client->payouts->create([
'beneficiary_id' => 'bene_3Kd91',
'amount' => 250000, // in paise
'mode' => 'upi',
], [
'idempotency_key' => 'payout-run-2026-08-29-0417',
]);
echo $payout->status;POST /payouts, in three parameters.
Send money to a beneficiary's bank account or UPI ID.
| Parameter | Meaning |
|---|---|
beneficiary_id | The beneficiary receiving the funds |
amount | Amount in paise — 250000 is ₹2,500.00 |
mode | Transfer mode; the published example uses upi. Bank transfer is also supported. |
A payout object; the examples read its status. The idempotency key travels as an Idempotency-Key header in cURL, or as an option in the SDK. For parameters beyond the published example, ask developer support.
From beneficiary to payout report.
- 01Save the beneficiary
Store the recipient's bank account or UPI ID once, and reuse its beneficiary id.
- 02Create the payout
Call the Payout API with the beneficiary, the amount in paise, the mode and an idempotency key.
- 03Read the status
The response carries the payout's status; it moves from initiated to completed.
- 04Handle the webhook
A payout event arrives as the status changes — mark the vendor, employee or partner as paid here.
- 05Report
Completed payouts appear in your payout report for reconciliation.
Why every payout needs a key.
A payout that times out might have gone through. Without a key, retrying could pay twice; with the same key, the retry returns the original payout instead.
- Make the key deterministic
- Build it from your own run and beneficiary — for example payout-run-2026-08-29-0417 — so a re-run produces the same key.
- One key per payout
- Never reuse a key for a different payout; it identifies exactly one transfer.
curl https://api.paynancial.com/v1/payouts \
-u YOUR_API_KEY: \
-H "Idempotency-Key: payout-run-2026-08-29-0417" \
-d beneficiary_id=bene_3Kd91 \
-d amount=250000 \
-d mode=upiWhat to do when a payout is refused.
Errors come back with a structured code, so your code can decide what to do without parsing text.
| Code | Means | What to do |
|---|---|---|
insufficient_funds | The balance available is not enough for the requested payout or refund. | Do not retry automatically; top up or reduce the amount, then try again. |
invalid_method | The payment method or mode in the request is not valid for this call. | Correct the request. Retrying the same request will fail the same way. |
rate_limited | Too many requests in a short period. | Back off and retry later with the same idempotency key. |
Paying many beneficiaries at once.
Payouts supports bulk: a batch of transfers submitted in a single request, with every payout in the batch tracked individually and a clear reason for any that fail. The published example shows a single payout; ask developer support for the batch request format.
Whether you send one request per payout or a batch, give each payout its own idempotency key, and handle failures payout by payout — the rest of the batch has already moved. See Bulk Payouts.
Payout API questions.
What is the Paynancial Payout API?
The resource that sends money to a beneficiary's bank account or UPI ID: POST /payouts with the beneficiary, the amount in paise and the mode, plus an idempotency key.
Why do payouts need an idempotency key?
A payout that times out might have gone through. Retrying with the same idempotency key returns the original payout instead of paying twice.
What happens if a payout fails?
You get a structured error code such as insufficient_funds, invalid_method or rate_limited, and a failed payout comes with a clear reason. Fix the cause, then retry.
Can I send payouts in bulk through the API?
Yes — Payouts supports submitting a batch of transfers in a single request, with each payout tracked individually. Ask developer support for the batch request format.
Send a test payout in the Sandbox.
Request a sandbox key and try a payout with no real money involved.