3. Core APIs
3.1. Create Mandate Request API POST
To register a new mandate with NPCI, the end customer must review and authorise the request. To authorise the mandate, the request must be sent to NPCI ONMAG service which redirects the user appropriately.
This API is used to request a mandate registration. Invoking this API will trigger creation of a URL which is sent to the customer. The customer can review the mandate details and proceed to the NPCI ONMAG service for authorization.
The details of the API are given below:
3.1.1. Request
Request URL / Method
| Attribute | Value |
|---|---|
| URL | https:// |
| Method | POST |
Request Body
Mandate Details object
| Name | Mandatory | Max. Length | Type | Description |
|---|---|---|---|---|
| referenceNumber | C | 35 | AN | Can be used to refer to the mandate request with the Provider. If not passed, the system will assign a unique reference number. |
| utilityCode | M | 18 | AN | NPCI Identifier for the merchant. It should be a 18-digit Utility code. |
| seqTp | M | 4 | AN | Regularity with which instructions are to be created and processed. This
must be
one of the values below: • OOFF - One-off • RCUR - Recurring |
| frqcy | M | 4 | AN | NACH: list of values available in NACH List. UPI: list of values available in UPI List. Refer NACH/UPI excel sheet. |
| frstColltnDt | M | 10 | Date | Date of the first collection of a debit as per the mandate. Format: YYYY-MM-DD. E.g. 2020-01-25 |
| fnlColltnDt | M | 10 | YYYYMMDD | Date of the final collection of a debit as per the mandate. If the date is not passed, it will be set to default 40 years from the frstColltnDt (First Collection Date). Final Collection Date cannot exceed 40 years from the First Collection Date. |
| amountTp | M | 4 | AN | This must be one of the values below: • FIXA - Fixed Amount (Amount to be collected as per the Frqcy, Ex. If the Frqcy is monthly, then mention the fixed amount that must be collected every month) • MAXA – Upto a Maximum Amount (Full Loan amount for the entire mandate cycle to be mentioned) |
| colltnAmt | M | 13 | #.00 | Amount to be collected from the debtor's account. Amount in Rupees with paisa component. Example: 12000.00 |
| mndtType | O | 10 | AN | This must be one of the values below: • ONMAG • UPI If value not given, the default value is ONMAG. |
Loan Details object
| Name | Mandatory | Max. Length | Type | Description |
|---|---|---|---|---|
| categoryCode | M | 4 | AN | Identifies under which category the mandate is created. NACH or UPI list values can be referred to. |
| schmNm | M | 20 | AN | Scheme/Plan Reference Number given by the Merchant, e.g., "House Loan" or loan number. |
| consRefNo | M | 20 | AN | Consumer Reference Number, e.g., Loan Reference Number or unique reference number corporate to identify record at corporate LOS level. |
Customer Contact Details object
| Name | Mandatory | Max. Length | Type | Description |
|---|---|---|---|---|
| Mobile | C | 10 | Numeric | 10 digit mobile number without any country prefix. Format: XXXXXXXXXX.
Example: 9876543210 (WITHOUT country prefix +91) |
| Phone | O | 34 | AN | 3 char area code + “-” + phone number. Must not have a country prefix.
Format:
XXX-XXXXXXXX. E.g. 080-12345678 |
| C | 50 | AN | Must be a valid email format. Note: Either one of the fields to be mentioned, Email or Mobile number. |
|
| Pan | O | 10 | AN | Customer Additional Identification Details |
Customer Account Details object
| Name | Mandatory | Max. Length | Type | Description |
|---|---|---|---|---|
| bnkId | M | 4 | AN | Bank Short Code to be mentioned i.e. first 4 letters of IFSC Code. Ex: HDFC. Refer ‘Get Live Banks’ API for list of Banks. |
| dbtrNm | M | 40 | AN | Customer Name |
| dbtrAccTp | M | 10 | Alpha | Debtor Account Type. Must be SAVINGS / CURRENT. |
| dbtrAccNo | M | 35 | AN | The account of the debtor, to which a debit entry will be made as a result of the transaction. Note: If account number begins from 0, then ensure to pass account number within double quotes. Ex: ”0123456789”. |
Amount Details object
| Name | Mandatory | Max. Length | Type | Description |
|---|---|---|---|---|
| amountTp | M | 4 | AN | This must be one of the values below: • FIXA - Fixed Amount (Amount to be collected as per the Frqcy, Ex. If the Frqcy is monthly, then mention the fixed amount that must be collected every month) • MAXA – Upto a Maximum Amount (Full Loan amount for the entire mandate cycle to be mentioned) |
| colltnAmt | M | 13 | #.00 | Amount to be collected from the debtor's account. Amount in Rupees with paisa component. Example: 12000.00 |
UPI Details object
| Name | Mandatory | Max. Length | Type | Description |
|---|---|---|---|---|
| virtualAddress | C | 255 | AN | Payer VPA/UPI ID. Can be passed via API or on the Review Page. Applicable for UPI Mandate only. |
| debitDay | C | 2 | N | Debit presentation day for the mandate. Value can be in the range for
the
frequency: [1-7] - For frequency is WEEK [1-15] - for frequency is BIMN [1-30/31] for frequency is MNTH, QURT, MIAN, YEAR. Debit presentation will occur on the next day if the month does not have the day. For NACH, if the debitDay is not given, then collection day is calculated using the first collection date. Mandatory for UPI Mandate. |
| debitRule | C | 20 | AN | Recurrence Rule (ON/BEFORE/AFTER). If Pattern is other than ONETIME/AS PRESENTED/DAILY, then ruleType is mandatory. Mandatory and Applicable for UPI Mandate only. |
| accountValidation | C | 1 | A | This parameter will take care of Thirdparty Account validation during mandate creation. Possible values are Y - Validate the account number for mandate creation N - Do not validate In case of mismatch of account, Revoke requested will be auto fired. Mandatory and Applicable for UPI Mandate only |
| revokeable | C | 1 | Possible values are Y - Revocable N – Non-Revocable Mandatory and Applicable for UPI Mandate only |
3.1.2. Response
The API returns the standard response described in the Overview section. The following tables enumerate the possible “code” values for an API failure and describe the JSON object in the “message” in case of the API success.
Response Message Object Details
| Name | Type | Description |
|---|---|---|
| moreInfo | string | Additional information regarding the request. Ex: mandate request created. |