Signature Mechanism

Generate Signatures

Signature Content

The signature content is made up of seven parameters, each ending with \n (a line break). Include the last parameter, and if the parameter itself ends with \n, you also need to append a \n.

AppId\nAppSecret\nHTTPMethod\nURL\nRequestTimestamp\nNonce\nRequestBody\n

Examples：

483f6c9c743b4a9bbd34bee0c9c81eb7
19200e1478524aceb629acbc570d15d3
POST
https://{{gateway_domain}}/pg/v2/payment/create
1724932426000
3d4578d6c27186f31411ed01b870dffe
{"merchantTradeNo":"MTU-11677","amount":"1.00","currency":"INR","description":"payment test","payer":{"userId":"test_id","name":"testName","email":"[email protected]","phone":"00000000"},"payMethod":{"type":"UPI"},"tradeEnv":{"ip":"127.0.0.1","deviceId":"02efc74d-3988-4f0d-8cc8-0cb78bded719"},"merchantAttach":"merchant attach","notifyUrl":"https://example.com/notifyurl","returnUrl":"https://example.com/returnurl"}

TIP

The body parameters of the request packet are in the format of JSON strings. When generating the main body of the request packet, set the field data type based on the parameter type of the interface document, for details about the sample code on the API description page.

Please do not modify the request body after generating the signature, otherwise the gateway signature verification will fail.

Submit Signature

Submit via the standard HTTP Authorization header. Authorization consists of two parts: the authentication type and the signature information.

# Format
Authorization: CertificationType Signature

# Example
Authorization: V2_SHA256 appId=4189b620f93b48c5904210ff47bb8938,sign=58c7f3ddbdeb80caa41e511aec154d16abbea448ba9278c49c0027becf7d2631,timestamp=1713515049457,nonce=B2DF764E7371B224FB3F144F1BD69A2A

• Certification type, currently V2_SHA256
• Signature information
  • format: appId=%s,sign=%s,timestamp=%s,nonce=%s (%s replaced with actuals)
  • appId: The application ID obtained by the merchant in the merchant's self-service system
  • sign: the signature value of the API request
  • timestamp: timestamp (milliseconds)
  • nonce: a random string
  • The above signature fields can appear in any order

Signature Calculation Method

TIP

It is highly recommended to use the SDK for signature calculation and verification.

package com.examplepay.sdk.authorization.example;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class SignDemo {
    public static void main(String[] args) throws NoSuchAlgorithmException {
        // The format of the signed content is described above
        String signContent = "Replace with the Actual Content to be Signed";
        String algorithm = "SHA-256";
      
        MessageDigest messageDigest = MessageDigest.getInstance(algorithm);
        messageDigest.update(signContent.getBytes(StandardCharsets.UTF_8));
        byte[] byteBuffer = messageDigest.digest();
      
        StringBuilder sb = new StringBuilder();
        for (byte b : byteBuffer) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) {
              sb.append('0');
            }
            sb.append(hex);
        }
        String sign = sb.toString();
      
        System.out.println(sign);
    }
}

Signature Verification

API Request and Response Scenarios

When the HTTP status code is 200, the validity of the signature must be verified to ensure the authenticity and integrity of the response.

1. Extract the Authorization header from the gateway server's response headers.
2. Retrieve the signature information based on the Authorization format described earlier.
3. Parse the signature information to extract the timestamp and nonce.
4. Re-sign the gateway server's response body using the specified signing format.
5. Compare the re-signed result with the signature information returned by the gateway server for validation.

WARNING

When verifying the signature, always use the original response body from the gateway (HTTP Response Body) to ensure consistency. Avoid using parsed or transformed data where null or empty values might be filtered, as this could lead to signature verification failure.

The response fields of an API may be expanded based on business requirements. If you do not use the original response body but instead verify the signature using a parsed object or a manually constructed JSON string, newly added fields may be missing or the field order may change, which can lead to signature verification failure.

Webhook Scenarios

• When the merchant verifies the signature, the URL is the address where the payment platform currently initiates a request to the merchant's system. The URL should be the notifyUrl that the merchant filled in when calling the payment platform interface to create an order.
• Other scenarios in which the same interface responds to requests.

WARNING

When verifying signatures, be sure to use the HTTP request body of the original request packet of the gateway to prevent null or empty values from being filtered out after parsing and transformation, which are inconsistent with the original request body of the gateway, resulting in failure to verify the signature.

The fields in a webhook callback payload may be expanded based on business requirements. If you do not use the original response body but instead verify the signature using a parsed object or a manually constructed JSON string, newly added fields may be missing or the field order may change, which can lead to signature verification failure.

Return URL Redirection Scenarios

1. Fetch the payment and authorization field values from queryString.
2. Use the Authorization format above to retrieve the signature information.
3. Parse the signature information and retrieve the request timestamp and nonce.
4. Re-sign the payment field value according to the signature content format above. The format of the signature content is:

AppId\nAppSecret\nHTTPMethod\nURL\nRequestTimestamp\nNonce\nQueryString\n

URL：Refers to the original return URL submitted by the merchant, excluding specific parameters added during platform redirection. Specific parameters include：payment/authorization/paymentNo/merchantTradeNo

QueryString format:
payment=%s, where %s is the value of the payment parameter.

Example：
payment={"amount":"1.00","createdTime":"2024-04-23T21:15:29+08:00","currency":"INR","merchantAttach":"merchant attach","merchantTradeNo":"MTU-1150","paymentNo":"20240423211529300800001098000022","refundStatus":"NO_REFUND","status":"PENDING"}

5. Verify against the signature information in the authorization field value.