What a Payout Integration Actually Covers
A payout API sends money from your funded merchant account to a user's bank account. In India this usually means IMPS, which settles in near real time around the clock, or NEFT, which settles in half-hourly batches. Your platform submits a payout request, receives an acknowledgement and learns the final result later through a callback or a status query. The integration is less about one API call and more about handling a transaction whose outcome arrives asynchronously.
In a white-label setup such as Centabal Pay, the merchant accounts stay in your name. We run the technical channel, the panel and day-to-day operations. That split shapes the checklist. Some items sit with your engineers and some with your finance team. Others stay with you as the account holder regardless of who runs the technology, including licensing, user verification and anti-money-laundering obligations.
Before You Start: Decisions and Inputs to Prepare
Most delays in payout projects come from missing inputs rather than from code. Settle the points below before the first sandbox request. Record who owns each one on your side so questions do not stall while engineers wait for answers from finance, risk or compliance.
- Funding accounts: which merchant accounts fund withdrawals, who tops them up and what happens when the balance runs low.
- Rails and limits: whether you use IMPS, NEFT or both, and the per-transaction and daily limits set by your account and bank.
- Beneficiary data: account number, IFSC and account holder name, and how your app collects and checks them before submission.
- Approval rules: which withdrawals go out automatically and which need manual review by your risk or support team.
- Environments: sandbox and production credentials, server IP addresses to allowlist and a public HTTPS endpoint for callbacks.
- Compliance ownership: who on your side confirms that user verification and record-keeping meet the rules in each country you serve.
- Tenants: for resellers, which merchants get their own tenant in the reseller panel and their own credentials.
Payout API Integration Steps
The order below puts risky work early and avoids rebuilding parts later. Finish and review each step before production credentials are issued.
Idempotency deserves extra attention. Network timeouts happen. A retry without a stable reference is the most common way a platform pays the same user twice. Use the reference as the single key that links your ledger entry, the API request, the callback and the bank reference.
- 1. Obtain sandbox credentials and confirm that request signing works with a simple status or balance call.
- 2. Map your internal withdrawal record to the payout request: one unique reference per payout, plus amount, beneficiary details and the chosen rail.
- 3. Store the reference before sending the request, so a timeout never leads to a second payout for the same withdrawal.
- 4. Handle the immediate response correctly: an accepted request is not a completed payout, so mark it pending.
- 5. Implement the webhook callback and the status query, and use both to move payouts to a final state.
- 6. Record the bank reference, such as the UTR, for every completed payout so support can answer user questions.
- 7. Build daily reconciliation between your ledger, the payout reports and the statement of the funding account.
- 8. Add alerts for low balance, rising failure rates and payouts stuck in pending beyond your threshold.
Webhook Callback Setup for a Payment API
Callbacks tell your system the final status of each payout. Because they carry information that moves money in your ledger, your endpoint must confirm that each message is genuine. It must also behave correctly when the same message arrives twice or arrives out of order.
Log raw callbacks with timestamps. When a user disputes a withdrawal, your support team needs to see exactly what was received and when. Operations will ask for the same log first when investigating an incident, so keep it searchable by payout reference.
- Expose a dedicated HTTPS endpoint and restrict it to the provider's IP addresses where possible.
- Verify the signature on every callback before acting on the payload, and reject anything that fails.
- Respond quickly with a success code and do heavy processing asynchronously, so the sender does not retry unnecessarily.
- Make processing idempotent, so a duplicate callback for a completed payout changes nothing.
- Never move a payout from a final state back to pending. Log conflicting updates and investigate them instead.
- Run a scheduled status query for payouts with no callback after a set time, so a missed message never leaves a user waiting.
Testing Beyond the Happy Path
A sandbox that only returns success proves little. Before go-live, run test cases for the outcomes that cause real support tickets and accounting gaps. Ask which scenarios the sandbox can simulate. Plan small, controlled live tests with your own accounts for the rest.
For each case, check three things: what the user sees in your app, what your ledger shows, and whether funds and withdrawal records agree at the end of the day. Write the expected result down before running the test, so reviewers can sign off without guessing what should have happened.
- Invalid IFSC or account number, and a name mismatch if beneficiary validation is enabled on your setup.
- Insufficient balance in the funding account.
- Request timeout followed by a retry with the same reference.
- Callback delivered twice, delivered late or not delivered at all.
- Payout that stays pending for a long period, for example during bank downtime.
- Payout that fails after being accepted, with the amount returned to your account.
Payment Gateway Go-Live Checklist
Go-live is a controlled switch, not a release you forget about. Use this list as a final gate. Agree the launch window with the operations team in advance so someone is watching the first live payouts on both sides.
If you also collect deposits through a UPI pay-in API in the same channel, run the pay-in and payout go-live checks together. Reconciliation across both flows is where mismatches tend to appear, and finding them in the first days is far easier than at month-end.
- Production credentials stored in a secrets manager, not in code or chat messages.
- Production server IPs allowlisted, and the callback URL registered and tested.
- Funding account topped up, and low-balance alerts tested.
- Withdrawal limits and manual review rules configured as agreed.
- Support team briefed on payout statuses, bank references and what to tell a user whose payout is pending.
- Shared escalation channel with the provider's operations team, with named contacts on both sides.
- First batch of small payouts monitored end to end before full traffic.
- Pause plan in place: a fast way to stop automatic payouts if failure rates rise.
Payment Gateway Integration Timeline: What It Depends On
No single honest number fits every payout integration. The work on the API itself is often the smaller part. The timeline is usually set by factors outside the code, and most of them sit on the client side.
Resellers onboarding several merchants should treat the first merchant as the reference integration. Its tests and documentation can then be reused for each new tenant. For expansion into Pakistan, Bangladesh, Vietnam, the Philippines or Myanmar, expect separate account arrangements and local payout methods with their own beneficiary formats. Run the checklist separately for each country rather than copying the India setup.
- How quickly your merchant and funding accounts are opened and approved.
- Whether your platform already has a withdrawal ledger and approval flow, or needs one built.
- Your internal release cycle and security review process.
- The number of countries and tenants in scope, since each adds configuration and testing.
- Whether your engineers and finance staff are available for testing and reconciliation sign-off.
Mistakes to Avoid
Most payout incidents trace back to a handful of avoidable decisions made during integration. Review this list with both your engineering and finance leads before launch, because several of these gaps only show up once real volume and real user complaints arrive.
- Treating the API response as the final result and marking withdrawals paid immediately.
- Generating a new reference on every retry, which can create duplicate payouts.
- Skipping signature verification on callbacks because the endpoint seems hidden.
- Relying only on callbacks, with no status query fallback.
- Leaving reconciliation to month-end instead of running it daily.
- Assuming the technology provider carries your regulatory obligations. Licensing, user verification and reporting stay with the account holder.
- Launching without a clear escalation path for nights and weekends.