Adyen POS本地集成：向终端发送metadata并在Webhook接收的问题

1. 确保请求结构符合Adyen规范 #

Adyen对SaleToAcquirerData的格式有严格要求，metadata必须以URL编码的键值对格式传递（部分场景支持JSON字符串，但URL编码是通用兼容方式），且键名需以metadata.前缀开头。

示例支付请求结构（Terminal API/Checkout API）：

{
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "reference": "ORD-2024-001",
  "paymentMethod": {
    "type": "POS"
  },
  "saleToAcquirerData": "metadata.orderId=ORD-2024-001&metadata.customerEmail=user@example.com",
  "terminalId": "YOUR_TERMINAL_ID"
}

注意：若使用JSON格式，需先将metadata对象转为字符串再进行URL编码，比如{"metadata":{"orderId":"ORD-2024-001"}}编码后为%7B%22metadata%22%3A%7B%22orderId%22%3A%22ORD-2024-001%22%7D%7D。

2. 验证终端与SDK兼容性 #

• 旧款Adyen终端（如V200s旧固件）可能不支持传递metadata字段，需升级终端至最新固件版本（可通过Adyen后台Devices > Terminals页面操作）。
• 若使用Adyen POS SDK集成，确保SDK版本为最新，避免版本兼容问题导致字段丢失。

3. 配置Webhook接收metadata #

• 登录Adyen后台，进入Webhooks配置页，确认订阅的事件（如AUTHORISATION、CAPTURE）已开启additionalData字段返回。metadata会被映射到Webhook响应的additionalData节点下，键名保留metadata.前缀。
  示例Webhook响应片段：

{
  "eventCode": "AUTHORISATION",
  "additionalData": {
    "metadata.orderId": "ORD-2024-001",
    "metadata.customerEmail": "user@example.com"
  }
}

• 确保Webhook签名验证配置正确，错误的签名设置可能导致Adyen截断部分响应字段。

4. 正确查询后台metadata #

在Adyen后台查询订单时，需进入Transactions页面找到对应订单，点击Details标签，在Additional data区域查看metadata字段——基础订单信息页面默认不展示该内容。

5. 调试与日志排查 #

• 使用Adyen测试环境进行验证，在后台Developers > Logs中查看请求详情，确认发送的SaleToAcquirerData字段完整且格式正确，未被截断或修改。
• 检查API响应中的additionalData节点，若响应中无metadata，说明终端未接收并传递该字段，需重新检查请求结构或终端兼容性。

内容的提问来源于stack exchange，提问作者nhat tran khan