# 签名与验签

> 所有请求使用 HMAC-SHA256 签名，HansaPay 的响应与通知也按同样规则验签。

## 认证方式

所有商户主动调用 HansaPay 系统的接口都必须携带以下请求头：

- `X-MerchantID`
- `X-Timestamp`
- `X-Nonce`
- `X-Sign`

签名算法：

- `HMAC-SHA256`
- 输出格式：十六进制小写字符串

## 字符编码与请求格式

- 请求方法：`POST`
- Content-Type：`application/json`
- 请求体必须参与签名
- 签名时使用原始 JSON 字节串
- 不要对 JSON 做二次美化、trim、字段重排后再验签

## 请求签名规则

### 待签名字符串

HansaPay 系统按以下格式验签：

```text
merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawBody
```

例如：

```text
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":"john@example.com","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"}
```

### 签名计算

伪代码：

```text
sign = hex_lower( HMAC_SHA256(secret_key, sign_payload) )
```

其中：

- `merchantID`：HansaPay 系统分配的商户号
- `secret_key`：HansaPay 系统分配的商户 API 密钥
- `timestamp`：Unix 秒级时间戳
- `nonce`：随机字符串，建议 16 到 32 位
- `rawBody`：HTTP 原始请求体字符串

### Java 示例

```java
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 示例

```php
<?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 示例

```go
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)
}
```

### 请求头示例

```http
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: 7f7d6e3d2baf9b9bd0e4d8d9a5d2c8d9f7c4e1a2b3c4d5e6f708091011121314
```

## HansaPay 系统响应验签

商户也应对 HansaPay 系统的响应验签。响应头使用同样的键：

- `X-MerchantID`
- `X-Timestamp`
- `X-Nonce`
- `X-Sign`

验签规则：

```text
merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawResponseBody
```

说明：

- 响应 body 也必须按原始字符串参与验签
- 不要先反序列化再重新序列化后验签
- 如验签失败，应视为响应不可信
- `401` 与 `403` 鉴权错误不带签名

## 签名失败排查清单

当 HansaPay 系统返回以下错误时，优先检查签名链路：

- `401`，`Missing authentication headers` 或 `Merchant ID not found or invalid`
- `403`，`Invalid signature`

建议按下面顺序排查：

### 商户号是否正确

- `X-MerchantID` 必须使用 HansaPay 系统分配的商户号
- 不要传商户名称、登录账号或内部用户 ID

### 密钥是否正确

- 确认使用的是商户 API 密钥，不是登录密码
- 确认没有多环境混用
- 测试环境和生产环境密钥通常不同

### 待签名字符串是否完全一致

HansaPay 系统验签格式固定为：

```text
merchantID + "\n" + timestamp + "\n" + nonce + "\n" + rawBody
```

常见错误：

- 少了换行符
- 使用了 `\r\n` 而不是 `\n`
- header 顺序拼错
- body 前后被 trim
- body 不是原始字符串，而是对象重新序列化后的字符串

### JSON 字段名是否写错

商户接口使用的是 snake_case，例如：

- `payment_method`
- `merchant_order_no`
- `notify_url`
- `trade_info.goods_name`

不要混用旧字段名：

- `paymentMethod`
- `merchantOrderNo`
- `goodsName`

### JSON 是否被二次格式化

签名必须基于实际发出的原始 body。

例如这两段 JSON 业务上等价，但签名结果不同：

```json
{"order_no":"O1","status":"SUCCESS"}
```

```json
{
  "order_no": "O1",
  "status": "SUCCESS"
}
```

因此：

- 先生成最终请求 body
- 再用这段最终 body 去签名
- 不要签名之后再改空格、缩进或字段顺序

### 时间戳是否异常

- `X-Timestamp` 必须使用秒级 Unix 时间戳
- 不要传毫秒
- 不要传格式化时间字符串
- HansaPay 可能拒绝 `X-Timestamp` 与当前时间相差超过几分钟的请求，返回 HTTP `401` 和 `Request expired`。请保持服务器时间同步（NTP），并在发送前即时签名
- 在同一检查下，`X-Nonce` 只能使用一次：以相同 nonce 重发的请求会以 HTTP `401` 拒绝。每次重试都请用新的 nonce 重新签名

正确示例：

```text
1719200000
```

错误示例：

```text
1719200000123
2026-06-24T10:00:00+08:00
```

### `nonce` 是否为空

- `X-Nonce` 不能为空
- 建议 16 到 32 位随机字符串，最长 128 位
- 每个请求（包括重试）都使用新的 nonce（见 [时间戳是否异常](https://www.hansapay.io/docs/zh/authentication#is-the-timestamp-valid)）

### HMAC 输出格式是否正确

HansaPay 系统要求：

- 算法：`HMAC-SHA256`
- 输出：十六进制小写字符串

不要使用：

- Base64
- 十六进制大写
- MD5
- RSA

### Content-Type 是否正确

请使用：

```text
Content-Type: application/json
```

### 验签失败时建议记录的日志

商户本地建议打印：

- `merchant_id`
- `timestamp`
- `nonce`
- `raw_body`
- `sign_payload`
- `received_sign`
- `expected_sign`

这样可以最快定位是 header 问题、body 格式问题还是密钥问题。

### 金额限制错误排查

如果 HansaPay 系统返回：

- `2006`：代收金额不满足通道限制
- `5008`：代付金额不满足通道限制

请检查：

1. `trans_amount.value` 是否低于当前可用通道最小限额
2. `trans_amount.value` 是否高于当前可用通道最大限额
3. 当前支付方式下，商户已启用通道是否都不接受该金额
4. 这类错误与签名无关，通常不需要排查 `X-Sign`
