卡支付-前置组件集成

该文档介绍前置组件支付下，使用银行卡支付的集成要求。

通过前置组件集成卡支付时，商户无需具备PCI认证资质，因为支付过程中的用户信息（如：用户名、银行卡号、CVV等）等敏感信息，均由PayerMax组件收集托管。

1. 集成准备

查看前置组件支付-集成准备。

2. 交互流程

相比于前置组件支付通用流程主要的差异在于：卡支付时，用户可能需要完成额外的3DS认证流程。

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant User as 用户
    participant Page as 商户页面
    participant Component as PayerMax
前置组件
    participant MServer as 商户服务端
    participant PMServer as PayerMax服务端
    participant Channel as 支付渠道
钱包/银行等

    %% 1. 初始化流程
    User->>Page: 1.1 选择商品下单
    Page->>MServer: 1.2 发送订单信息
如：收单国家、订单币种等
    MServer->>PMServer: 1.3 获取前置组件初始化信息
clientKey和sessionKey
    PMServer-->>MServer: 1.4 返回结果
clientKey和sessionKey
    MServer-->>Page: 1.5 返回结果
含clientKey和sessionKey
    Page->>Component: 1.6 创建并挂载PayerMax组件

    %% 2. 获取Token流程
    User->>Page: 2.1 用户输入支付信息
    Page->>Component: 2.2 获取paymentToken
    Component->>PMServer: 2.3 获取paymentToken
    PMServer-->>Component: 2.4 返回结果
含paymentToken
    Component-->>Page: 返回paymentToken

    %% 3. 支付与3DS认证
    User->>Page: 3.1 确认支付
    Page->>Component: 3.2 提交支付
含paymentToken
    Component->>MServer: 3.3 提交订单
含paymentToken
    MServer->>PMServer: 3.4 创建支付
调用前置组件下单接口
    PMServer->>Channel: 3.5 支付请求
    PMServer->>Channel: 3.6 3DS 验证请求
    Channel-->>PMServer: 3.7 返回3DS请求结果
    PMServer-->>MServer: 3.8 请求结果
含3DS 认证页面URL
    MServer-->>Component: 3.9 返回结果
含3DS 认证页面URL
    Component-->>Page: 3.10 返回结果
    Page->>Page: 3.11 渲染3DS认证页
    User->>Page: 3.12 输入3DS认证信息

    %% 4. 后台处理
    Channel-->>PMServer: 3.13 3DS认证结果
    PMServer->>Channel: 3.14 推进支付
    Channel-->>PMServer: 3.15 支付结果

    %% --- 获取支付结果色块 (与参考代码样式一致) ---
    rect rgb(235, 245, 255)
        Note over MServer, PMServer: 获取支付结果
        
        Note over MServer, PMServer: 通过支付结果通知
        PMServer->>MServer: 4.1 支付结果异步通知
        MServer->>MServer: 4.2 更新支付结果
        MServer-->>PMServer: 4.3 返回响应
        
        Note over MServer, PMServer: 通过支付订单查询
        MServer->>PMServer: 5.1 查询支付交易单
        PMServer-->>MServer: 5.2 交易详情，含支付结果
        MServer->>MServer: 5.3 更新支付结果
    end

3. 接口列表

查看前置组件支付-接口列表。

4. 环境信息

• 测试环境：https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <接口PATH>

• 集成环境：https:// pay-gate.payermax.com/aggregate-pay/api/gateway/ <接口PATH>

5. 集成步骤

5.1 获取前置组件初始化信息

查看前置组件支付-获取前置组件初始化信息。

5.2 渲染前置组件

查看前置组件支付-渲染前置组件。

5.3 创建支付

查看前置组件支付-创建支付。

可以通过请求参数data.paymentDetail.allowedCardOrg指定卡组。不同国家下卡支付的卡组信息，请查看支付方式列表。

前置组件下，支持使用推荐卡进行支付。

5.4 完成3DS认证

前置组件下，直接使用PayerMax 3DS服务，PayerMax依据内部风控结果，决策是否发起3DS认证流程，商户无须额外的集成工作。

5.5 获取支付结果

查看前置组件支付-获取支付结果。

6. 测试上线

在商户完成上述集成步骤后，可以发起实际支付请求进行初步测试验证，具体步骤请查看集成测试-发起测试。

在测试通过后，最终发布上线前，须联系PayerMax技术支持，提交测试的订单信息，以便于PayerMax检查请求日志和数据，确认您已经正确集成相关能力，具体步骤请查看集成测试-发起验收。

验收通过后，商户可以配置生产环境的集成信息，并准备开量事宜。

另外，在收单产品集成下有PayerMax支持的各类支付方式的集成文档，其中包含每种支付方式的测试上线说明。

7. 错误排除

测试或验收过程中的响应错误，可以查看错误排查-错误码。同时，在常见问题中，总结列举各类常见的问题及其处理方式。

您还可以直接联系PayerMax技术支持团队，咨询集成、测试、验收过程中的任何问题。