Initiate Payout


Important Note

Please use only Staging Credentials on each API Reference page to test the APIs directly from our Documentation.

API Endpoints

This API allows you to facilitate money transfers to/from the linked virtual bank accounts of your customers from within your application.

API Endpoints

API Specifications

Request Payload

Request ParameterMandatory (M) / Optional (O) / Conditional Mandatory (CM)Description
reference_idMA URN to be passed by the user for each API request. Alphanumeric values are allowed. Special characters such as โ€œ@ # $ % ^ & * ! ; : ~ ` ? = + ) ( apostrophe, double quotesโ€ are not allowed
purpose_messageM1. The narration/remarks that will be displayed in the beneficiaries bank statement.

2. Only Alphanumeric values are allowed, special characters such as โ€œ@ # $ % ^ & * ! ; : ~ ` ? = + ) ( apostrophe, double quotesโ€ are not allowed.

3. Minimum length is 5 characters and Maximum length is 255 characters
from_accountMThe virtual account against which the payout must be performed. The virtual account added must belong to the provider selected.
to_accountCMThe Beneficiary Account to be added.

1. "to_account" is mandatory if the intended transfer type is IMPS/NEFT/RTGS.

2. "ifsc_code" parameter is required for IMPS/NEFT/RTGS transfers.

3. If the transfer type is set as UPI, this parameter is not required.
to_upiCMBeneficiary UPI ID to be passed. 'to_upiโ€™ is mandatory if the intended transfer type is UPI.
1. โ€˜ifscโ€™ parameter is not required for UPI transfer.

2. Special characters such as dot(.) are accepted for values after (@) sign.

3. The UPI ID must follow the NPCI format (Ex: name@bankName or mobilenumber@bankName).

4. If the transfer type is selected as IMPS/NEFT/RTGS, this parameter is not required
transfer_typeMUPI/IMPS/NEFT/RTGS are the available transfer type
transfer_amountMThe Amount to be transferred.Minimum amount is INR 1 (2 Decimal values are allowed Ex: 1.00)
beneficiary_codeCMA URN generated when a beneficiary is created by using Manage Beneficiary API. If the beneficiary_details is passed in the API, then beneficiary_code is not required.
beneficiary_detailsCMAn object that contains 4 parameters that are required to add the details of the beneficiary. If beneficiary_code is passed in the API, then beneficiary_details are not required.
payee_nameMBeneficiary name to be added.
ifsc_codeCMBeneficiary IFSC code to be added.

1. Alphanumeric values are allowed as per the IFSC code assigned to the beneficiary bank.

2. If the transfer type is UPI, this parameter is not required.

3. Maximum length is 11 characters
email_addressOBeneficiary Email Address to be added.
Alphanumeric and special characters are allowed but after (@), only dot(.) is allowed. Sample email format ([email protected])
mobile_numberOMobile numbers have to be strictly 10 digits long and start with one of 9, 8, 7 or 6. Only numeric characters are allowed. Country code is not required.

Response Payload

Response ParameterMandatory (M) / Optional (O) / Conditional Mandatory (CM)Description
status MThe status of the payout transaction. These are the status available
1. Success
2. Failure
3. Pending
decentroTxnIdMA URN generated by Decentro against the API request
transferTypeMThe transfer type of the payout transaction.
UPI,IMPS,NEFT and RTGS are the values propagated
responseCodeMThe response code of the API request
bankReferenceNumberCMThe bank reference number of the transaction. This parameter will be generated when the status is "Success" or "Failure"
beneficiaryNameCMThe name of the beneficiary account holder. This parameter will be generated when the status is "Success"
providerResponseCMThe message on the status of the transaction. This parameter will be generated when the status is "Success" or "Failure"
newBalanceMThe balance of the virtual account after the payout transaction is performed.


Simulation Data

Decentro provides the test data which will simulate various scenarios of the API when a transaction takes place.

Note: This test data is only valid in the Staging environment. Account details passed in the from_account parameter must match the provider secret passed in the headers.

Important: Please refer to the Simulation Data guide here


Error Messages of the API

Please refer Here for all the errors from Initiate Payout API

Click Try It! to start a request and see the response here!