This API allows the platform to initiate a mandate registration using Decentro's ENACH stack.
Overview
This API allows the platform to initiate an ENACH-based registration request. The payer can then authorize the request using one of the supported modes.
- Debit Card
- Net banking
Ensure to use only staging credentials & Simulation data only.
Flow
Below is the flow for using this API.
- The platform can check if the bank is supported using the Supported Banks API.
- The platform captures the mandate details like amount, frequency, timeframe, etc.
- The platform initiates a registration request by hitting the endpoints with the mandate details.
- Decentro validates if the destination bank supports the authorization mode (Debit Card/Netbanking).
- The platform receives a shortened link from Decentro if the request is successful.
- The platform renders the link on their asset (app/website), which is redirected to the NPCI page.
- The payer authorizes the request using the relevant details
- Debit card-related details if authorization is Debit Card
- Netbanking login and OTP (in some cases) if authorization is Netbanking
- Decentro triggers the registration status callback once the authorization is complete with the status to a pre-configured endpoint.
- Decentro also redirects the payer to the platform's page basis the redirection URL provided at the time of onboarding.
- The platform can alternatively check the registration status using the Mandate Registration Status API by passing the Decentro transaction ID received from this API response.
Note: If the link generated by Decentro is successfully initiated (opened), it remains valid for 15 minutes from the time of opening. If the payer uses the link after this time period, the registration will not be successful. This link can only be clicked once.
Registration Statuses
| Status | Description |
|---|---|
| Active | Mandate registration has been successfully completed, and the mandate is currently active. |
| Inactive | The mandate registration end date has passed. |
| Pending | Mandate registration is still pending completion. The registration process has been initiated but has not been completed. |
| Rejected | Mandate is rejected by destination banks or NPCI for various reasons. |
| Expired | The mandate registration link has expired. This status occurs when the user fails to initiate or open the registration link within the specified timeframe. |
| Session_Timeout | The user initiated the registration session by clicking on the registration link but did not complete the process. The registration was dropped mid-journey due to inactivity or other reasons. |
API Endpoints
Below are the API endpoints to be used by the platform basis the environments.
| Environment | Endpoint |
|---|---|
| Staging / Sandbox | https://staging.api.decentro.tech/v2/payments/enach/mandate |
| Production | https://api.decentro.tech/v2/payments/enach/mandate |
Request Parameters
Frequency
Below are the frequencies accepted by Decentro under the 'frequency' parameter in the request payload.
- Adhoc
- Daily
- Weekly
- Monthly
- Quarterly
- Semi-Annually
- Yearly
- Bi-Monthly
Amount Rule
Below are the values Decentro accepts under the 'amount_rule' parameter in the request payload.
- Fixed -> Amount to be debited from the user's bank account is fixed. Can not debit more or less than the specified amount.
- Max -> Amount to be debited from the user's bank account can be less than or equal to the specified amount.
Authentication Mode
Below are the values Decentro accepts under the 'authentication_mode' parameter in the request payload.
- Debit Card
- Net banking
Start & End Date
Below are the validations on the date parameters in the request payload.
- Start date: needs to be a current date or a date in the future
- End date: needs to be at least 1 day after the start date and can extend up to 40 years
Category Codes
Below are the purpose codes the platform will pass in the category_code parameter in the request payload.
| NPCI Code | Decentro Code | Description |
|---|---|---|
| A001 | API | API mandate (This is discontinued from NPCI) |
| C001 | B2B | B2B Corporate |
| B001 | CRED | Bill Payment Credit card |
| D001 | MAND | Destination Bank Mandate |
| E001 | EDU | Education fees |
| I001 | PREM | Insurance Premium |
| I002 | PAYM | Insurance other payment |
| L002 | LONS | Loan amount security |
| L001 | LONP | Loan installment payment |
| M001 | MF | Mutual Fund Payment |
| U099 | OTH | Others |
| F001 | SUB | Subscription Fees |
| T002 | TRE | TReDS |
| T001 | TAX | Tax Payment |
| U001 | ELEC | Utility Bill Payment Electricity |
| U003 | GAS | Utility Bill payment Gas Supply Cos |
| U005 | TELE | Utility Bill payment mobile telephone broadband |
| WAT | WAT | Utility Bill payment water |
Simulation Data
OTP Validation
- Enter any 6-digit random number to validate the OTP.
- "111-111" use this 6-digit number to verify the wrong OTP scenario.
Debit Card Validation
- Enter a random 12-digit debit card number.
- Enter a random 3-digit CVV.
- Enter a random debit card expiry date.
Authentication Mode - Debit Card
| Amount | Scenario | Message | Error Code |
|---|---|---|---|
| 100 | Wrong account details. | Account doesn't exist or invalid account details. | AP05 |
| 200 | Registration Successful. | Success/ Active | - |
| 500 | Registration Successful. | Success/ Active | - |
| 300 | Wrong debit card details. | Customer entered the wrong debit card details. | AP35 |
| 400 | The Bank account belongs to a minor. | Mandates were not registered. The Bank account is of minor. | AP16 |
| Random amount | Other than the specified amount. | Transaction rejected or cancelled by the customer | AP23 |
| Cancel button | User clicked on the cancel button. | Transaction rejected or cancelled by the customer. | AP23 |
Authentication Mode - Net Banking
| Scenario | Message | Error Code |
|---|---|---|
| User clicked on the cancel button. | Customer cancelled or rejected the mandate registration. | AP23 |
| User accepted | Active/ Success | - |