AePS Gateway Integration (Backend)
Create a callback-URL on your server
Backend server integration serves two important purposes for you:
- Directly get AePS Gateway transaction status on your server.
- For better security and to avoid fraud, Eko seeks a secure confirmation from your server every time a transaction is done.
General Steps For Server-Side Integration
- Use the guide below to create a callback API on your server.
- Configure your callback-URL in the frontend code (see Frontend Integration docs for Web & Android).
- You will receive a request on your callback-URL to confirm a transaction. Return a secure confirmation.
- You will receive a confirmation for the current transaction. Store the information on your server.
STEP 1: Create a callback-URL on your server
- Create callback-URL (Method : POST)
- Implement the CORS headers on your callback-URL
Your server must send proper CORS headers in the response of your callback-API (You can refer to the link https://developers.eko.in/docs/enable-cors)
Add the following response HTTP headers:
For OPTIONS method:
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Origin: https://stagegateway.eko.in
Access-Control-Allow-Headers: Content-Type
For POST method:
Access-Control-Allow-Origin: https://stagegateway.eko.in
- Configure the callback-URL :-
Frontend:
See AePS Integration-Web (Step - 3)
aeps.setCallbackURL('https://your-website.com/eko_aeps_callback');
Android:
See AePS Integration-Android (Step - 2)
bundle.putString("callback_url", callback_url);
STEP 2: Add logic to your callback-URL
Eko AePS Gateway will call your callback-URL with two types of request:
- Transaction Intimation:
- This tells that a transaction is about to happen.
- Request body contains action=debit-hook
- Request body contains the rest of the transaction details (in detail).
- Verify the transaction details.
- You may store the transaction details in your database with status=pending
- Return a valid confirmation response as per the guide below.
- Transaction Response:
- Request body contains action=eko-response
- Request body contains the rest of the transaction details along with status (successful/failed).
- This is just for your information. You may store/update the transaction success/failure status in your database.
For Cash withdrawal, data.type will be 2, for Balance Inquiry, data.type will be 3 and for Mini Statement data.type will be 4
{
"action": "debit-hook",
"detail": {
"http_method": "POST",
"interaction_type_id": 344,
"interaction_label": "AePS",
"client_ref_id": "1540880592059",
"request_hash_params": ["customer_id", "amount", "user_code"],
"data": {
"customer_id": "9999999999",
"bank_code": "PUNB",
"type": "2",
"user_code": "20810200",
"amount": "100"
},
"param1": "value1",
"param2": "value2",
}
}
{
"action": "go",
"allow": true,
"secret_key_timestamp": "1540880719963",
"request_hash": "r8SC5YiCylzllnftA9ys4/hPi5hIJrMVZhykamemqKE=",
"secret_key": "4CKAzpT/B44CnhXM01pRnZELcGKWOhvbZg7TqoGDIrA="
}
{
"action": "go",
"allow": false,
"message": "Your reason to cancel the transaction. It will be shown to your user/merchant"
}
Step 3: Add Callback-URL logic for Daily KYC
- Sample request sent to your server via callback-URL for DailyKYC intimation
{
"action": "debit-hook",
"detail": {
"url": "/api",
"http_method": "POST",
"interaction_type_id": 594,
"interaction_label": "Daily KYC",
"client_ref_id": "781716212761753",
"card_index": 1,
"request_hash_params": [],
"data": {
"customer_id": "",
"bank_code": "SBIN"
}
}
}
- Sample response returned by your callback-URL to give a go-ahead to the DailyKYC
{
"action": "go",
"allow": true,
"secret_key_timestamp": "1540880719963",
"secret_key": "4CKAzpT/B44CnhXM01pRnZELcGKWOhvbZg7TqoGDIrA="
}
- Sample response returned by your callback-URL to cancel DailyKYC
{
"action": "go",
"allow": false,
"message": "Your reason to cancel the DailyKYC. It will be shown to your user/merchant"
}
Please Note
- With every financial transaction, a unique client_ref_id will be shared for your reference and transaction identification.
- Your application can make a note of this client_ref_id for future inquiry purposes.
- It should be stored as a string of maximum length twenty.
- You can generate and pass the client_ref_id from your end and can pass in the response of the debit hook transaction with maximum length of 20 characters and we will overwrite ours generated client_ef_id with yours and provide you the client_ref_id generated by you in the final transaction response of the AePS.
At the time of transaction confirmation, you must send security parameters in the payload (secret_key, secret_key_timestamp & request_hash) which are generated on your server.
Please Note
To generate secret_key, secret_key_timestamp and request_hash, refer to authentication section
For generating request_hash, the request will be formed by concatenating secret_key_timestamp and value of parameters present in request_hash_params(detail.request_hash_params) array list in same order.
You should iterate through request_hash_params list and check if that field is present in detail.data, if present then append its value in the request signature, used to generate request_hash
For e.g.
When request_hash_params = ["customer_id","amount","user_code"]
secret_key_timestamp = “1532582133692”
ThenFor Cash Withdrawal ("type": "2")
detail.data: {
"customer_id": "9999999999",
"bank_code": "PUNB",
"type": "2",
"user_code": "20810200",
"amount": "2000"
}request signature =
secret_key_timestamp + customer_id + amount + user_code
“1532582133692” + “9999999999” + “2000” + “ 20810200”
“15325821336929999999999200020810200”For Balance Inquiry ("type": "3")
detail.data: {
"customer_id": "9999999999",
"bank_code": "PUNB",
"type": "3",
"user_code": "20810200"
}request signature =
secret_key_timestamp + customer_id + user_code
“1532582133692” + “9999999999” + “ 20810200”
“1532582133692999999999920810200”For Mini Statement ("type": "4")
detail.data: {
"customer_id": "9999999999",
"bank_code": "PUNB",
"type": "4",
"user_code": "20810200"
}request signature =
secret_key_timestamp + customer_id + user_code
“1532582133692” + “9999999999” + “ 20810200”
“1532582133692999999999920810200”Steps to generate the request_hash:
First, the secret-key value which you have passed "f74c50a1-f705-4634-9cda-30a477df91b7"; is not a value of secret-key this is the key which is encoded to generate the secret-key and secret-key-timestamp.
Please generate the request hash properly. Please check the request hash generation code again. Before generating the request hash you need to generate a string which will be generated by concatenating some parameters in a particular manner only. You cannot change the sequence.
Sequence concatenated string in case of cash withdrawal :
secret_key_timestamp + customer_id + amount + user_code
Sequence concatenated string in case of request balance :
secret_key_timestamp + customer_id + user_code
Sequence concatenated string in case of mini statement:
secret_key_timestamp + customer_id + user_code
After generating the concatenated string please follow the following procedure :
- Encode your authenticator password using the base 64. Authenticator password will be the key which you have used for the secret-key generation. Authenticator password for the staging server is "f74c50a1-f705-4634-9cda-30a477df91b7"
// Initializing key in some variable. You will receive this key from Eko via email
$key = "f74c50a1-f705-4634-9cda-30a477df91b7";
$encodedKey = base64_encode($key);
After encoding the key, you need to hmac the concatenated string and encoded_key using hmac256.
$signature_req_hash = hash_hmac('SHA256', $data, $encodedKey, true);
In the $data you need to send the concatenated string.After hmac , you need to again encode the result using the base64.
$request_hash = base64_encode($signature_req_hash);Final result after encoding will be the request_hash.
Please make sure that you are generating the request_hash in this manner only.
Eko AePS Gateway proceeds the transaction on receiving confirmation from your server.
Eko AePS Gateway sends the transaction response to your server via your callback-URL:
{
"action": "eko-response",
"detail": {
"url": "https://stagegateway.eko.in/v2/api",
"client_ref_id": "1546497183438",
"http_method": "POST",
"http_status": 200,
"interaction_type_id": 344,
"is_debithook_response": true,
"is_final": true,
"response": {
"status": 0,
"response_status_id": 0,
"response_type_id": 1305,
"message": "Transaction successful",
"data": {
"tx_status": "0",
"transaction_date": "",
"reason": "",
"amount": "2000.0",
"merchant_code": "",
"tds": "0.3",
"shop": "",
"sender_name": "amit",
"tid": "14563687",
"auth_code": "",
"balance": "339976.26",
"shop_address_line1": "",
"user_code": "20310001",
"merchantname": "Sneha",
"stan": "",
"aadhaar": "XXXX XXXX 9999",
"customer_balance": "",
"transaction_time": "",
"commission": "6.0",
"bank_ref_num": "",
"terminal_id": ""
}
}
},
"param1": "value1",
"param2": "value2",
}
Status of a cash withdrawal transaction is marked by field tx_status (*detail.response.data.tx_status*):
tx_status | Description |
---|---|
0 | Successful Transaction |
1 | Failed transaction |
2 | Do the transaction inquiry |
Any other value | Suspicious, contact Eko |
commission (*detail.response.data.commission*) field states the commission given to you for that transaction.
- For transaction inquiry, use the Transaction Inquiry API
- Security Tip: Make sure to call the Transaction Inquiry API only from your back-end server, to validate the status of a transaction.
- Use this API to get confirmation of any transaction with an unknown status.
Updated 5 months ago