post https://in.staging.decentro.tech/v3/core_banking/money_transfer/initiate
Important Note
Please use only Staging Credentials on each API Reference page to test the APIs directly from our Documentation.
API Endpoints
| Environment | Endpoint |
|---|---|
| Staging / Sandbox | https://in.staging.decentro.tech/v3/core_banking/money_transfer/initiate |
| Production | https://in.decentro.tech/v3/core_banking/money_transfer/initiate |
Overview
This API allows you to facilitate money transfers to/from the linked virtual bank accounts or the consumer URN from within your application.
Flow
Below is the flow for using the Initiate Payout flow through Decentro
- The platform can use the provided "Consumer URN" or the "Virtual Account" to initiate a payout
- Consumer URN: Decentro will select the suitable provider and virtual account, and perform the payout
- From account: The Platform is specifying that a particular virtual account must be used for payout.
- The platform can provide the transfer type, amount, and beneficiary details. Once these details are provided, the payout can be initiated.
- The payout is an asynchronous process, wherein the request for the payout is initiated and pending for processing. This applies to NEFT and RTGS. IMPS and UPI provide synchronous responses.
- Decentro will trigger Transaction Status Callback: when the transaction reaches its final status.
- Decentro will trigger Account Balance Callback: whenever there is a debit/credit from the virtual account.
- If the platform wants to check the status of any transaction. Get Transaction Status: can be used to check the status of any transaction on demand. Decentro recommends using this functionality as a fallback mechanism to check the status of the transaction.
Key Points
Below are the key points about the initiate payout workflow.
- If the consumer URN is used by the platform, the provider selection will take place from the most suitable provider at the time of the request, removing the dependency on the platform to implement a provider selection rule. The platform must ensure that all the virtual accounts across a consumer URN have sufficient funds to be processed.
- The "api_status" must not be confused with the "transaction_status". Even if the "api_status" is success, it does not mean the actual "transaction_status" is success. Please ensure this is handled during the implementation of the payout API to your platform.
- Decentro recommends platforms to handle the response of all possible transaction status. For details on the statuses, please refer to this section here.
API Specifications
Request Payload
| Request Parameter | Mandatory (M) / Optional (O) / Conditional Mandatory (CM) | Description |
|---|---|---|
| reference_id | M | A 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_message | M | 1. 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 35 characters |
| consumer_urn | M | A URN created for a consumer must be passed here. |
| from_account | O | The virtual account against which the payout must be performed. This is an optional field and is only to be used if the platform wants to perform a payout from a specific virtual account. |
| transfer_type | M | UPI/IMPS/NEFT/RTGS are the available transfer type |
| transfer_amount | M | The Amount to be transferred.Minimum amount is INR 1 (2 Decimal values are allowed Ex: 1.00) |
| beneficiary_details | CM | An object that contains all the beneficiary details to which the platform will perform payout to. |
| to_account | CM | The 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_upi | CM | Beneficiary 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 |
| payee_name | M | Beneficiary name to be added. Note: Decentro sanitises special characters for passing through banking APIs validations. Please ensure no special characters are passed, only Alphabetical values are passed. |
| ifsc_code | CM | Beneficiary 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_address | O | Beneficiary Email Address to be added. Alphanumeric and special characters are allowed but after (@), only dot(.) is allowed. Sample email format ([email protected]) |
| mobile_number | O | Mobile 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 Parameter | Mandatory (M) / Optional (O) / Conditional Mandatory (CM) | Description |
|---|---|---|
| decentro_txn_id | M | A URN generated by Decentro against the API request |
| api_status | M | The status of the payout API request. Decentro recommends not using this parameter to mark the transaction status Here are the values that will be propagated. 1. Success 2. Failure |
| message | M | The message of the API will be propagated here. This message is not related to the transaction message. These messages are based on the actions of the API. |
| response_key | M | Response key documenting the status of the API hit and various errors as mentioned below. |
| data | CM | The object that contains the details of the transaction. This object will not be present if there is an API failure. |
| transaction_status | M | The status of the payout transactions. These are the following values available. For more refer, please refer to this section here 1. Success 2. Failure 3. Pending 4. Unknown |
| transfer_type | M | The transfer type of the payout transaction. UPI, IMPS, NEFT, and RTGS are the values propagated |
| bank_reference_number | CM | The bank reference number of the transaction. This parameter will be generated when the status is "Success" or "Failure." |
| beneficiary_name | CM | The name of the beneficiary account holder. This parameter will be generated when the status is "Success." |
| transaction_status_description | CM | The message on the status of the transaction. This parameter will be generated when the status is "Success" or "Failure." |
Payout Response Keys
| Response Key | Message |
|---|---|
| success_transaction_request_initiated | Request was successfully initiated |
| error_amount_below_minimum | Transfer amount cannot be less than zero. Enter a correct value. |
| error_duplicate_reference_id | The provided reference_id has already been used for another transaction. Kindly choose a different value. |
| error_amount_exceeded_imps | Your amount exceeds the maximum amount that can be sent via IMPS. Please note that the amount should be <= INR 500000 per transaction. |
| error_invalid_reference_id | Request reference id is not of type string. |
| error_missing_reference_id | Request reference id cannot be null or empty. Hint: reference_id (string) |
| error_amount_exceeded_neft | Your amount exceeds the maximum amount that can be sent via NEFT. Please note that the amount should be <= INR 1000000 per transaction. |
| error_amount_exceeded_upi | Your amount exceeds the maximum amount that can be sent via UPI. Please note that the amount should be <= INR 100000 per transaction. |
| error_malformed_request | Request body is empty/ malformed. Kindly check the payload and retry. |
| error_ifsc_code | Since beneficiary details are being passed, ifsc_code is mandatory. |
| error_amount_invalid | Transfer amount is not a parseable positive float value. Enter a correct value |
| error_empty_transfer_amount | Request body does not contain the transfer amount. |
| error_transfer_type_invalid | Provided transfer_type is invalid. Allowed transfer types are NEFT, RTGS, IMPS and UPI |
| error_empty_transfer_type | Transfer type cannot be null or empty. Hint: transfer_type (string). |
| error_empty_to_account | Request body does not contain the target account number. |
| error_transfer_type_not_allowed | Transfer type UPI is not allowed for the given source account. |
| error_invalid_format_upi | To UPI Address has to be in the NPCI specified format |
| error_from_account_invalid | Request body does not contain the source account number. |
| error_empty_purpose_message | Request body does not contain the purpose message. |
| error_empty_from_account | Source account number does not exist. Kindly retry with a valid value. |
| error_empty_reference_id | Request body does not contain the reference_id. |
| error_amount_exceeded | Transaction amount (plus applied taxes and commission) is more than the balance available in the source account. |
| error_unsanitized_values | Unsanitized values detected for key(s): payee_name. Kindly sanitize the corresponding values by removing special characters such as . @ # $ % ^ & * ! ; : ~ ` ? = + ) ( apostrophe, double quotes and retry |
| error_ifsc_code_incorrect | IFSC length should be 11 |
| error_email_address_incorrect | The provided email address did not pass the validity check. Kindly enter a correct value |
| error_mobile_number_incorrect | Beneficiary mobile number has to be strictly 10 digits long and start with one of 9, 8, 7 or 6 |
| error_provider_error | Unexpected response received from underlying provider. |
| error_exceeded_decimal_in_amount | Transfer amount with precision upto only two decimal places is allowed. |
| error_amount_incorrect_format | Transfer amount has to be an integer |
| error_empty_client_secret | Client Secret cannot be empty. Hint: client_secret (string) |
| error_ise_error | Internal Server Error. Please check the status of the transaction and then retry if failed. |