post https://staging.api.decentro.tech/v3/banking/settlement_request
This API is used by the platform to request for a settlement from the available balance with Decentro.
Overview
This API allows the platform to request a settlement from Decentro from the available balance. The requested settlement is processed by Decentro after checking the balances available. The actual settlement to the merchant is processed depending on the transfer mode and the amount.
Note: This feature is now available only for collections undertaken through the Virtual accounts stack of Decentro. The same will be rolled out for UPI and other modes of collections as well.
Flow
Below is the flow for using this API.
- The platform receives collections from its payers using the Virtual accounts created using the Create a Virtual Account v3 API
- The platform receives the settlement account URN (settlement_account_urn) from Decentro when adding the settlement account via manage settlement account API
- The platform can initiate settlements with the required amount using this request settlement API
- Decentro validates the balance available in the virtual account for processing settlements and commissions and processes the request or rejects it if the balance is insufficient or the payload is invalid.
- The platform receives confirmation of the settlement request from Decentro and triggers a settlement callback to the platform.
API Endpoints
| Environment | Endpoint |
|---|---|
| Staging/Sandbox | https://staging.api.decentro.tech/v3/banking/settlement_request |
| Production | https://api.decentro.tech/v3/banking/settlement_request |
Response key
| Response Key | Message |
|---|---|
| success_settlement_request_initiated | Settlement request initiated successfully |
| error_invalid_reference_id | Reference ID is not valid. |
| error_empty_reference_id | Reference ID cannot be empty. Hint: reference_id (string) |
| error_invalid_format_reference_id | Reference ID is not of type string. Hint: reference_id (string) |
| error_duplicate_reference_id | Duplicate Reference ID. Please pass an unique value. |
| error_incorrect_length_reference_id | Reference ID needs to be between 5 and 50 characters |
| error_invalid_consumer_urn | Consumer URN does not exist. Please retry with a valid consumer_urn |
| error_empty_consumer_urn | Consumer URN cannot be empty. Hint: consumer_urn (string) |
| error_invalid_format_consumer_urn | Consumer URN is not of type string. Hint: consumer_urn (string) |
| error_invalid_beneficiary_code | Beneficiary code does not exist. Please retry with a valid beneficiary code |
| error_missing_beneficiary_code | Beneficiary code cannot be empty. Hint: Beneficiary code (string) |
| error_invalid_format_beneficiary_code | Beneficiary code is not of type string. Hint: beneficiary_code (string) |
| error_invalid_amount | Please pass the amount value with up to two decimals places only. Hint: amount (float) |
| error_empty_amount | Amount cannot be empty. Hint: amount (float) |
| error_invalid_format_amount | Amount is not of type int or float. Hint: amount (INT, float) |
| error_insufficient_balance | Amount is more than available balance. Please retry with with amount less than or equal to . |
| error_empty_purpose_message | Purpose message cannot be empty. Hint: purpose_message (string) |
| error_invalid_format_purpose_message | Purpose message is not of type string. Hint: purpose_message (string) |
| error_incorrect_length_purpose_message | Purpose message needs to be between 5 and 50 characters |
| error_missing_va_suffix/error_missing_virtual_account_number | Either of virtual account number or va suffix value is required. Please pass valid value. |
| error_invalid_virtual_account_number | virtual account number does not exist. Please pass a valid virtual account number |
| error_invalid_va_suffix | va_suffix does not exist. Please pass a valid va_suffix |