commercetools-adyen-integration-notification 镜像文档

镜像概述

commercetools-adyen-integration-notification 是 commercetools 电商平台与 Adyen 支付网关的通知集成服务镜像。该镜像提供了接收、验证、处理 Adyen 支付通知的能力，并将支付状态同步至 commercetools 平台，确保支付流程中的状态一致性，是电商交易流程中连接支付通知与订单管理的关键组件。

核心功能与特性

核心功能

• Adyen 通知接收与验证：监听并接收 Adyen 发送的支付通知，通过 HMAC 签名验证通知的真实性，防止恶意请求
• 支付状态解析与同步：解析 Adyen 通知中的支付状态（如支付成功、失败、退款等），并同步至 commercetools 订单/支付资源
• 错误处理与重试：对处理失败的通知提供重试机制，支持可配置的重试策略（次数、间隔）
• 日志与监控：提供详细的处理日志，支持集成外部监控系统（如 Prometheus）

关键特性

• 高兼容性：支持 Adyen 标准通知格式及 commercetools 最新 API 版本
• 可配置性：通过环境变量灵活配置连接参数、重试策略等
• 轻量级：基于 Java 微服务架构，资源占用低，部署便捷

使用场景

• 电商平台支付流程闭环：在集成 Adyen 作为支付方式的 commercetools 电商平台中，实时处理支付通知以更新订单状态（如从"待支付"变为"已支付"）
• 支付异常处理：自动处理支付通知超时、格式错误等异常情况，减少人工干预
• 财务对账支持：通过准确的状态同步，为财务对账提供可靠的支付状态数据

使用方法与配置说明

前提条件

• 已部署 commercetools 平台，获取项目密钥（Project Key）、API 凭证（Client ID/Secret）
• 已在 Adyen 平台配置支付通知端点（需指向该服务的访问地址），并获取 Adyen API Key、通知 HMAC Key

Docker 快速启动

基本运行命令

docker run -d \
  -p 8080:8080 \
  -e COMMERCETOOLS_PROJECT_KEY="your-commercetools-project-key" \
  -e COMMERCETOOLS_CLIENT_ID="your-client-id" \
  -e COMMERCETOOLS_CLIENT_SECRET="your-client-secret" \
  -e COMMERCETOOLS_API_URL="[***]{region}.com" \
  -e ADYEN_API_KEY="your-adyen-api-key" \
  -e ADYEN_NOTIFICATION_HMAC_KEY="your-adyen-notification-hmac-key" \
  -e PORT=8080 \
  commercetools/commercetools-adyen-integration-notification:latest

Docker Compose 配置示例

version: '3.8'
services:
  adyen-notification-service:
    image: commercetools/commercetools-adyen-integration-notification:latest
    ports:
      - "8080:8080"
    environment:
      - COMMERCETOOLS_PROJECT_KEY=your-commercetools-project-key
      - COMMERCETOOLS_CLIENT_ID=your-client-id
      - COMMERCETOOLS_CLIENT_SECRET=your-client-secret
      - COMMERCETOOLS_API_URL=[***]
      - COMMERCETOOLS_AUTH_URL=[***]
      - ADYEN_API_KEY=your-adyen-api-key
      - ADYEN_NOTIFICATION_HMAC_KEY=your-adyen-notification-hmac-key
      - ADYEN_MERCHANT_ACCOUNT=your-adyen-merchant-account
      - PORT=8080
      - RETRY_MAX_ATTEMPTS=3
      - RETRY_INITIAL_DELAY_MS=1000
      - LOG_LEVEL=INFO
    restart: unless-stopped

环境变量配置

通知端点配置

Adyen 平台需配置通知端点为该服务的访问地址，格式为：
http://<服务IP或域名>:<PORT>/notifications

例如：[***]

注意事项

• 确保服务可被 Adyen 服务器访问（公网可达或通过 ***/专线连接）
• HMAC 密钥需与 Adyen 平台配置完全一致，否则通知验证会失败
• 生产环境建议配置 HTTPS（可通过反向代理如 Nginx 实现）
• 建议配合监控工具（如 Prometheus + Grafana）监控服务健康状态及通知处理成功率