跳到主要内容

通过 Adyen 使用卡支付

通过 Adyen 的安全支付处理平台接受信用卡和借记卡支付。此集成支持所有主要卡网络，具有高级欺诈保护和 3D Secure 身份验证。

设置​

请按照通用的 Adyen 说明 来设置 Adyen。

功能​

设置 Adyen 账户后，我们建议您在开发者区域配置以下内容，以便使用所有功能。前往 Adyen 仪表板的 Developers -> Additional data，然后确保选择以下字段。

  • 定期详情
  • 原始收单结果
  • 支付账户参考

集成​

API 请求​

curl --request POST \
  --url https://api.efundpay.com/v4/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'x-merchant-account-id: <x-merchant-account-id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": {
      "currency": "USD",
      "value": 2500
    },
    "payment_method": {
      "method": "adyen",
      "payment_method_data": {
        "type": "scheme",
        "encrypted_card_number": "test_4111111111111111",
        "encrypted_expiry_month": "test_03",
        "encrypted_expiry_year": "test_2030",
        "encrypted_security_code": "test_737"
      },
      "browser_info": {
        "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
        "color_depth": 24,
        "language": "en-US",
        "java_enabled": false,
        "screen_height": 1080,
        "screen_width": 1920,
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
      }
    },
    "external_identifier": "order-12345"
  }'

支付流程​

  1. 初始化支付 - 通过 EFundPay 创建支付请求
  2. 客户端加密 - 使用 Adyen 的 JavaScript 库加密卡数据
  3. 支付处理 - Adyen 处理支付
  4. 3D Secure - 处理所需的 3D Secure 身份验证
  5. Webhook 通知 - 通过 webhook 接收支付状态
  6. 最终结果 - 处理成功/失败响应

配置​

必需参数​

  • amount.currency - 三字母 ISO 货币代码
  • amount.value - 最小货币单位的支付金额
  • payment_method_data.type - 卡支付设置为 "scheme"
  • encrypted_card_number - 加密的卡号
  • encrypted_expiry_month - 加密的到期月份
  • encrypted_expiry_year - 加密的到期年份
  • encrypted_security_code - 加密的安全代码（CVV）

可选参数​

  • browser_info - 用于欺诈检测的浏览器信息
  • billing_address - 客户账单地址
  • shipping_address - 客户配送地址
  • merchant_order_id - 您的内部订单参考

自动救援​

此连接器支持 Adyen 的自动救援功能。当客户不在场的卡交易在第一次请求时被拒绝时，此功能将自动重试。要启用此功能，在发出后续支付请求时为 Adyen 传入以下连接选项。

POST /transactions

{
    "amount": 1299,
    "country": "US",
    "currency": "USD",
    "intent": "capture",
    "payment_method": {
        "method": "id",
        "id": "7f6fb9ca-eb1c-42c6-9b65-8f1c699b84bd"
    },
    "connection_options": {
        "adyen-card": {
            "autoRescue": true,
            "maxDaysToRescue": 5
        }
    },
    "payment_source": "card_on_file",
    "is_subsequent_payment": true,
    "merchant_initiated": true
}

请注意，此功能仅适用于 is_subsequent_payment 设置为 true 的客户不在场交易。

需要设置以下字段。

  • autoRescue - 启用该功能的布尔值。默认为 false。
  • maxDaysToRescue - 救援窗口，以天为单位。您可以指定 1 到 48 天。Adyen 建议使用一个日历月（30 天）的救援窗口。
  • autoRescueScenario - 这是 Adyen 定义的测试场景之一。这只在沙盒中有效。请注意，这些测试场景中来自 Adyen 的 webhook 可能需要几分钟才能到达。

当交易被接受使用此功能进行自动重试时，我们会将交易标记为 processing。当我们收到成功支付或最终拒绝的 webhook 时，我们将相应地更新状态。

对于自动救援功能，确保 Adyen 已设置为以 JSON 格式发送 webhook 很重要。

支付/原始信用交易​

此连接器支持 Adyen Transfers API 以启用支付/原始信用交易。此功能需要在您的 Adyen 账户中启用才能工作。您还需要在仪表板中 Adyen 连接的配置中提供余额账户 ID。您的支付将从此余额账户中提供资金。

响应处理​

成功响应​

{
  "type": "transaction",
  "id": "txn_123456789",
  "status": "processing",
  "psp_reference": "8535296650153317",
  "result_code": "Authorised",
  "external_identifier": "order-12345"
}

Webhook 通知​

{
  "ll_transaction_id": "2022012601122644",
  "merchant_transaction_id": "order-12345",
  "payment_data": {
    "payment_status": "SUCCEEDED",
    "payment_amount": "25.00",
    "payment_currency_code": "USD",
    "payment_time": "20220126141430",
    "adyen_psp_reference": "8535296650153317",
    "result_code": "Authorised"
  }
}

客户端集成​

Adyen Web 组件​

// 加载 Adyen Web 组件
const checkout = await AdyenCheckout({
  environment: 'test',
  clientKey: 'test_...',
  paymentMethodsResponse: paymentMethodsResponse,
  onSubmit: (state, component) => {
    // 处理支付提交
    makePayment(state.data);
  },
  onAdditionalDetails: (state, component) => {
    // 处理 3D Secure
    makeDetailsCall(state.data);
  }
});

// 挂载组件
checkout.create('card').mount('#card-container');

支付提交​

async function makePayment(paymentData) {
  try {
    const response = await fetch('/api/payments', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(paymentData),
    });
    
    const result = await response.json();
    handlePaymentResult(result);
  } catch (error) {
    console.error('支付失败:', error);
  }
}

测试​

测试卡​

Adyen 提供各种测试卡号：

  • 成功: 4212345678901247
  • 拒绝: 4212345678901254
  • 3D Secure: 4212345678901247
  • 余额不足: 4212345678901254

测试环境​

  • 开发时使用测试 API 密钥
  • 使用 Adyen 的测试商户账户
  • 在测试模式下验证 webhook 通知
  • 测试 3D Secure 流程

安全考虑​

PCI 合规​

  • Adyen 处理卡数据的 PCI 合规
  • 使用 Adyen 的客户端加密
  • 切勿存储原始卡数据
  • 实施适当的 webhook 签名验证

欺诈预防​

  • 启用 Adyen 的风险管理工具
  • 实施 3D Secure 身份验证
  • 监控可疑活动
  • 使用 Adyen 的欺诈检测功能

常见问题​

支付失败​

  • 卡被拒绝 - 检查卡详情和资金
  • 需要 3D Secure - 实施 3D Secure 流程
  • 无效金额 - 确保金额格式正确
  • 货币不匹配 - 验证货币设置

集成问题​

  • 未收到 Webhook - 检查 webhook 端点和签名
  • 加密错误 - 验证客户端加密设置
  • 无效 API 密钥 - 验证 API 密钥配置

最佳实践​

用户体验​

  • 实施适当的加载状态
  • 显示清晰的错误消息
  • 提供多种支付选项
  • 针对移动设备进行优化

技术实施​

  • 使用 webhook 进行实时更新
  • 实施适当的错误处理
  • 存储支付参考
  • 优雅地处理网络故障

安全​

  • 始终使用 HTTPS
  • 验证 webhook 签名
  • 实施适当的会话管理
  • 定期安全审计

支持​

如需通过 Adyen 集成卡支付的技术支持：

  • EFundPay 支持 - 联系我们的技术团队
  • Adyen 支持 - 使用 Adyen 的支持资源
  • Adyen 文档 - 全面的 API 文档

相关文档​

Powered by Docusaurus