NAV Navbar
cURL JSON CodeSnippet

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 :

2. Process Flow

  1. The client initiates a transaction (see Request Initiation section).

  2. 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.

  3. 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).

  4. From there, the user will be redirected to the destination bank page where they fill in the required authorization details.

  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)

Request Details

Content-Type: application/x-www-form-urlencoded

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

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:

responseUrl?requestId=requestId&txnId=txnId&hash=hash&status=SUCCESS

Eg: https://mydomain.com/response.html?requestId=123456789101112&txnId=33adb2ce-b26b-4cef-a485&hash=9780cd0d2ce77eef8f64942f54e02&status=SUCCESS

failureUrl?requestId=requestId&txnId=txnId&hash=hash&status=FAIL&errorCode=&errorMsg=

Eg:

https://mydomain.com/response.html?requestId=123456789101112&txnId=33adb2ce-b26b-4cef-a485&hash=9780cd0d2ce77eef8f64942f54e02&status=FAIL&errorCode=100&errorMsg=Error

4. Hash Generation

  1. It is essential that we have a definitive protocol to verify all the communication between us and client.

  2. So for every request coming to us, you have to supply a hash which we will use as a first step of verification.

  3. 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.

  4. Hash should be calculated this way: hash=SHA256(Hash-Sequence)

  5. Hash Sequence is specified as follows(no space,no commas,no single/double quotes)

  6. 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|salt

  7. InitiateMandate 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: