Revision History
| SI# | Ver# | Modified By | Update | Updated On |
|---|---|---|---|---|
| 1 | 1.0.0 | Tech Team | - Initial Version | 06/06/2019 |
1. Overview
This document serves as an Integration Guide that can be used by client’s technical team to consume Mandate Initiation and Registration functionality of eNACH Solution offered by Khosla Labs.
Document covers the following :
Process Flow that explains the functional flow of the solution ( Mandate Authorization & Mandate Registration.
InitiateMandate API Specification. This API is used to initiate, authorize and register the Mandate with NPCI. API Specification Includes API Request & Response Payload Specification, Sample Request & Response.
Hash Generation Section explains how to generate Hash Parameter ( HMAC ) in request Payload.
2. Process Flow
The client initiates a transaction (see Request Initiation section).
If the request is valid user will be redirected to Veri5 Digital page, where the user will see the mandate data provided by the merchant. He/She needs to provide his/her consent to proceed with mandate authorization.
After giving consent and clicking on proceed the user will be redirected to NPCI page to provide the authentication mode (net banking or debit card) and destination bank name (corresponding to his account number in the mandate data).
From there, the user will be redirected to the destination bank page where they fill in the required authorization details. Now go to step 5.
Then, the user will be redirected back to Veri5 Digital Web sdk page and from there will be either redirected back to merchant app or can proceed with a retry based on number of retries left (in case of failure).
3. Request Initiation
URL (Method: POST)
- https://
hostname/enach_svc/_initiateMandate
Request Details
- Headers:
Content-Type: application/x-www-form-urlencoded
- Parameters:
| name | value | comments | example |
|---|---|---|---|
| client_code | String, Mandatory | Your client code received during onboarding and also you can get this info from Client | a1b2c3 |
| api_key | String, Mandatory | Your api key. This will be shared with you seperately. | q1w2e3 |
| request_id | String, Mandatory | Request Id generated by client. Should be unique for each request. | a72bd9hjd9 |
| collection_amount* | Decimal, Conditional | Amount to be collected from the debtor's account | 2000.00 |
| maximum_amount* | Decimal, Conditional | Maximum amount that may be collected from the debtor's account, per instruction | 5000.00 |
| category_code | String, Mandatory | Category under which the mandate is created. Following are the possible category codes along with their description. A001- API mandate C001 - B2B Corporate B001 - Bill Payment Credit card D001 - Destination Bank Mandate U001 - Utility Bill Payment Electricity U003 - Utility Bill payment Gas Supply Cos U005 - Utility Bill payment mobile telephone broadband U006 - Utility Bill payment water L001 - Loan instalment payment L002 - Loan amount security I001 - Insurance Premium I002 - Insurance other payment M001 - Mutual Fund Payment F001 - Subscription Fees T002 - TReDS T001- Tax Payment E001 - Education fees U099 - Others | I001 |
| category_description | String, Mandatory | Description of category. Should be exactly as given above (case sensitive) for the provided category code. | If category_code=I001 then category_description =Insurance Premium |
| sequence_type | String, Mandatory | Identifies the underlying transaction sequence as either recurring or one-off. Values must be "RCUR" or "OOFF" | RCUR |
| frequency_type | String, Optional | Regularity with which instructions are to be created and processed. Frequency codes currently accepted are given below with their meaning: ADHO => Adhoc, INDA => Intra Day, DAIL => Daily, WEEK => Weekly, MNTH => Monthly, MIAN => Semi annually,YEAR => Yearly,BIMN => Bi-Monthly, QURT=> Quarterly | MNTH |
| first_collection_date | String, Mandatory | Date of the First collection of a direct debit as per the mandate. This field is in ISO Date Format ,This field will include optional timezone +5:30. | 2012-05-17+05:30 |
| final_collection_date | String, Optional | Date of the final collection of a direct debit as per the mandate. This field is in ISO Date Format ,This field will include optional timezone +5:30. | 2015-05-17+05:30 |
| redirect_url | String, Mandatory | This should be a valid url. We will redirect the response on this URL after mandate authorization response is received from NPCI. Check Response Details section for further details. | https://mydomain.com/response.html |
| debtor_name | String, Mandatory | Name of the debtor from whose account debit will happen. | abc |
| crn_no | String, Mandatory | Customer reference number. Will be shown to user along with mandate data. | crn123 |
| hash | String, Mandatory | This should be SHA-256 value of the hash sequence as per Hash Generation section. | 9780cd0d2ce77eef 8f64942f54e0281a 0e220ff6bbcce0a0 3df27a2b15575f58 |
- Either one of collection_amount or maximum_amount is mandatory
3.1 Sample HTML Code
This sample code demonstrates how to initiate the InitiateMandate API from merchant application.
<form method="post" action="<to be provided separately>">
<input type="hidden" name="client_code" value="<your client code>" >
<input type="hidden" name="api_key" value="<timestamp in millisecond>" >
<input type="hidden" name="request_id" value="request123" >
<input type=”hidden” name=”collection_amount” value=”2000.00”>
<input type=”hidden” name=”category_code” value=”U099”>
<input type="hidden" name="category_description" value="Others" >
<input type="hidden" name="sequence_type" value="RCUR" >
<input type="hidden" name="frequency_type" value="MNTH>” >
<input type="hidden" name="first_collection_date" value="2012-05-17+05:30”>
<input type="hidden" name="redirect_url" value="https://mydomain.com/response.html”>
<input type="hidden" name="debtor_name" value="debtor123" >
<input type="hidden" name="debtor_account_no" value="71930312>” >
<input type="hidden" name="hash" value="<calculated hash value>” >
<input type="hidden" name="salt" value="<your salt>” >
<input type="hidden" name="crn_no" value="<your customer reference no.>” >
<button type="submit">Proceed </button>
</form >
Response Details:
Redirected to your response URL.
If success, then
responseUrl?requestId=requestId&txnId=txnId&hash=hash&status=SUCCESS
- If failure,
failureUrl?requestId=requestId&txnId=txnId&hash=hash&status=FAIL&errorCode=
Eg:
4. Hash Generation
It is essential that we have a definitive protocol to verify all the communication between us and client.
So for every request coming to us, you have to supply a hash which we will use as a first step of verification.
In return all responses will also contain hash supplied by us. You should not entertain any request at your responseUrl if hash does not match.
Hash should be calculated this way: hash=SHA256(Hash-Sequence)
Hash Sequence is specified as follows(no space,no commas,no single/double quotes)
InitiateMandate Api Request :
client_code|request_id|collection_amount|maximum_amount|category_code|category_description|sequence_type|frequency_type|first_collection_date|final_collection_date|redirect_url|debtor_name|debtor_account_no|api_key|saltInitiateMandate Api Response :
client_code|request_id|status|api_key|txn_id|salt
Example(For _init request): If your
client_code=a1b2c3,
api_key=123,
requestId=1234567890101112,
salt=e1d2c3b4a,
collection_amount=2000.00
category_code =U099
category_description=others
sequence_type=RCUR
frequency_type=MNTH
first_collection_date=2012-05-17+05:30
redirect_url=https://mydomain.com/response.html
debtor_name=debtor123
debtor_account_no=71930312
then
Hash-Sequence=a1b2c3|1234567890101112|2000.00
||U099|others|RCUR|MNTH|2012-05-17+05:30||https://mydomain.com/response.
html|debtor123|71930312|123|e1d2c3b4a
hash =SHA-256(Hash-Sequence)
For validation:
Receiving end should calculate hash based on request parameters and match it against the received hash.
If receivedHash=calculatedHash, then only you should proceed with your application logic.
api_key and salt are the key parameters here. It is known only to the client and Khosla Labs.
api_key and hash need to be passed in each API call. Salt is never transmitted in any API call
Appendix A : Cancel Payment Request API Specification
Below is the link for cancelPaymentRequest API Specification for eNACH Payment Services.
https://drive.google.com/drive/u/1/folders/1aXdFS7b4H1PQbMgD6XPCgAcX6YWRhf9R
Appendix B : Check Payment Status API Specification
Below is the link for checkPaymentStatus API Specification for eNACH Payment Services.
https://drive.google.com/file/d/1SXhBxQPfvTzIFQ2blVF7rd0O2lla9nLp/view?usp=sharing
Appendix C : Make Payment Request API Specification
Below is the link for makePaymentrequest API Specification for eNACH Payment Services.
https://drive.google.com/file/d/1GuDk9k1HrGknkPRy8t4j4sUBcr-2E5fC/view?usp=sharing
Appendix D : Get Mandate Registration Status API Specification
Below is the link for getMandateRegistrationStatus API Specification for eNACH Payment Services.
https://drive.google.com/file/d/1aVcXuD_baxU-m9ozbYr2sF6yQFEn_Mr3/view?usp=sharing