madhukodali23/Adyen-Hosted-Form-Integration-with-Payment-and-Refund-Webhook-Handling

# Adyen 托管支付集成：Webhook、退款与 AWS Serverless 部署 ## 项目概述 本项目使用 Adyen Drop-in 集成实现了一套完整的端到端支付处理系统。该应用程序支持安全支付处理、webhook 处理、退款功能、HMAC 验证、AWS Serverless 部署、幂等性处理以及云数据库持久化。 该系统展示了一种生产级支付架构，包含安全的 webhook 验证、云端 MySQL 数据库集成、前端/后端部署，以及 Adyen Web v6 支付流程处理。 # 功能特性 - Adyen Drop-in 支付集成 - 使用 Adyen Sessions API 创建支付会话 - AUTHORISATION webhook 处理 - REFUND webhook 处理 - 用于保障 webhook 安全的 HMAC 签名验证 - AWS Lambda Serverless 后端部署 - AWS API Gateway 集成 - AWS SSM Parameter Store 密钥管理 - 使用 Railway 集成云 MySQL 数据库 - Refund API 实现 - 支付与退款持久化 - 使用 UNIQUE 约束进行幂等性处理 - 成功与失败支付处理 # 系统架构 ``` Frontend (React + Adyen Drop-in) ↓ Backend API (Node.js + Express) ↓ AWS Lambda + API Gateway ↓ Adyen Payment Gateway ↓ Webhook Events ↓ Webhook Verification using HMAC ↓ Cloud MySQL Database (Railway) ``` # 支付流程 ``` 1. Frontend requests payment session from backend 2. Backend calls Adyen Sessions API 3. Session response returned to frontend 4. Adyen Drop-in rendered on frontend 5. User enters card details 6. Adyen processes payment 7. Adyen triggers AUTHORISATION webhook 8. Backend validates HMAC signature 9. Payment details stored in payments table 10. Frontend navigates to success/failure page ``` # 失败处理流程 ``` 1. Payment gets refused by Adyen 2. Adyen Web v6 triggers onPaymentFailed callback 3. Frontend redirects to failure page 4. Adyen sends failure webhook event 5. Backend validates HMAC signature 6. Failed payment stored in database ``` # 退款流程 ``` 1. Refund API called with payment PSP reference 2. Backend sends refund request to Adyen 3. Adyen processes refund 4. Adyen triggers REFUND webhook 5. Backend validates HMAC signature 6. Refund details stored in refunds table ``` # 技术栈 ## 前端 - React.js - Adyen Web Drop-in - Axios ## 后端 - Node.js - Express.js - MySQL2 ## 数据库 - MySQL - Railway Cloud 数据库 ## 云服务与部署 - AWS Lambda - AWS API Gateway - AWS SSM Parameter Store - Serverless Framework - Vercel ## 支付网关 - Adyen # 数据库结构 ## payments 表 ``` CREATE TABLE payments ( id SERIAL PRIMARY KEY, transactionId VARCHAR(255), merchantReference VARCHAR(255), status VARCHAR(100), amount INTEGER, createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` ## refunds 表 ``` CREATE TABLE refunds ( id SERIAL PRIMARY KEY, refundId VARCHAR(255), paymentId VARCHAR(255), status VARCHAR(100), refundAmount INTEGER, createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` # API Endpoints ## 创建支付会话 ``` POST /create-payment-session ``` 创建 Adyen 支付会话并将 session 详情返回给前端。 ## Webhook Endpoint 处理： - AUTHORISATION 事件 - REFUND 事件 执行： - HMAC 验证 - 支付持久化 - 退款持久化 - 重复事件处理 ## 退款 API ``` POST /refund ``` 请求体： ``` { "paymentPspReference": "PAYMENT_REFERENCE" } ``` 通过 Adyen 触发退款请求。 # Adyen Web v6 支付处理 ## 成功支付 处理方式： ``` onPaymentCompleted ``` ## 失败支付 处理方式： ``` onPaymentFailed ``` 重要经验： 在 Adyen Web v6 中，被拒绝或取消的支付会通过 `onPaymentFailed` 回调单独处理，而不是使用 `onPaymentCompleted`。 # AWS SSM Parameter Store 敏感信息使用 AWS Systems Manager (SSM) Parameter Store 进行了安全存储。 示例： - Adyen API 密钥 - HMAC 密钥 - 数据库凭证 优势： - 安全的密钥管理 - 避免硬编码凭证 - 集中化的配置管理 # 安全特性 - 实现了 HMAC webhook 验证 - 基于环境变量的密钥管理 - 使用 Adyen HMAC 验证器进行安全的 webhook 验证 - 支持 SSL 的云数据库集成 - AWS SSM 安全参数管理 - 针对 webhook 重试的幂等性处理 # 幂等性处理 为了防止重复处理 webhook 和产生重复的交易记录，我们通过在交易和退款标识符上设置 UNIQUE 约束实现了幂等性处理。 ## payments 表 UNIQUE 约束 ``` ALTER TABLE payments ADD CONSTRAINT unique_transaction UNIQUE (transactionId); ``` ## refunds 表 UNIQUE 约束 ``` ALTER TABLE refunds ADD CONSTRAINT unique_refund UNIQUE (refundId); ``` ## 为什么需要幂等性 像 Adyen 这样的支付网关可能会由于以下原因多次重试 webhook 投递： - 网络故障 - 超时问题 - 投递确认失败 如果不进行幂等性处理，重复的 webhook 事件可能会在数据库中创建多条支付或退款记录。 # 部署 ## 前端 部署方式： - Vercel ## 后端 部署方式： - AWS Lambda - API Gateway - Serverless Framework ## 数据库 托管在 Railway MySQL 上。 # 遇到的挑战 - 理解 Adyen Web v6 的回调行为 - 触发和处理支付失败场景 - 明确被拒绝的支付需使用 onPaymentFailed 回调处理 - 理解 Adyen 文档及测试模拟行为 - Webhook 同步 - AWS Serverless 部署 - MySQL 连接配置 - HMAC 验证的实现 # 未来改进 - 3D Secure (3DS) 身份验证集成 - 基于 OTP 的支付验证 - 实时支付状态追踪 - 基于 WebSocket 的更新 - 欺诈检测系统 - 监控与日志仪表板 - 数据分析仪表板 - 多支付网关支持 # 测试卡信息 ## 成功支付 ``` Card Number: 4111 1111 1111 1111 Expiry: 03/30 CVV: 737 Card Holder Name: John Smith ``` ## 拒绝支付 ``` Card Number: 4111 1111 1111 1111 Expiry: 03/30 CVV: 737 Card Holder Name: REFUSED ``` # 3D Secure (3DS) 3D Secure 是在线支付过程中使用的一种附加身份验证层。 示例： - OTP 验证 - 银行身份验证页面 - 生物识别验证 优势： - 减少欺诈 - 增强支付安全性 - 改善交易身份验证 该架构已为未来使用 Adyen Sessions Flow 集成 3DS 做好准备。 # 结论 本项目演示了使用 Adyen 构建的生产级支付集成系统，包含： - 安全的 webhook 验证 - AWS Serverless 部署 - 退款处理 - 数据库持久化 - 基于 HMAC 的 webhook 安全 - 使用 Adyen Web v6 的失败处理 - 幂等 webhook 处理 - 云原生支付架构 该实现涵盖了现实世界中的支付网关概念，包括支付授权、webhook 系统、安全的云端部署、退款工作流以及可扩展的后端架构。

标签：Adyen集成, AWS Serverless, MITM代理, Webhook处理, 支付网关, 自定义脚本