跳转到主要内容

集成概览

Quick Reference

What接入支付的集成模式
Why选择与您的技术需求、UX（用户体验）需求和时间线匹配的路径
Reading Time7 分钟
Difficulty初级
Prerequisites身份验证 → 环境配置

为什么这个决策很重要​

您选择的集成模式决定了卡片数据如何流转。它也决定了谁负责卡数据安全，以及谁处理 3DS（3D Secure 验证）。后期更换模式意味着重新架构。花 7 分钟做好决策，可为您节省数周的工作。

错误选择后果
不需要完全服务器端控制时选择 H2H（Host-to-Host 直连）增加不必要的复杂性——A55 通过 SDK（软件开发工具包）或收银台页面为您处理卡数据安全
需要完全服务端控制时选择 SDK您会与 SDK 对抗而非借力
需要像素级 UX（用户体验）控制时选择收银台页面您将失去对支付体验的控制

对比矩阵​

维度H2H（服务器直连）SDK（嵌入式）收银台页面（重定向）
集成时间数周数天数小时
卡数据处理您的服务器——完全服务器端控制SDK 处理卡片字段——A55 保障安全完全由 A55 管理
UX 控制力完全——每个像素由您掌控高——原生收银体验，SDK 处理 3DS有限——A55 托管页面
谁处理卡片数据您的服务器浏览器端 SDKA55 托管页面
谁执行 3DS您（处理 url_3ds）SDK（无摩擦 + 挑战）A55（端到端）
适合场景需要完全服务器端控制的团队原生收银体验、减少 3DS 工作量最快上线、完全由 A55 管理

决策树​

速查规则
  • 数小时内上线？ → 收银台页面
  • 原生 UX，A55 处理卡数据安全？ → SDK
  • 完全服务器端控制？ → H2H

1. H2H（服务器直连）​

您的后端直接向 A55 发送卡片数据、客户字段和 3DS 载荷。

您负责： 卡片采集、HTTPS 传输、3DS 挑战重定向、Webhook（网络钩子）处理。

A55 负责： 收单路由、授权、Webhook 投递。

优势权衡
完全掌控支付的每个步骤您负责采集卡数据后发送至 A55
自定义重试逻辑和错误处理3DS 挑战流程需要前端配合
可直接使用所有 API（应用程序编程接口）参数集成周期最长

2. SDK（嵌入式前端）​

在您的收银页面嵌入 A55 JavaScript SDK。SDK 负责采集卡片数据、处理 3DS 并返回结果。

您负责： 后端创建收款、前端初始化 SDK、Webhook 处理。

SDK 负责： 卡片字段渲染、设备指纹采集、3DS 无摩擦/挑战路由、异步回调。

优势权衡
原生收银体验——SDK 渲染在您的页面中需要集成和测试 SDK 生命周期
A55 保障卡数据安全——卡片数据不经过您的服务器灵活性不及原始 H2H
3DS 由 SDK 自动处理需要前端 JavaScript 集成

3. 收银台页面（重定向）​

使用最少的数据创建收款，然后将付款人重定向至 A55 的托管页面。卡片采集、3DS 和支付完成均在该页面上进行。

您负责： 创建收款、重定向、回调 URL 处理、Webhook 处理。

A55 负责： 其余一切——卡片采集、3DS、支付完成、托管 UI。

优势权衡
最快上线——数小时内投产对支付 UX 的控制较少
A55 全面处理卡数据安全重定向会将用户带离您的站点
无需前端 JavaScript托管页面样式由 A55 管理

职责汇总​

职责H2HSDK收银台页面
后端创建收款您您您
采集卡片数据您SDKA55
处理 3DS 验证您SDKA55
处理 Webhook您您您
卡数据安全您负责A55 通过 SDK 处理完全由 A55 管理
前端 JavaScript不需要需要（SDK）不需要

集成快速入门​

无论选择哪种模式，后端创建收款的调用方式相同：

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "YOUR_WALLET_UUID",
    "merchant_id": "YOUR_MERCHANT_UUID",
    "payer_name": "张伟",
    "payer_email": "zhangwei@example.com",
    "payer_tax_id": "12345678909",
    "payer_cell_phone": "+5511999999999",
    "installment_value": 250.00,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "订单 #42",
    "type_charge": "credit_card",
    "webhook_url": "https://your-app.com/webhooks/a55"
  }'

此调用之后的处理取决于您的集成模式：

  • H2H： 在请求载荷中包含 card 对象；如果返回 url_3ds 则进行处理。
  • SDK： 使用返回的 charge_uuid 初始化前端 SDK。
  • 收银台页面： 包含 is_checkout: true；将付款人重定向至返回的 URL。

Webhook 是最终事实来源​

无论选择哪种集成模式

将 Webhook 视为最终支付状态的权威来源。提交支付后显示"处理中"状态，直到 Webhook 确认结果。终态（paid、error、canceled、refunded）不会再发生变更。

显示时机
处理中提交支付后
成功Webhook 确认 paid
失败Webhook 确认 error 或 canceled

无论您选择哪种集成模式，Visa Data Only（仅数据共享） 都能通过向发卡行共享丰富的交易数据来提升通过率——而不会增加任何摩擦。Square 的试点项目显示，在 600 万笔交易中，通过率提升高达 +646 个基点。

三种集成方式均支持 Data Only。在收款载荷中添加 data_only: true 并包含 device_info 即可启用。

了解如何启用 Data Only →

H2H 指南 →完整的服务器对服务器集成，包含 3DS 处理。SDK v2 指南 →嵌入 A55 SDK 实现原生收银体验与自动 3DS。收银台页面指南 →重定向至 A55 托管收银台——最快的集成方式。DataOnly 纯数据扣款 →通过数据共享获得最高通过率——无需挑战验证。