This document contains some best practices you should follow when integrating RazorpayX with your system.
Before we list out the best practices, you should know that we support 2 types of API calls to make payouts.
- Normal Payout API
- Composite Payout API
In this flow, you have to make separate API calls to:
- Create a contact. You receive a contact id in the response.
- Create a fund account using the contact id. Fund account can be a bank account or a UPI ID.
- Create a payout using the fund account id.
The Composite Payout API allows you to create a contact, fund account and payout in a single API call.
After creation, a payout can remain in the processing state for T+2 working days, where T is the transaction time. From the processing state, a payout can move to the processed or reversed state.
It is possible for a payout in the processed state to move to the reversed state. This can happen in a maximum time of T+3 working days. This happens in very rare occasions.
- API calls are asynchronous. We DO NOT suggest using the Fetch Payout API to check the status of the payouts.
- We recommend subscribing to our webhooks instead.
- Webhooks are triggered whenever there is a change in the status of the payout. You can update your database using the webhook payload.
Your customer might have accidentally shared incorrect account details with you. You might use these details to create a fund account and then make a payout to it. Even though the account number is wrong, if the account exists, the payout will be processed and the amount will be credited to the account.
To avoid such scenarios, we recommend validating the fund account before making a payout to the account.
Read more: Fund account validation
We recommend you enable workflows on your account. This allows you to set up a maker-checker process. You can have 1 person create a payout and save it as a draft. Next, you can have someone from the financial team check the payouts before they are processed.
Read more: RazorpayX Maker-Checker
We recommend you set low balance alerts on your RazorpayX account. Once set, we will notify you when your RazorpayX account balance drops below the set threshold.
Read more: Low balance alerts
If your RazorpayX account does not have sufficient funds to process a payout, the payout fails.
To avoid such scenarios, we recommend passing
queue_if_low_balance: true in the Payout API request. When you pass the parameter, if you do not have sufficient balance to process the payout, the payout is queued instead of failing.
The queued payouts are automatically processed when you add funds to your RazorpayX account.
Read more: Queued Payouts
If you are not PCI DSS compliant, you should not process your contact's card details in your backend.
Use the public Fund Account API to create a fund account with type card. The public Fund Account API only needs your <KEY_ID>. DO NOT send your <KEY_SECRET> when making this API call as you will be exposing this on your website.
Read more: Payouts to Cards
We recommend you ensure your payout API requests are idempotent. Idempotency allows you to safely retry or send the same request multiple times without fear of performing the same action more than once.
For example, you made a request, but were unable to read/save the response sent by Razorpay. In such cases, you make another payout request. Assuming the first request was successful, your account will be debited twice. Making your payout requests idempotent helps you avoid such scenarios.
To make a request idempotent, all you have to do is add the header
X-Payout-Idempotency to the request and pass an idempotency key against it. When a payout request is idempotent, you can make the same call multiple times, but the amount will be deducted only once. If a duplicate request is found with the same idempotency key, we return the payout's latest state.
Read more: RazorpayX Idempotency
As an extra precaution, you can get your IP address whitelisted. This means only API calls made from the whitelisted IP will be processed by us.
Contact RazorpayX Support from your Dashboard to get your IP whitelisted.
Whitelisting your IP will affect both Razorpay Payment Gateway and RazorpayX API calls.