DianDianPay

English

简体中文

English

简体中文

Toggle theme

Signature and Verification ​

To ensure the integrity and authenticity of data after transmission, Diandian Pay requires all requests to be signed and all notifications to be verified:

  • Requests: When calling Diandian Pay's API, you must sign the request parameters.
  • Notifications: Upon receiving a Webhook notification from Diandian Pay, you must verify the validity of the signature.

Encoding Rules (Must Be Followed for Signing/Verification) ​

To ensure consistent signature generation across different programming languages and systems, strictly adhere to the following rules:

  • Do not perform Unicode escaping on non-ASCII characters (such as Chinese characters, emojis, etc.). Keep the original characters.

    • ✅ Correct example: Chinese remains as 中文, emoji 😊 remains as 😊
    • ❌ Incorrect example: 中文 encoded as \u4e2d\u6587, emoji as \ud83d\ude0a

  • URL strings should remain unencoded (no percent-encoding).

    • ✅ Correct example: https://example.com/pay?param=abc&token=中文
    • ❌ Incorrect example: https%3A%2F%2Fexample.com%2Fpay%3Fparam%3Dabc%26token%3D%E4%B8%AD%E6%96%87

Calling the API ​

Before making API calls, ensure you have completed the following preparations:

1. Generate and Prepare RSA Keys ​

  • Algorithm: RSA
  • Key Format: PKCS#8
  • Key Length: At least 2048 bits
  • Requirements:
    1. Generate a key pair (public key and private key)
    2. Upload and configure your public key in the Diandian Pay platform
    3. Safely store your private key locally for signing requests

2. Obtain Merchant Information ​

  • Log in to Dashboard
  • Navigate to Settings (top-right) > Account Settings > Merchant > Retrieve merchant_id (unique merchant identifier)

Request Signing ​

The diagram below illustrates how to sign a request:

img

Step 1: Construct the String to Be Signed ​

The syntax for the string to be signed is:

plain
merchant_id.timestamp.timezone.request_body

Note: Values are concatenated using a period (.) in English.

  • merchant_id: Unique merchant identifier. Example: acct_8NRyElotSWv5F08m
  • timestamp: Required in the request header, representing the time the request was sent, accurate to the millisecond. Example: 1742308640331
  • timezone: Required in the request header, indicating the time zone of the timestamp. Example: Asia/Shanghai
  • request_body: The HTTP request body. See the example below:
json
{
    "merchant_id": "1",
    "env": {
        "terminal_type": "WEB",
        "client_ip": "143.45.4.222",
        "browser_info": {
            "user_agent": "Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 5.1; Trident/5.1)"
        }
    },
    "order": {
        "merchant_order_id": "99999999999",
        "shipping": {
            "shipping_name": {
                "first_name": "KING",
                "last_name": "MIsa",
                "full_name": "KING MIsa"
            },
            "shipping_address": {
                "country": "US",
                "state": "TX",
                "city": "Austin",
                "address1": "789 Oak Ave",
                "address2": "",
                "zip_code": "78701"
            },
            "email": "example@example.com",
            "phone": "+864-281-1794",
            "carrier": "USPS"
        },
        "payment_amount": {
            "currency": "USD",
            "value": 1000
        },
        "payment_method": {
            "payment_type": "CARD",
            "payment_data": {
                "country": "US",
                "card_number": "4111111111111111",
                "expiry_year": "30",
                "expiry_month": "03",
                "cvv": "737",
                "card_holder_name": {
                    "first_name": "KING",
                    "last_name": "MIsa",
                    "full_name": "KING MIsa"
                },
                "billing_address": {
                    "country": "US",
                    "state": "TX",
                    "city": "Austin",
                    "address1": "789 Oak Ave",
                    "address2": "",
                    "zip_code": "78701"
                },
                "requires_3ds": false
            }
        },
        "metadata": {
            "shop": "happy",
            "domain": "example.com"
        }
    },
    "redirect_url": "https://example.com/reutrn  "
}

Following the syntax above, the constructed string to be signed becomes:

json
acct_8NRyElotSWv5F08m.1742308640331.Asia/Shanghai.{"merchant_id":"1","env":{"terminal_type":"WEB","client_ip":"143.45.4.222","browser_info":{"user_agent":"Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 5.1; Trident/5.1)"}},"order":{"merchant_order_id":"99999999999","shipping":{"shipping_name":{"first_name":"KING","last_name":"MIsa","full_name":"KING MIsa"},"shipping_address":{"country":"US","state":"TX","city":"Austin","address1":"789 Oak Ave","address2":"","zip_code":"78701"},"email":"example@example.com","phone":"+864-281-1794","carrier":"USPS"},"payment_amount":{"currency":"USD","value":1000},"payment_method":{"payment_type":"CARD","payment_data":{"country":"US","card_number":"4111111111111111","expiry_year":"30","expiry_month":"03","cvv":"737","card_holder_name":{"first_name":"KING","last_name":"MIsa","full_name":"KING MIsa"},"billing_address":{"country":"US","state":"TX","city":"Austin","address1":"789 Oak Ave","address2":"","zip_code":"78701"},"requires_3ds":false}},"metadata":{"shop":"happy","domain":"example.com"}},"redirect_url":"https://example.com/reutrn  "}

Step 2: Generate the Signature ​

The syntax for generating the signature is:

plain
signature = base64_encode(sha256withRSA(<signed_string>, <private_key>))
  • signature: The resulting signature string.
  • base64_encode: Method to Base64-encode the digital signature.
  • sha256withrsa: Sign the provided content using the SHA-256 hashing algorithm and RSA private key.
  • signed_string: The string constructed in Step 1.
  • private_key: Your private key.

Example signature output:

plain
M8jbljAHTkw9Vn/4JnFvsrIQIxU98ktYUFAYVgKJ7403Td4I2J0Aq3Y4qy6u2Og+n9HpL8g9bU9OCcA+iEGPhYoB3uWVJuMtjFLvV6z/Yey2JbmK6gjVKap1CRGmlfzgHHx7Qdvrf6ExsULQMtFeRwp3iczmjuBcq1YhjfooNq5ktbq/oI4UO7DI1OjqCdb1ZBpD6ZgqLAmxuiIkYFUK4AmrpqhvE/jrAzWCVPotm9VoMB4iivVj+sUGOken0/s35YFYgD1PUZPBUAlMCfEr3seq9J/E+oRHSbBrgQPjw+Muv8VQ21K9rvRSf6oUt0rxNITzcnJl/Z9SgRIOsPPEXA==

Step 3: Add the Signature to the Request Header ​

Include the generated signature in the request header as follows:

http
signature: M8jbljAHTkw9Vn/4JnFvsrIQIxU98ktYUFAYVgKJ7403Td4I2J0Aq3Y4qy6u2Og+n9HpL8g9bU9OCcA+iEGPhYoB3uWVJuMtjFLvV6z/Yey2JbmK6gjVKap1CRGmlfzgHHx7Qdvrf6ExsULQMtFeRwp3iczmjuBcq1YhjfooNq5ktbq/oI4UO7DI1OjqCdb1ZBpD6ZgqLAmxuiIkYFUK4AmrpqhvE/jrAzWCVPotm9VoMB4iivVj+sUGOken0/s35YFYgD1PUZPBUAlMCfEr3seq9J/E+oRHSbBrgQPjw+Muv8VQ21K9rvRSf6oUt0rxNITzcnJl/Z9SgRIOsPPEXA==

Handling Responses ​

A response consists of response headers and a response body. Below are examples.

Response Headers Example ​

http
timezone: Asia/Shanghai
signature: h8zwMT0uBQJa/IDCg4ifIOchBFft9AvLkokjrrIiYtkf8fsk3A8wDqSdB2c66ks9gJqARafZ0MygnWOUU9NbVPCUixHvDFl8Z3238ADzhb29+S4S3fn7XTFV7DUtCMd9aFUvKLXGr6z4/GBog80yynGHDL6Ygjde7xI9D/x/OXiLOBGN1AuopTj7zL6TEvp/646T5PzZg8w9pnWA7r4ZxHplZrG0SKTLtZRloCtLk3kC3EwI0/m8obG4pptiPjY/8PuuLQUzbaPfd57wQP7tLUEhTr0LY2hSRYbdAtHwiPcmMY9QoW0rnHj/a/4nCqZNTrBwqiHJhdsKEZflA2KPjw==
timestamp: 1742311500484
DD-Request-Id: req_oVJMRLT7dzs8inRB9xYTYuLo

Response Body Example ​

json
{
    "data": {
        "id": "pi_aDNwWGfls1vcPLUHJDykYwmR",
        "amount": 7698,
        "result": {
            "result_code": "FAILED",
            "result_status": "F",
            "result_message": "card_velocity_exceeded"
        },
        "currency": "USD",
        "merchant_id": "acct_8NRyElotSW15F08m",
        "merchant_order_id": "21064044592225646561337"
    }
}

The following steps demonstrate how to verify Diandian Pay's response using the example above.

Step 1: Obtain Diandian Pay's Public Key ​

Go to Dashboard > Developers > API Keys > View Details to retrieve Diandian Pay's public key.

Step 2: Construct the String to Be Verified ​

The syntax is:

plain
merchant_id.timestamp.timezone.response_body
  • merchant_id: Merchant identifier, e.g., acct_8NRyElotSW15F08m
  • timestamp: From response header, accurate to milliseconds, e.g., 1742311500484
  • timezone: From response header, e.g., Asia/Shanghai
  • response_body: The HTTP response body

Constructed example:

plain
acct_8NRyElotSW15F08m.1742311500484.Asia/Shanghai.{"data":{"id":"pi_aDNwWGfls1vcPLUHJDykYwmR","amount":7698,"result":{"result_code":"FAILED","result_status":"F","result_message":"card_velocity_exceeded"},"currency":"USD","merchant_id":"acct_8NRyElotSW15F08m","merchant_order_id":"21064044592225646561337"}}

Step 3: Extract Signature from Response Header ​

Retrieve the signature from the signature field in the response header.

Step 4: Verify the Signature ​

The verification syntax is:

plain
is_signature_valid = sha256withrsa_verify_signature(<signed_string>, base64_decode(received_signature), <public_key>)
  • is_signature_valid: A boolean value indicating whether the signature is valid.
    • true: Signature is valid.
    • false: Signature is invalid. Possible causes include mismatched key pairs or incorrect construction of the signed string.
  • sha256withrsa_verify_signature: The method to verify the RSA signature using SHA-256.
  • base64_decode: Decode the received Base64-encoded signature.
  • received_signature: The signature obtained in Step 3.
  • public_key: Diandian Pay's public key obtained in Step 1.