Getting started
中文Authentication
Sign every request with HMAC-SHA256, and verify every response and notification the same way.
Authentication
All merchant-initiated requests to HansaPay must include these headers:
X-MerchantIDX-TimestampX-NonceX-Sign
Signature algorithm:
HMAC-SHA256- Output format: lowercase hex string
Encoding and Request Format
- HTTP method:
POST - Content-Type:
application/json - The request body must be included in the signature
- Use the raw JSON body bytes when signing
- Do not prettify, trim, or reorder JSON fields before verifying
Request Signing Rules
String to Sign
HansaPay verifies signatures using:
merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawBodyExample:
M123456
1719200000
8f31a2bc9d4e6f70
{"payment_method":"CARD","merchant_order_no":"M202406240001","trans_amount":{"currency":"USD","value":"99.99"},"notify_url":"https://merchant.example.com/callback/payment","trade_info":{"goods_name":"VIP","description":"Monthly subscription"},"card":{"card_number":"4111111111111111","cardholder_name":"JOHN DOE","exp_month":12,"exp_year":2028,"cvc":"123"},"billing_address":{"country":"US","first_name":"John","last_name":"Doe","email":"[email protected]","phone":"15551234567","state":"CA","city":"San Francisco","address":"Market Street","street_number":"1355","postal_code":"94103"},"device_ip":"203.0.113.10","metadata":"biz=member"}Signature Calculation
Pseudo-code:
sign = hex_lower( HMAC_SHA256(secret_key, sign_payload) )Where:
merchantID: merchant ID assigned by HansaPaysecret_key: merchant API secret assigned by HansaPaytimestamp: Unix timestamp in secondsnonce: random string, recommended length 16 to 32rawBody: raw HTTP request body string
Java Example
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
public class SignDemo {
public static String hmacSha256Hex(String data, String secret) throws Exception {
Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
mac.init(keySpec);
byte[] raw = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder();
for (byte b : raw) {
sb.append(String.format("%02x", b));
}
return sb.toString();
}
public static void main(String[] args) throws Exception {
String merchantId = "M123456";
String timestamp = "1719200000";
String nonce = "8f31a2bc9d4e6f70";
String rawBody = "{\"order_no\":\"O202406240001\"}";
String secret = "your_merchant_secret";
String payload = merchantId + "\n" + timestamp + "\n" + nonce + "\n" + rawBody;
String sign = hmacSha256Hex(payload, secret);
System.out.println(sign);
}
}PHP Example
<?php
$merchantId = 'M123456';
$timestamp = '1719200000';
$nonce = '8f31a2bc9d4e6f70';
$rawBody = '{"order_no":"O202406240001"}';
$secret = 'your_merchant_secret';
$payload = $merchantId . "\n" . $timestamp . "\n" . $nonce . "\n" . $rawBody;
$sign = hash_hmac('sha256', $payload, $secret);
echo $sign . PHP_EOL;Go Example
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
)
func main() {
merchantID := "M123456"
timestamp := "1719200000"
nonce := "8f31a2bc9d4e6f70"
rawBody := `{"order_no":"O202406240001"}`
secret := "your_merchant_secret"
payload := merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawBody
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(payload))
sign := hex.EncodeToString(mac.Sum(nil))
fmt.Println(sign)
}Example Headers
POST /api/v1/payments/query HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-MerchantID: M123456
X-Timestamp: 1719200000
X-Nonce: 8f31a2bc9d4e6f70
X-Sign: 7f7d6e3d2baf9b9bd0e4d8d9a5d2c8d9f7c4e1a2b3c4d5e6f708091011121314Verifying HansaPay System Responses
Merchants should also verify signatures on HansaPay responses. Response headers use the same keys:
X-MerchantIDX-TimestampX-NonceX-Sign
Verification rule:
merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawResponseBodyNotes:
- The response body must also be verified using the raw body string
- Do not deserialize and reserialize before verification
- If verification fails, the response should be treated as untrusted
401and403authentication errors are not signed
Signature Troubleshooting Checklist
When HansaPay returns the following errors, check the signing chain first:
401withMissing authentication headersorMerchant ID not found or invalid403withInvalid signature
Recommended troubleshooting order:
Is the Merchant ID Correct
X-MerchantIDmust be the merchant ID assigned by HansaPay- Do not send merchant name, login account, or internal user ID
Is the Secret Correct
- Make sure you are using the merchant API secret, not the login password
- Make sure you are not mixing environments
- Test and production secrets are usually different
Is the String to Sign Exactly the Same
HansaPay always verifies:
merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawBodyCommon mistakes:
- Missing line breaks
- Using
\r\ninstead of\n - Wrong header order
- Trimming body content
- Signing a reserialized object instead of the raw body
Are the JSON Field Names Correct
The merchant API uses snake_case, for example:
payment_methodmerchant_order_nonotify_urltrade_info.goods_name
Do not mix old-style names such as:
paymentMethodmerchantOrderNogoodsName
Was the JSON Reformatted
The signature must be based on the exact request body sent over the wire.
These two JSON payloads are business-equivalent but produce different signatures:
{"order_no":"O1","status":"SUCCESS"}{
"order_no": "O1",
"status": "SUCCESS"
}Therefore:
- Build the final request body first
- Sign that final body
- Do not modify spaces, indentation, or field order after signing
Is the Timestamp Valid
X-Timestampmust be a Unix timestamp in seconds- Do not send milliseconds
- Do not send a formatted datetime string
- HansaPay may refuse a request whose
X-Timestampis more than a few minutes from the current time, with HTTP401andRequest expired. Keep your server clock synchronised (NTP) and sign each request just before sending it - Under the same check an
X-Noncecan be used only once: a request sent again with the same nonce is refused with HTTP401. Sign every retry again with a new nonce
Valid example:
1719200000Invalid examples:
1719200000123
2026-06-24T10:00:00+08:00Is nonce Empty
X-Noncemust not be empty- Recommended length: 16 to 32 random characters, at most 128
- Use a new nonce for every request, including retries (see Is the Timestamp Valid)
Is the HMAC Output Format Correct
HansaPay expects:
- Algorithm:
HMAC-SHA256 - Output: lowercase hex string
Do not use:
- Base64
- Uppercase hex
- MD5
- RSA
Is the Content-Type Correct
Use:
Content-Type: application/jsonSuggested Logs When Verification Fails
Recommended local logs:
merchant_idtimestampnonceraw_bodysign_payloadreceived_signexpected_sign
This is the fastest way to determine whether the issue comes from headers, body formatting, or the secret.
Amount Limit Troubleshooting
If HansaPay returns:
2006: collection amount does not satisfy channel limits5008: payout amount does not satisfy channel limits
Check:
- Whether
trans_amount.valueis below the current minimum allowed by the available channel - Whether
trans_amount.valueis above the current maximum allowed by the available channel - Whether all enabled channels for the current payment method reject that amount
- These errors are not signature-related, so
X-Signusually does not need investigation
