AePS Gateway Integration (Backend)

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

1. Use the guide below to create a callback API on your server.
2. Configure your callback-URL in the frontend code (see Frontend Integration docs for Web & Android).
3. You will receive a request on your callback-URL to confirm a transaction. Return a secure confirmation.
4. 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:

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

1. 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"
    }
  }
}

2. 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="
}

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

For 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 :

1. 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);

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

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

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.