1. Headers

Every hamropay api request should include certain headers to work. It is mandatory for all the api.

Following are three headers that the client needs to pass while sending every request. The header includes the following:

1. Client Id: The unique id that will be generated and given by the Hamropay team.
2. Client API Key: This is the key to access the API for checkout . API Key will be generated and given to the client by the Hamropay team.
3. Signature: Every request should have a signature header attached, which is a string value. Every api section describes how to generate the signature string for that api.

Headers Example with Key And Values :

2. Signature Generation

This section describes how the signature string should be generated in general, for the values required for generating the signature please consult every api section found below.

Signature must be included in the header section of the request. To generate a signature we need the signature string (described in the individual API section) and client secret.

The client secret used for generating the string will be provided by the Hamro Pay team and shared ONLY between the client and Hamro Pay Checkout API.

The signature should be a Base64 string of HMAC512 message output.

Psudo Code Example:

client_secret = 'abcdefg'

signature_message_string = field1 + ',' + field2 + ',' + field3 + ',' + field4.. fieldn
(String separated by comma).

final_signature_string = toBase64 ( HmacSHA512Digest(signature_message_string, client_secret) )

(Values separated by comma as a string). Messages are different according to APIs. What field's to be used for generating the signature_message are defined in the every API sections.

2.1. Sample Code For Base64 Signature Generation

public static String signHMAC(String message, String secret) {
   try {

       Mac mac = Mac.getInstance("HmacSHA512");
       SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes(), "HmacSHA512");
       mac.init(secretKeySpec);
       return Base64.getEncoder().encodeToString(mac.doFinal(message.getBytes("UTF-8")));

   } catch (NoSuchAlgorithmException var4) {
       throw new RuntimeException(var4);
   } catch (InvalidKeyException var5) {
       throw new RuntimeException(var5);
   } catch (UnsupportedEncodingException var6) {
       throw new RuntimeException(var6);
   }
}

3. Checkout API

initial_signature_string = merchantTxnId+','+transactionAmount+','+merchantId+','+client_id+','+clientApiKey
final_signature_string = toBase64 ( HmacSHA512DigestOf(initial_signature_string, using_secret) )

"clientCommissionConfig": {
       "commissionMerchantId":"8c9e2ea0-4eb5-11f1-baa3-de257371874e1",
       "commissionPercentage": 3.56
   }

"productList" : [
  {
    "name:" "shirt",
    "imageUrl":
      "https://testUrl.jpg",
    "description": "This is shirt",
    "price": 99.99, //Amount in Rs. for render purpose so Rs.99.99 should be 99.99
    "quantity": 1
  },
];

// Request
{
    "merchantTxnId": {{transactionId}},
    "merchantId" : "PN_-Nd99TBnAlBjCgl8ef_b",
    "transactionAmount": "1000",
    "failedRedirectionUrl":"https://testl.com/payment/",
    "successRedirectionUrl":"https://testl.com/payment/",
    "productList" : [
      { "name:" "shirt", "imageUrl": "https://testUrl.jpg", "description": "This is shirt", "price": 10, "quantity": 1 },
      { "name:" "shirt2", "imageUrl": "https://testUrl2.jpg", "description": "This is shirt 2", "price": 20, "quantity": 1 }
    ]
}

// Response
200 OK

{
    "sessionId": "ca8f7b70-b9c9-11ee-8611-0a73743c8233",
    "merchantId": "PN_-Nd99TBnAlBjCgl8ef_b"
}

3.2. Checkout Proceed API

The checkout API is intent for the web to call. After the Session creation, the client’s website can make a request with Checkout-Form to hamro pay-checkout-gateway. This request has a Checkout-Form where Params need to be sent to hamropay checkout gateway. This will redirect you to hamropay checkout webpage with given params in form data.

Important NOTE

After the Session creation api is called you need to generate the params in your backend service so that the secret is NOT exposed to the client as you need the secret to build a token for the params, i.e directly return data required to build params from the Create Session API as you already have all the details required after calling the session API for params building, after generating the params return the params to your web-client which makes a form-data request using the params to hamro pay-checkout-gateway described below.

POST {{GATEWAY_URL}}/api/checkout UAT base URL

Intended API User: Merchant frontend

Request body ( Form Data) :

Params :

The params of Checkout-Form, also known as body of request contains merchant_id, session_id, Token, merchant_transaction_id, transaction_id and remarks.

Token

Token is a form Signature but with different fields, and rather than passing it to header its passed in params iteself. Token is generated the same as Signature Generation using the your same Secret and Message format described below.

Fields for token generation: 1. merchant_id
2. merchant_transaction_id
3. session_id
4. transaction_amount
5. client_id
6. client_api_key
Use these fields for signature string generation i.e values of the fields combined with ',' to form a single string and see Signature Generation section to see how to generate this.

Params for request body :

params.js

Copy

params = {
            merchant_id: "Your merchant id" ,
            session_id: "Session ID",
            token: "Your Token" ,
            merchant_transaction_id: "Your Transaction ID (length less or equal to 25 chars)",
            remarks: " Remarks (upto 250 chars) ",
            phone_number: "phone number of hamropay user if available [OPTIONAL]"
          };

Js Sample Checkout-Form using params above

checkout-form.js

Copy

const form = document.createElement("form");
  form.method = method;
  form.action = path;
  form.enctype = "application/x-www-form-urlencoded";
  for (const key in params) {
    if (params.hasOwnProperty(key)) {
      const hiddenField = document.createElement("input");
      hiddenField.type = "hidden";
      hiddenField.id = key;
      hiddenField.name = key;
      hiddenField.value = params[key];
      form.appendChild(hiddenField);
    }
  }

  document.body.appendChild(form);
  form.submit();

Response after the request: Redirection to Hamro pay checkout gateway.

How it looks in web :

How it looks in Mobile :

initial_signature_string = merchantTxnId+','+merchantId+','+client_id+','+clientApiKey
final_signature_string = toBase64 ( HmacSHA512DigestOf(initial_signature_string, using_secret) )

// Request
{
    "merchantId" : "PN_-Nd99TBnAlBjCgl8ef_b",
    "merchantTxnId" : "erftycnmiim"
}

// Response
{
    "merchantTransactionId": "erftycnmiim",
    "trackingId": "",
    "status": "NOT_INITIATED",
    "amount": 0,
    "remarks": "",
    "message": "TRANSACTION NOT INITIATED YET"
}

4. Success / Failed Redirection

After the transaction, HamroPay will redirect to the provided success or failure URL.

https://something.com/success?MerchantTxnId=123213

https://something.com/failure?MerchantTxnId=123213

5. Webhook (Optional)

Merchants / Clients will receive a webhook to their provided POST REQUEST URL (endpoint) from hamro pay after the Checkout transaction is successful or failed. The webhook can be used to trigger the actual transaction without having to poll for the transaction status.

Using Hamro Pay webhook

1. 1. Integration Setup: To begin, the client integrates their application with Hamro Pay's payment system. This involves providing a callback URL, typically a POST endpoint, where Hamro Pay will send webhook notifications which is a json body regarding payment details.
2. 2. Webhook Configuration: Once integrated, Hamro Pay configures its system to send payment webhook notifications to the provided URL whenever a payment status changes, such as success or failure.
3. 3. Handling Webhook Requests: The client's server needs to implement an endpoint to receive and process webhook requests. This endpoint should be capable of handling POST requests and parsing the incoming data.
4. 4. Processing Payment Status: Upon receiving a webhook notification, the client's server extracts relevant information from the payload, such as transaction ID, status, and any associated metadata.
5. 5. Handling Success or Failure: Depending on the received status, the client's application can take appropriate actions. For instance, if the payment was successful, it can update the user's account or trigger a confirmation message. If the payment failed, it can initiate a refund process or notify the user about the issue.
6. 6. Signature Verification (Optional but Recommended): To ensure the authenticity of webhook requests and prevent unauthorized access or tampering, HamroPay can include a signature along with the payload. The client's server then verifies this signature to confirm that the request indeed originates from HamroPay.

Webhook Body:

These are the json body fields you will receive in request from hamropay backend to your provided endpoint.

Json Representation

//HEADER
// Signature: <<Signature String generated from hamropay>>

{
  "merchantTxnId": "Txn Id used for reconciliation purposed initially from client",
  "merchantId": "your merchant Id",
  "amount": 9.99, //in Rs.
  "status": "COMPLETED OR FAILED" //either or,
  "metadata": {"field1":"fieldValue1","field2":"fieldValue2"}
}

Webhook Verification

You will get a webhook request containing the signature in the header. The signature string is available in header in key Signature i.e header.get("Signature"). The {{merchantWebHookSigningSecret}} will be provided by Hamro Pay team.

//Use the following fields from the body, to generate the signature string:
// Seperated by commas
var signatureString = merchantTxnId +','+ merchantId +','+ status +','+ amount;

var signatureFromHeader = header.get("Signature");
var signatureGenFromBodyInBase64 = Base64( HMAC.signHMAC(signatureString , {{merchantWebHookSigningSecret}}) );

var isValid = signatureFromHeader.equals(signatureGenFromBodyInBase64);

You can Signature Generation to see code sample how to generate signature string using the fields merchantTxnId +','+ merchantId +','+ status +','+ amount

6. Code with Description

Test your integration

Once you have wired up the endpoints above, run an end-to-end payment with the sandbox test credentials and verify the success, failed, and pending flows.