（串口通信、SHA256签名） POS->>POS: 2. 报文处理 POS->>PPSERVE: 3. 支付/退款请求 PPSERVE->>PPSERVE: 4. 支付/退款请求处理 PPSERVE->>POS: 5. 支付/退款请求 POS->>POS: 6. 交易/退款处理 POS->>PPSERVE: 7. 支付结果 Note over SAAS: 支付/退款结果查询 SAAS->>POS: 8. 支付结果查询 POS->>SAAS: 9. 支付结果返回 ``` ### 支付流程步骤 :::: steps 1. SAAS发起支付请求 SAAS收银系统通过串口向POS设备发送支付请求，请求报文需使用SHA256签名保证数据安全（[签名规约](/notes/zh/guide/sign/)）。 调用接口：[GMC串口支付接口](/notes/zh/api/services/InPersonPayments/gmc/pay/) 2. POS报文处理 POS设备接收串口数据，解析报文并验证签名，提取业务参数。 3. POS转发支付请求 POS设备将支付请求转发至PingPong服务端进行处理。 4. PingPong处理支付请求 PingPong服务端验证商户信息、处理支付路由、执行风控检查。 5. POS执行交易 POS设备根据PingPong服务端指令执行刷卡、插卡或扫码等交易操作。 6. POS上报支付结果 交易完成后，POS设备将支付结果上报至PingPong服务端。 7. SAAS查询支付结果 SAAS收银系统通过串口向POS设备查询支付结果，获取交易状态和详情。 调用接口：[GMC串口查询接口](/notes/zh/api/services/InPersonPayments/gmc/query/) :::: ### 退款流程步骤 :::: steps 1. SAAS发起退款请求 SAAS收银系统通过串口向POS设备发送退款请求，需提供原支付订单号和退款金额。 调用接口：[GMC串口退款接口](/notes/zh/api/services/InPersonPayments/gmc/refund/) 2. POS报文处理 POS设备接收串口数据，解析报文并验证签名，校验退款参数。 3. POS转发退款请求 POS设备将退款请求转发至PingPong服务端进行处理。 4. PingPong处理退款请求 PingPong服务端验证原订单信息、检查可退款金额、执行退款处理。 5. POS执行退款 POS设备根据PingPong服务端指令执行退款操作。 6. POS上报退款结果 退款完成后，POS设备将退款结果上报至PingPong服务端。 7. SAAS查询退款结果 SAAS收银系统通过串口向POS设备查询退款结果，确认退款状态。 调用接口：[GMC串口查询接口](/notes/zh/api/services/InPersonPayments/gmc/query/) :::: ## 相关接口 | 接口名称 | EVENT | 说明 | 链接 | |:--------|:------|:-----|:-----| | GMC串口心跳接口 | `HEARTBEAT` | 保持SAAS与POS设备连接状态 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/heartbeat/) | | GMC串口支付接口 | `PAY` | 创建支付订单并完成交易 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/pay/) | | GMC串口交易查询接口 | `PAY_QUERY` | 查询支付交易状态和详情 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/payQuery/) | | GMC串口退款接口 | `REFUND` | 对已完成的交易发起退款 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/refund/) | | GMC串口退款查询接口 | `REFUND_QUERY` | 查询退款交易状态和详情 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/refundQuery/) | | GMC串口交易取消接口 | `TRANSACTION_CANCEL` | 取消进行中的交易 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/transactionCancel/) | | GMC串口重打印接口 | `REPRINT` | 重新打印交易小票凭证 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/reprint/) | | GMC串口结算接口 | `CALCULATE` | 触发POS设备批量结算 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/settlement/) | ### 接口使用说明 #### 心跳检测（HEARTBEAT） * 建议每 **30秒** 发送一次心跳包 * 连续3次无响应可判定设备离线 * `bizContent` 字段可为空 #### 交易查询（PAY\_QUERY） * 用于查询支付交易状态和详情 * 支持通过 `merchantTransactionId` 或 `transactionId` 查询，二选一 * 返回交易金额、状态、时间及卡支付信息等详情 #### 退款查询（REFUND\_QUERY） * 用于查询退款交易状态和详情 * 支持通过 `merchantRefundId` 或 `transactionRefundId` 查询，二选一 * 返回退款金额、状态、时间及卡支付信息等详情 #### 交易取消（TRANSACTION\_CANCEL） * 用于取消进行中的交易 * 需要提供 `merchantTransactionId` 商户交易流水号 * 仅对特定状态下的交易有效 #### 重打印（REPRINT） * 用于重新打印上一笔交易小票 * `bizContent` 字段可为空，默认打印最后一笔交易 * 如需指定交易，可在 `bizContent` 中传入交易ID #### 结算（CALCULATE） * 用于触发POS设备批量结算，通常在日终执行 * `bizContent` 字段可为空 * 结算完成后POS设备会打印结算凭证 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/InPersonPayments/offlineCardPayment/index.md description: >- 线下卡支付解决方案通过SAAS收银机与POS设备云端通信，实现支付、查询、退款等功能。采用REST API方式，关键参数包括deviceSn、deviceModel和cashierDeviceId，确保交易请求准确路由至指定POS终端。覆盖场景包括实体店铺的即时支付与退款处理，支持刷卡及NFC支付方 --- # 线下卡支付 ## 主要参与方 PingPongCheckout的线下卡支付解决方案集成方案实现了SAAS收银机与POS设备通过云端服务进行通信，完成支付、查询、退款等交易流程。该方案采用REST API方式，通过明确的设备标识机制确保交易请求准确路由到指定的POS终端。 * SAAS收银机：发起交易请求，接收交易结果 * PingPong收单服务：作为中间层，处理请求路由和响应转发 * POS设备：执行实际的支付操作，处理卡片交易 ## API 清单 1. 下单 API 2. 单笔交易查询 API 3. 申请退款 API 4. 退款查询 API ## 支付流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant SAAS as 💳 SAAS收银机 participant PP as 🔄 PingPong收单服务 participant POS as 📱 POS设备 Note over SAAS, POS: 💰 卡支付流程 Note over SAAS, PP: 📋 请求参数:• deviceSn, deviceModel, cashierDeviceId• paymentMethod=卡支付方式 SAAS->>+PP: 1️⃣ 下单并支付请求(unifiedPay) PP->>PP: 2️⃣ 验证请求签名和参数 PP->>+POS: 3️⃣ 转发支付请求到指定POS设备 POS->>POS: 4️⃣ 执行刷卡/NFC支付操作 Note over PP, POS: ✅ 支付响应:• 包含卡交易信息(cardTransinfo)• transactionId, merchantTransactionId• status=SUCCESS/FAILED POS-->>-PP: 5️⃣ 返回支付处理结果 PP-->>-SAAS: 6️⃣ 返回支付结果 opt 🔍 [查询订单详情] Note over SAAS, PP: 🔎 查询参数:• transactionId 或 merchantTransactionId SAAS->>+PP: 7️⃣ 订单结果查询(query) PP->>PP: 8️⃣ 查询订单状态 Note over PP, POS: 📊 订单详情响应:• 完整的cardTransinfo信息• 收单行、卡号、持卡人等信息 PP-->>-SAAS: 9️⃣ 返回订单详情 end Note over SAAS, POS: 🎉 支付流程完成 ``` ### 发起支付请求 SAAS收银机向PingPong收单服务发送统一下单支付请求(unifiedPay) 请求中包含`deviceSn`和`deviceModel`参数，明确指定目标POS设备 同时包含`cashierDeviceId`标识收银机自身 ::: note 注意 `deviceSn`,`cashierDeviceId`和`deviceModel`参数是为了确保支付请求被正确路由到指定的POS设备, 请确保参数填写正确, 否则可能导致支付失败或请求被路由到错误的POS设备 ::: ### 请求路由 PingPong收单服务接收请求并验证签名 根据`deviceSn`和`deviceModel`将支付请求路由到指定POS设备 ### 支付处理 POS设备接收请求并执行支付操作(如刷卡、NFC支付等) 处理完成后，POS设备将结果返回给收单服务 ### 结果返回 收单服务将支付结果返回给SAAS收银机,同步响应结果可能是`PROCESSING`状态,支付结果需要通过查询API进行获取, SAAS收银机接收结果并进行后续处理（如打印小票、更新订单状态等） ## 退款流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant SAAS as 💳 SAAS收银机 participant PP as 🔄 PingPong收单服务 participant POS as 📱 POS设备 Note over SAAS, POS: 💰 卡支付退款流程 Note over SAAS, PP: 📋 退款请求参数:• merchantTransactionId, merchantRefundId• deviceSn, deviceModel (POS退款必传) SAAS->>+PP: 1️⃣ 退款请求(refund) PP->>PP: 2️⃣ 验证请求签名和参数 PP->>+POS: 3️⃣ 转发退款请求到指定POS设备 POS->>POS: 4️⃣ 执行退款操作 Note over PP, POS: ✅ 退款响应:• transactionRefundId, merchantRefundId• status = ACCEPT_SUCCESS/PROCESSING/SUCCESS/FAILED POS-->>-PP: 5️⃣ 返回退款处理结果 PP-->>-SAAS: 6️⃣ 返回退款受理结果 opt 🔍 [查询退款状态 - 可选] Note over SAAS, PP: 🔎 查询参数:• refundId 或 merchantRefundId• merchantTransactionId SAAS->>+PP: 7️⃣ 退款结果查询(refund/query) PP->>PP: 8️⃣ 从数据库查询退款状态 Note over PP, POS: 📊 退款状态响应:• status = PROCESSING/SUCCESS/FAILED• 退款金额、币种、时间等信息 PP-->>-SAAS: 9️⃣ 返回退款状态信息 end Note over SAAS, POS: 🎉 退款流程完成 ``` ### 发起退款请求 SAAS收银机向收单服务发送退款请求(refund) 对于POS交易退款，必须包含`deviceSn`和`deviceModel`参数 请求中包含原交易信息和退款金额 ### 退款路由 收单服务验证请求并路由到指定POS设备 POS设备执行退款操作 ### 结果返回 POS设备将退款结果返回给收单服务，同步响应结果可能是`PROCESSING`状态,支付结果需要通过查询API进行获取, 收单服务将退款受理结果返回给收银机 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/InPersonPayments/offlineQRCodePayment/index.md description: >- 线下二维码支付解决方案通过SAAS收银机与POS设备云端通信，实现支付、查询和退款。采用REST API方式，支持支付宝、微信等移动支付工具。关键API包括下单、交易查询、申请退款和退款查询。适用于零售场景，二维码有效期可自定义，建议设置为5分钟以优化用户体验。 --- # 线下二维码支付 ## 主要参与方 PingPongCheckout的线下二维码支付解决方案实现了SAAS收银机与POS设备通过云端服务进行通信，完成支付、查询、退款等交易流程。该方案采用REST API方式，生成二维码供消费者使用移动支付工具完成支付。 * SAAS收银机：发起交易请求，展示二维码，接收交易结果 * PingPong收单服务：处理请求，生成二维码，通知交易结果 * 消费者移动设备：扫描二维码完成支付 ## API 清单 1. 下单 API 2. 单笔交易查询 API 3. 申请退款 API 4. 退款查询 API ## 支付流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant SAAS as 💳 SAAS收银机 participant PP as 🔄 PingPong收单服务 participant Consumer as 📱 消费者移动设备 Note over SAAS,Consumer: 🧾 二维码支付流程 Note over SAAS, PP: 📋 请求参数:• cashierDeviceId• paymentMethod=二维码支付方式• timeExpire (二维码有效期) SAAS->>+PP: 1️⃣ 下单并支付请求(unifiedPay) PP->>PP: 2️⃣ 验证请求签名和参数 Note over PP,Consumer: ✅ 二维码响应:• qrCode, qrUrl, qrCodeExpired• status=PROCESSING PP-->>-SAAS: 3️⃣ 返回二维码信息 SAAS->>Consumer: 4️⃣ 向消费者展示二维码 Consumer->>Consumer: 5️⃣ 扫描二维码 Consumer->>Consumer: 6️⃣ 确认支付 Consumer->>PP: 7️⃣ 支付处理 opt 🔁 [轮询订单状态 - 直到终态] Note over SAAS, PP: 🔎 查询参数:• transactionId 或 merchantTransactionId SAAS->>+PP: 8️⃣ 订单结果查询(query) PP->>PP: 9️⃣ 查询订单状态 Note over PP,Consumer: 📊 订单状态响应:• status=PROCESSING/SUCCESS/FAILED PP-->>-SAAS: 🔟 返回订单状态信息 end Note over SAAS,Consumer: 🎉 二维码支付完成 ``` ### 发起支付请求 SAAS收银机向PingPong收单服务发送统一下单支付请求(unifiedPay) 请求中必须包含`cashierDeviceId`参数标识收银机自身 指定`paymentMethod`参数为相应的二维码支付方式 ::: note 注意 请求参数中的`timeExpire`表示二维码的有效期，可设置1分钟到3天。若不设置，默认为3天。 为提高用户体验，建议设置合理的二维码超时时间，通常零售场景建议设置为5分钟。 ::: ### 生成二维码 PingPong收单服务接收请求并验证签名 生成支付二维码，返回`qrCode`和`qrUrl`参数 同时返回`qrCodeExpired`参数表示二维码过期时间 ### 展示二维码 SAAS收银机接收响应，将二维码展示给消费者 消费者使用移动支付工具（如支付宝、微信等）扫描二维码完成支付 ### 支付结果查询 初始响应状态通常为`PROCESSING` SAAS收银机需通过查询API(query)轮询订单状态 或等待PingPong收单服务通过`notificationUrl`推送支付结果 ::: warning 重要提示 收单服务返回的初始状态为`PROCESSING`，只表示二维码生成成功，不代表支付完成。 SAAS收银机应实施轮询机制，建议间隔3-5秒查询一次，直到获取最终支付结果。 ::: ## 退款流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant SAAS as 💳 SAAS收银机 participant PP as 🔄 PingPong收单服务 Note over SAAS,PP: 💰 二维码支付退款流程 Note over SAAS, PP: 📋 退款请求参数:• merchantTransactionId, merchantRefundId• cashierDeviceId SAAS->>+PP: 1️⃣ 退款请求(refund) PP->>PP: 2️⃣ 验证请求签名和参数 PP->>PP: 3️⃣ 处理退款请求 Note over SAAS,PP: ✅ 退款响应:• transactionRefundId, merchantRefundId• status=ACCEPT_SUCCESS/PROCESSING PP-->>-SAAS: 4️⃣ 返回退款受理结果 opt 🔁 [查询退款结果 - 直到终态] Note over SAAS, PP: 🔎 查询参数:• refundId 或 merchantRefundId• merchantTransactionId SAAS->>+PP: 5️⃣ 退款结果查询(refund/query) PP->>PP: 6️⃣ 查询退款状态 Note over SAAS,PP: 📊 退款状态响应:• status=PROCESSING/SUCCESS/FAILED• 退款金额、币种、时间等信息 PP-->>-SAAS: 7️⃣ 返回退款状态信息 end Note over SAAS,PP: 🎉 二维码退款完成 ``` ### 发起退款请求 SAAS收银机向收单服务发送退款请求(refund) 请求中包含原交易信息和退款金额 必须包含`cashierDeviceId`参数标识收银机自身 ### 退款处理 收单服务验证请求并处理退款操作 退款结果可能不会立即返回，初始可能为`ACCEPT_SUCCESS`或`PROCESSING`状态 ### 结果查询 SAAS收银机通过退款查询API(refund/query)获取最终退款结果 轮询查询直到退款状态变为`SUCCESS`或`FAILED` ::: tip 退款建议 对于二维码支付的退款，建议在系统中保留原交易的`merchantTransactionId`，以便在退款时快速关联原交易。 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/InPersonPayments/overview/index.md description: >- PingPongCheckout的线下支付解决方案支持构建功能丰富的销售点集成系统，提供全球多语言支持、多样化支付方式（如信用卡和扫码支付）、灵活的网络架构及独特的购物体验。通过统一管理平台轻松管理支付终端和交易记录。适用于需要本地化支付体验和定制化终端界面的商户。 --- # Accept in-person payments with Terminal ## In-person payments 通过PingPongCheckout的线下支付解决方案，您可以构建功能丰富的销售点集成系统，具备以下特点： • 全球多语言支持 - 在世界各地提供多种语言的支持服务 • 支付方式多样化 - 支持全球和本地各种支付方式，满足不同客户需求 • 灵活的网络架构 - 可根据您的业务需求选择合适的网络架构方案 • 独特的购物体验 - 为客户打造独特的购物体验，无缝整合线下和线上支付 • 统一管理平台 - 通过统一的商户后台，轻松管理您的支付终端和交易记录 ## 为客户打造独特体验 ### 本地化支付体验 为购物者提供本地货币支付选项，并为海外游客提供免税购物优惠，提升购物便利性。 个性化购物体验 ### 定制化终端界面 为支付终端开发完全可定制的用户界面，支持： * 品牌定制化 - 融入您的品牌元素 * 语言定制化 - 支持多种语言 * 功能扩展 - 支持多种支付方式 ## 如何工作 ## 支持的支付方式 PingPongCheckout的线下支付解决方案支持以下支付方式： * 信用卡支付 收银机通过物理POS设备直接处理信用卡支付，支持多种卡类型。 * 扫码支付 当您的收银机有背面屏幕可以显示二维码时，可以扫码完成支付。 ### 信用卡支付 1. **交互模式**： * 一次请求即是下单并支付。 * 客户在POS设备上直接刷卡 * 支付结果返回给收银系统 2. **设备依赖**： * 强依赖物理POS设备 * 必须传递设备标识参数：`deviceSn`、`deviceModel`、`cashierDeviceId` * 支付请求会转发到指定的POS设备上执行 3. **数据特性**： * 返回详细的卡交易信息(`cardTransinfo`) * 包含收单行信息、卡号（通常脱敏）、持卡人信息等 * 支持查询获取更完整的交易详情 4. **退款特点**： * 退款必须通过原POS设备执行 * 退款请求必须包含设备信息 * 退款过程相对同步，但仍需查询确认最终状态 ### 二维码支付 1. **交互模式**： * 异步处理流程，分为获取二维码和支付确认两个阶段 * 系统生成二维码，客户使用移动设备扫码支付 * 支付结果需等待用户完成支付操作 2. **设备依赖**： * 不依赖POS硬件设备 * 仅需收银终端展示二维码 * 支付在用户移动设备上完成 3. **数据特性**： * 返回二维码信息：`qrCode`、`qrUrl`、`qrCodeExpired` * 不包含卡交易信息 * 数据结构相对简单 ## 状态流转 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E8F4FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E8F4FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9' } }}%% stateDiagram-v2 [*] --> INIT : 下单支付 INIT --> PROCESSING : 发起支付请求 INIT --> CLOSED : 超时 PROCESSING --> SUCCESS : 成功回执 PROCESSING --> CANCEL : 订单取消回执 PROCESSING --> FAILED : 失败回执 PROCESSING --> CLOSED : 超时关闭/超时回执 SUCCESS --> [*] CANCEL --> [*] FAILED --> [*] CLOSED --> [*] note right of INIT 初始态 INIT end note note right of PROCESSING 处理中 PROCESSING end note note right of SUCCESS 成功 SUCCESS end note note right of CANCEL 取消 CANCEL end note note right of FAILED 失败 FAILED end note note right of CLOSED 关闭 CLOSED end note ``` --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/hosted/index.md' description: >- 该文档介绍了支付集成方式的选择与配置，包括重新支付、记住卡号功能及内嵌SDK特性。适用于优化用户支付体验，支持48小时内未支付成功的订单再次发起支付，并提供保存卡号以简化下次支付流程。内嵌SDK基于Web Component技术和ES2021标准，轻量快速，兼容现代主流浏览器，可自定义皮肤并设置支付 --- # 概览 ## 重新支付 收银台若未支付成功，可以手动打开URL再次发起支付，一个收银台URL有效时长为7天。 ## 记住卡号功能 收银台页面，如果用户勾选了保存卡号，下次支付时候将会自动展示上次的卡信息，如果有多个卡， 将展示已保存的卡列表。选择卡号之后将会自动回填卡信息，优化持卡人的结帐体验。 ## 内嵌 SDK 特性 1. 基于 Web Component 技术和 ES2021 标准，由浏览器原生支持的，优势明显 2. 更加轻量，快速响应，Gzip后整个收银台包大小约为 59 kb 3. 对接方式简单，灵活接入，符合现代化收银台 web app 标准 4. 现代主流浏览器中高版本均兼容 5. 支持自定义 SDK 收银台皮肤 6. 支持发起支付请求前设置钩子函数 ### 浏览器最低版本要求 ## 效果展示 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/link/index.md' description: >- 跳转收银台是一种支付集成方式，通过从下单响应中获取paymentUrl并重定向到收银台完成支付。支持多语言设置，默认为英文；若指定其他语言，则以传入值为准。适用于需要快速集成支付功能的场景，确保用户在熟悉的语言环境中顺畅完成支付过程。 --- # 跳转收银台 ## 重定向到收银台 从下单的响应中获取`paymentUrl`并重定向。 ## 跳转收银台语种支持 ::: note 提示 在language未传入的情况下，收银台语言默认为en，如果传了language，就以传入的语言为准。可在语言列表查看具体枚举值 ::: ## 跳转收银台模式系统交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Client as 💻 客户端 participant Merchant as 🏪 商户服务端 participant PP as 🔄 PingPong服务端 participant Checkout as 🛒 PingPong收银台 participant Bank as 🏦 发卡行 Note over Client, Bank: 🔗 跳转收银台交互流程 Note over Client, Merchant: 📦 订单创建阶段:
• 购物车结算
• 选择跳转支付 Client->>+Merchant: 1️⃣ 客户端提交订单 Note right of Merchant: 收集订单信息:
• 商品列表
• 金额币种
• 语言偏好 Merchant->>+PP: 2️⃣ 下单API请求(reserve) Note right of PP: 订单参数:
• 商品信息
• 支付配置
• 回调URLs
• language参数 PP->>PP: 3️⃣ 创建支付会话 Note right of PP: • 订单验证
• 生成会话ID
• 准备收银台 PP-->>-Merchant: 返回paymentUrl和会话信息 Note right of Merchant: 响应包含:
• paymentUrl(重定向链接)
• sessionToken
• 过期时间 Merchant-->>-Client: 重定向到paymentUrl Note over Client, Bank: 🛒 收银台处理阶段 Client->>+Checkout: 4️⃣ 跳转到PingPong收银台 Note right of Checkout: 根据language参数
显示对应语言界面 Checkout->>+PP: 5️⃣ 初始化收银台会话 PP->>PP: 验证会话有效性 PP-->>-Checkout: 返回支付方式和配置 Checkout-->>-Client: 渲染收银台页面 Note over Client: 显示支付方式:
• 国际信用卡
• 本地支付方式
• 数字钱包等 Client->>+Checkout: 6️⃣ 用户选择支付方式并填写信息 Note right of Checkout: 用户交互:
• 选择支付方式
• 填写支付信息
• 确认支付 Checkout->>+PP: 7️⃣ 提交支付请求 Note right of PP: 支付处理:
• 数据验证
• 风控检查
• 路由选择 PP->>PP: 处理支付逻辑 Note right of PP: • PCI合规处理
• 风险评估
• 3DS决策 alt 🟢 支付成功 - 无需3D PP-->>Checkout: 🎉 支付成功 Checkout-->>Client: 显示支付成功页面 opt 🔄 返回商户 Note over Client: 可选择返回商户网站
或停留在结果页 Client->>Merchant: 用户点击返回按钮 end else 🔐 需要3D验证 PP->>+Bank: 8️⃣ 3D Secure验证 Note right of Bank: 挑战流程:
• OTP验证
• 指纹/面部识别
• 其他验证方式 Bank->>Client: 重定向到3D验证页 Client->>Bank: 完成3D验证 Bank->>Bank: 处理验证结果 Bank-->>-PP: 返回验证结果 PP->>PP: 处理最终支付结果 PP-->>Checkout: 最终支付状态 Checkout-->>Client: 显示最终结果页面 else ❌ 支付失败 PP-->>Checkout: ❌ 支付失败 Checkout-->>Client: 显示支付失败页面 opt 🔄 重试支付 Client->>Checkout: 用户选择重试 Note over Checkout: 返回支付方式选择
允许重新支付 end end PP-->>-PP: 支付处理完成 Checkout-->>-Client: 最终页面显示 Note over Merchant, PP: 📡 异步通知阶段 PP->>+Merchant: 9️⃣ 异步通知支付结果 Note right of Merchant: Webhook通知:
• 最终支付状态
• 交易详情
• 签名验证 Merchant->>Merchant: 处理订单状态 Note right of Merchant: • 更新订单状态
• 触发业务流程
• 用户通知 Merchant-->>-PP: HTTP 200确认接收 Note over Client, Bank: 🎯 跳转收银台流程完成 ``` --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/magento235/index.md description: >- Magento2.3.5-PPPay 插件安装说明涵盖了插件的安装前提、注意事项及详细步骤。适用于Magento版本≥2.3.5和PHP版本≥7.1的环境，支持curl和bcmath扩展。文档强调了订单号单调递增的重要性，并提供了沙箱与生产环境配置参数及命令行操作指南。 --- # Magento2.3.5-PPPay 插件安装说明 ## 安装前提 > * magento version>=2.3.5 > * php version >=7.1 > * php extionsion:curl bcmath > * chmod 777 /magentoRoot/var/log *** 以下为非必要设置，若出现504错误可以检查下列选项 * \[ ] php ini执行超时时间 * \[ ] nginx 或者 apache 设置执行超时时间 *** ::: danger 注意 1. 同一个accId下订单号不能重复，必须是单调递增的，否则会引发订单状态问题。 2. 来源于不同数据库的订单不能共用同一个accId。 3. accId下已经有过交易，安装插件之前应该将id起始值设置为大于当前订单id最大的值。 4. 重置数据库，商店，或者accId迁往别的商店，应该检查accId下订单号最大值。 ::: ### 插件下载 Pppay.zip ## 安装过程 ### Magento安装路径规则 解压插件包后 我们先查看插件压缩包的registration.php文件 ```php title="registration.php" line-numbersConfiguration->Sales->Payments Method->Ping Pong Pay`  3. 按照下图所示配置参数! [image.png](/magento235/1629294335798-7a795d99-5669-4423-ba7c-6fd1d3226dee.png) *** ## 环境参数 ### 沙箱环境店铺参数 ```text title="沙箱环境店铺参数" line-numbers # [!code highlight] PingPong沙箱环境店铺参数 clientId: 2018092714313010016 accId: 2018092714313010016291 salt: F78BC96A55548B2319EE68E0 ``` ### 沙箱环境测试卡号 ```text title="沙箱环境测试卡号" line-numbers # [!code highlight] 标准测试卡号 卡号：4200000000000000 有效期：12/22 cvv: 123 cvv需为3位纯数字 # [!code highlight] 3DS交易测试卡号 3DS交易卡：4711100000000000 ``` ### 环境地址 ```text title="PingPong支付环境地址" line-numbers # [!code highlight] 沙箱环境地址 沙箱环境 https://sandbox-acquirer-payment.pingpongx.com # [!code highlight] 生产环境地址 生产环境 https://acquirer-payment.pingpongx.com ``` *** ### 对接过程 #### 沙箱环境对接 1. 按照文件安装插件。 2. 插件安装完成之后，需要进行支付自测，并完成以下事项： * \[ ] 截图输入卡号的页面 * \[ ] 截图支付完成的最终跳转页面 * \[ ] 将截图发送到对接群，并通知技术支持 安装过程，有任何问题可以在对接群里需求技术支持。 *** 注意事项： > 沙箱环境下，不会对持卡人发起扣款，支付之后发货将造成损失，不发货将持卡人可能会发起投诉。因此在对接期间，需要谨慎操作，对接测试通过之后，因立即关闭支付通道，等待生产环境上线之后打开。 *** ## 生产环境对接 1. 插件在技术支持下完成第一轮的沙箱环境对接后将进入，网站资料和账户审查阶段，通过之后，会发放生产环境参数。 2. 获取到生产参数之后，完成以下事项 * \[ ] 将沙箱环境参数替换为生产参数。 * \[ ] 自测支付，并完成截图 * \[ ] 准备一个$1的商品链接。 3. 发送截图和商品链接，并通知技术支持，将由客户/技术支持对该商品链接发起真实交易测试。以验证对接结果和网站支付可用性。 4. 完成真实交易测试之后，需要商户发起退款，以便于验证退款流程。 5. 完成以上流程，网站对接结束，支付通道正式上线，支付可用。 ## 生产环境配置 ### 审核过程 从对接群中或者商务/客户处获得通知，审核通过。 登录[商户后台](https://pay.pingpongx.com/aq/websiteList) ```text title="商户后台地址"https://pay.pingpongx.com/aq/websiteList ``` #### 前往网站列表 如图所示，前往群组管理->查看详情->网站列表 #### 群组管理 > * ⚫ 从菜单栏选择【网站管理】-【群组管理】进入群组管理页面 > * ⚫ 该功能实现当前商户可点击“创建群组”新建群组;系统默认会给一个默认的群组 > * ⚫ 网站下挂于群组。 > * ⚫ 点击“查看详情”进入群组详情页面，可修改群组名称、查看复制 ID 号、查看群组下的网站。  #### 选择网站 根据当前对接网站的域名，在列表中选择对应的网站  #### 获取对应域名网站的accId  #### 获取秘钥 > 从菜单栏选择【系统管理】-【秘钥管理】默认进入秘钥管理页，可在此页面查 看网站秘钥。 > 进入秘钥管理后，可查看所有网站对应的秘钥，点击“秘钥详情”查看具体秘 > 钥字段。 > 状态为“正常”的秘钥可使用，当状态为“异常”时，将无法使用可联系相关业务 人员处理。  *** ### M2常用命令 #### 显示后台管理员URI ```shell title="显示后台管理员URI" line-numbers php bin/magento info:adminuri ``` #### 卸载模块 比如插件名为Pppay\_Pppay ```shell title="卸载模块" line-numbers php bin/magento module:uninstall --clear-static-content Pppay_Pppay ``` #### 启用模块插件 比如插件名为Pppay\_Pppay ```shell title="启用模块插件" line-numbers php bin/magento module:enable --clear-static-content Pppay_Pppay ``` #### 禁用模块插件 比如插件名为Pppay\_Pppay ```shell title="禁用模块插件" line-numbers php bin/magento module:disable --clear-static-content Pppay_Pppay ``` #### 插件列表(启用和禁用的) ```shell title="插件列表" line-numbers php bin/magento module:status ``` #### 切换到生产模式 ```shell title="切换到生产模式" line-numbers php bin/magento deploy:mode:set production ``` #### 切换到开发模式 ```bash title="切换到开发模式" line-numbers php bin/magento deploy:mode:set developer ``` #### 代码编译 检查代码是否有语法错误,比如调用的类是否存在等等。 ```shell title="代码编译" line-numbers bin/magento setup:di:compile[!code highlight] ``` #### 生成静态文件 生成最新的静态文件到pub/static里去。 默认模式和生成模式必须要这些静态文件,不然就报错。 ```shell title="生成静态文件" line-numbers bin/magento setup:static-content:deploy -f[!code highlight] ``` 会自动生成默认语言(一般为英语)的静态文件。 也就是说上面这条命令只生成en\_US的静态文件。 如果你想要同时生成英文和中文,需要在后面指定语言包名,就是: ```shell title="生成多语言静态文件" line-numbers bin/magento setup:static-content:deploy en_US zh_Hans_CN -f[!code highlight] ``` #### 更新Magento数据库数据 插件里有自定义的表/添加了产品属性/更改了某个字段等等,凡是跟数据库表相关的数据。 都用这个命令来更新到数据库里去。 ```shell title="更新Magento数据库数据" line-numbers php bin/magento setup:upgrade[!code highlight] ``` --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/non-hosted-apm/index.md description: >- Non-hosted 本地支付提供了一种无需跳转至第三方页面的支付集成方案，适用于希望在自有平台上完成交易流程的商户。主要通过调用下单并支付API创建订单，并根据返回的action对象中的参数决定展示二维码或跳转链接来引导用户完成支付。支持异步通知机制确保交易状态同步，覆盖地区广泛，包括但不限于亚洲 --- # Non-hosted 本地支付 ## 交互流程 ::: steps 1. 客户端下单 客户在商户平台发起订单创建 2. 商户服务端请求下单并支付 商户后台调用[下单并支付](/notes/zh/checkout/api/uniformly/)接口 3. PingPongCheckout响应结果 若请求成功，PingPongCheckout会返回以下两种可能的结果： * 二维码：按提示，扫码支付 * url：跳转到APM支付通道方 4. 在APM通道指定的页面完成支付 用户按照指引在支付页面完成支付操作 5. PingPongCheckout服务端推送支付结果 支付完成后，系统发送异步通知，详见[异步通知](/notes/zh/notify/notify/) 6. 商户接收通知并返回确认 商户收到通知之后，应返回`code 200`作为确认 ::: ## API清单 ## 服务端接入 请求下单并支付 创建订单并获取APM支付关键信息`action`对象。 本地支付- `action.type`取值： | 参数 | 描述 | |:-------------------|:----------| | `QR_URL` | 二维码图片url，可以直接展示 | | `PAYMENT_REDIRECT_URL` | 跳转链接 | ## 客户端接入 服务端下单成功后,根据下单并支付响应参数做不同操作 | 参数 | 描述 | |:-------------------|:----------| | `paymentQrCode` | 展示二维码完成支付 | | `paymentRedirectUrl` | 直接跳转 | --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/non-hosted-card/index.md description: >- Non-hosted 国际信用卡支付方案适用于具备PCI-DSS认证的商户，能够自行开发并处理持卡人信息。该方案通过SafePayGuardJs和SecureShieldJs插件收集风控参数，并在用户点击支付后提交至PingPongCheckout服务端处理。支持全球范围内的信用卡支付，提供3D安全 --- # Non-hosted 国际信用卡支付 ## 接入前提 1. 商户具备PCI资质，并通过PingPongCheckout验证。(PCI-DSS请发送邮件附件到`acquire-risk@pingpongx.com`并抄送`gig-tech-acq@pingpongx.com`) 2. 商户具有自行开发收银台的能力。 :::danger 注意 该方案要求商户服务器自行保存、处理持卡人的信用卡信息，因此强制要求商户具备PCI-DSS认证。 ::: ## 交互流程 ::: steps 1. 进入商户的结账页面后，初始化 SafePayGuardJs 和 SecureShieldJs 插件 初始化风控插件，为后续操作做准备 2. 监听卡号输入框，持卡人填写卡号 当卡号发生改变或输入框失去焦点时，触发初始化 SecureShieldJs 中事件 triggerThreeDsInit，风控插件与 PingPongCheckout 服务端交互，返回部分 jsGeneratedData 和 browserInfo参数 3. 用户点击支付 调用 SafePayGuardJs 和 SecureShieldJs 中的 getGeneratedData 方法获取风控参数 4. 客户端提交订单信息 [下单并支付](/notes/zh/checkout/api/uniformly/)，将 SafePayGuardJs 和 SecureShieldJs 插件中收集的 jsGeneratedData、browserInfo 和其他参数一并提交 5. PingPongCheckout 服务端请求发卡行接口 将支付信息发送给发卡行处理 6. 发卡行返回支付结果给 PingPongCheckout 处理支付请求后返回结果 7. PingPongCheckout 服务端同步请求结果 接收并处理发卡行返回的结果 8. 商户客户端根据返回结果决定后续流程 根据 bizContent.threeDContinue 决定是否进入3D流程： * 无需 3D 验证：商户可以执行自定义的逻辑，展示支付结果 * 需要跳转 3D 验证：根据 bizContent.threeDUnionParams.threeDRedirectUrl 跳转3D挑战页，完成验证后 PingPongCheckout 会重定向到 payResultUrl ::: ## API清单 ## 客户端接入 ### 接入风控插件 端到端接入需要风控JS来收集必要的信息对交易做决策，当持卡人成输入卡号完之后，风控插件将会调用PingPongCheckoutServer API发送卡号数据进行验证， 详见 3DS集成指南 ## 服务端接入 ### 创建订单并支付 请求下单并支付 ### 处理响应 请求交易接口之后，PingPongCheckout 根据请求参数响应结果，商户应根据响应处理交易。 处理结果可能是中间态，需要接入异步通知处理交易状态。请前往异步通知 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/non-hosted/index.md description: >- 非托管支付方式介绍国际信用卡和本地支付的集成方法。适用于具备PCI资质且能自行开发收银台的商户，支持全球范围内的信用卡支付及特定地区的本地支付。关键特性包括风控插件集成、3D验证流程以及通过下单并支付API完成交易处理。 --- # Non-hosted > 国际信用卡以下简称 Credit Card > > 本地支付以下简称APM ## 国际信用卡支付 ### 接入前提 1. 商户具备PCI资质，并通过PingPongCheckout验证。(PCI-DSS请发送邮件附件到`acquire-risk@pingpongx.com`并抄送`gig-tech-acq@pingpongx.com`) 2. 商户具有自行开发收银台的能力。 :::danger 注意 该方案要求商户服务器自行保存、处理持卡人的信用卡信息，因此强制要求商户具备PCI-DSS认证。 ::: ### 交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Client as 💻 客户端 participant Merchant as 🏪 商户服务端 participant Risk as 🔒 风控插件 participant PP as 🔄 PingPong服务端 participant Bank as 🏦 发卡行 Note over Client, Bank: 💳 卡支付交互流程 Note over Client, Risk: 🛡️ 风控初始化阶段:• PCI-DSS认证要求• 持卡人卡信息处理 Client->>+Risk: 1️⃣ 进入结账页面，初始化风控插件 Risk-->>-Client: 风控插件初始化完成 Client->>Client: 2️⃣ 持卡人填写卡号信息 Note right of Client: 监听卡号输入框
卡号变更或失去焦点 Client->>+Risk: 3️⃣ 触发complexInit事件 Risk->>+PP: 风控插件与服务端交互 Note right of PP: 风控数据收集
卡号验证处理 PP-->>-Risk: 返回jsGeneratedData参数 Risk-->>-Client: 风控数据收集完成 Client->>+Merchant: 4️⃣ 提交订单和jsGeneratedData Note right of Merchant: 订单信息
+ 风控数据 Merchant->>+PP: 5️⃣ 下单并支付请求(uniformly) Note right of PP: 包含jsGeneratedData
和订单参数 PP->>PP: 6️⃣ 处理支付请求和风控验证 Note right of PP: • 风控评估• 3DS决策• 支付路由 alt 🟢 [无需3D验证] PP-->>Merchant: 🎉 支付成功响应 Merchant-->>-Client: 展示支付结果 Note over Client: 商户自定义逻辑
支付完成页面 PP->>Merchant: 9️⃣ 异步通知支付结果 Note right of Merchant: 订单状态更新
业务逻辑处理 else 🔐 [需要3D验证] PP-->>Merchant: 🔒 需要3D验证响应 Merchant-->>-Client: 触发3D验证流程 Note over Client, Bank: 🔐 3D Secure验证流程 Client->>+Risk: 8️⃣ 触发风控插件3D验证事件 Risk->>Client: 重定向到3D挑战页面 Client->>+Bank: 持卡人填写3D验证信息 Bank->>Bank: 验证3D信息 Note right of Bank: • OTP验证• 生物识别• 其他挑战 Bank->>+PP: 3D验证结果 PP->>PP: 处理3D验证结果 PP-->>-Bank: 确认接收 PP->>Client: 重定向到支付结果页 PP->>Merchant: 9️⃣ 异步通知最终支付结果 Note right of Merchant: 根据3D结果
更新订单状态 end Note over Client, Bank: 🎯 卡支付流程完成 ``` ****以下对主要步骤做简要说明**** :::: steps 1. 步骤 1 进入商户的结账页面后，初始化风控插件 2. 步骤 2 监听卡号输入框，持卡人填写卡号，卡号发生改变或者输入卡号的框体失去焦点，触发初始化事件-complexInit 3. 步骤 3 complexInit事件中，风控插件与PingPongCheckout服务端交互，返回jsGeneratedData参数 4. 步骤 4 客户端提交订单和jsGeneratedData参数到商户服务端 5. 步骤 5 商户服务端请求[下单并支付](/notes/zh/checkout/api/uniformly/)，将jsGeneratedData和其他参数一并提交 6. 步骤 6 PingPongCheckout服务端响应请求结果，根据返回结果决定是否进入3D流程 7. 步骤 7 无需3D验证,商户可以执行自定义的逻辑，展示支付结果 8. 步骤 8 需要3D验证 1. 触发风控插件的3D验证事件,页面将被重定向到3D挑战页,持卡人需要填写3D验证信息 2. 发卡行验证3D信息 3. 发卡行响应验证结果给PingPongCheckout服务端 4. 页面被重定向到商户填写的支付结果页 9. 步骤 9 PingPongCheckout服务端推送支付结果,如何获取异步通知报文详见[异步通知](/notes/zh/notify/notify/) :::: ### API清单 ### 客户端接入 #### 接入风控插件 端到端接入需要风控JS来收集必要的信息对交易做决策，当持卡人成输入卡号完之后，风控插件将会调用PingPongCheckoutServer API发送卡号数据进行验证， 详见 3DS集成指南 ### 服务端接入 #### 创建订单并支付 请求下单并支付 #### 处理响应 请求交易接口之后，PingPongCheckout 根据请求参数响应结果，商户应根据响应处理交易。 处理结果可能是中间态，需要接入异步通知处理交易状态。请前往异步通知 ## 本地支付 ### 交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Client as 💻 客户端 participant Merchant as 🏪 商户服务端 participant PP as 🔄 PingPong服务端 participant APM as 💳 本地支付提供商 Note over Client, APM: 🌍 本地支付交互流程 Note over Client, Merchant: 📱 订单创建阶段:• 用户选择本地支付方式• 商户收集订单信息 Client->>+Merchant: 1️⃣ 客户端下单 Note right of Merchant: 用户选择:• 支付方式(APM)• 订单金额• 收货信息 Merchant->>+PP: 2️⃣ 下单并支付请求(uniformly) Note right of PP: 请求包含:• paymentMethod=APM类型• 订单详情• 回调URL PP->>PP: 3️⃣ 处理支付请求 Note right of PP: • 验证商户信息• 选择支付路由• 生成支付会话 alt 🔗 [重定向类型APM] PP-->>Merchant: 📋 返回重定向URL和支付参数 Note right of PP: redirectUrl:
用户需跳转的支付页面 Merchant-->>-Client: 重定向到支付页面 Note over Client, APM: 🔄 外部支付处理流程 Client->>+APM: 4️⃣ 重定向到本地支付页面 Note right of APM: 例如:• 支付宝• 微信支付• PayPal等 APM->>APM: 用户完成支付操作 Note right of APM: • 登录验证• 支付确认• 安全验证 APM->>+PP: 5️⃣ 支付结果回调 PP->>PP: 处理支付结果 PP-->>-APM: 确认接收结果 APM->>Client: 重定向回商户页面 else 📊 [API类型APM] PP->>+APM: 4️⃣ 直接调用APM接口 Note right of APM: 服务端对服务端
API调用 APM->>APM: 处理支付请求 APM-->>-PP: 返回支付结果 PP-->>Merchant: 📋 返回支付结果 Merchant-->>-Client: 展示支付状态 end Note over Merchant, PP: 📡 异步通知阶段 PP->>+Merchant: 6️⃣ 异步通知最终支付结果 Note right of Merchant: Webhook通知:• 支付状态• 交易ID• 金额确认 Merchant->>Merchant: 处理支付结果 Note right of Merchant: • 订单状态更新• 发货处理• 用户通知 Merchant-->>-PP: 确认接收通知 opt 🔍 [状态查询 - 可选] Note over Merchant, PP: 🔎 主动查询支付状态 Merchant->>+PP: 查询支付状态API PP-->>-Merchant: 返回最新支付状态 end Note over Client, APM: 🎉 本地支付流程完成 ``` ****以下对主要步骤做简要说明**** :::: steps 1. 步骤 1 客户端下单 2. 步骤 2 商户服务端请求[下单并支付](/notes/zh/checkout/api/uniformly/) 3. 步骤 3 若请求成功，PingPongCheckout响应结果有2种可能： * 二维码：按提示，扫码支付 * url：跳转到APM支付通道方 4. 步骤 4 在APM通道指定的页面完成支付 5. 步骤 5 PingPongCheckout服务端推送支付结果,如何获取异步通知报文详见[异步通知](/notes/zh/notify/notify/) 6. 步骤 6 商户收到通知之后，应返回`code 200` :::: ### API清单 ### 服务端接入 #### 创建订单并支付 请求下单并支付 ### 客户端接入 服务端下单成功后,根据下单并支付响应参数做不同操作 | 参数 | 描述 | |:-------------------|:----------| | paymentQrCode | 展示二维码完成支付 | | paymentRedirectUrl | 直接跳转 | --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/opencart/index.md description: >- 介绍如何在OpenCart 3.8版本中安装和配置PPPay插件，包括环境要求、安装步骤及生产环境对接流程。适用于需要集成支付功能的商家，支持PHP 7.3及以上版本，需特别注意订单号唯一性和单调递增规则以避免状态问题。 --- # OpenCart-PPPay 插件安装说明 ## 安装前提 > * opencart version 3.8 > * php version >=7.3 > * php Extensions:curl > * chmod 777 /opencart\_root/storage/logs *** *** 以下为非必要设置，若出现504错误可以检查下列选项 * \[ ] php ini执行超时时间 * \[ ] nginx 或者 apache 设置执行超时时间 *** ::: danger 1. 同一个accId下订单号不能重复，必须是单调递增的，否则会引发订单状态问题; 2. 来源于不同数据库的订单不能共用同一个accId; 3. accId下已经有过交易，安装插件之前应该将id起始值设置为大于当前订单id最大的值; 4. 重置数据库，商店，或者accId迁往别的商店，应该检查accId下订单号最大值。 ::: ### 插件下载 opencart-ppay.ocmod.zip *** ## 安装过程 ### 登录网站后台 选择`扩展管理->插件安装` 点击 `上传` 插件。  ### 安装插件  ### 配置插件  ### 启用插件  ## 环境参数 ### 沙箱环境店铺参数 ```text title="沙箱环境店铺参数" line-numbers # [!code highlight] PingPong沙箱环境店铺参数 clientId: 2018092714313010016 accId: 2018092714313010016291 salt: F78BC96A55548B2319EE68E0 ``` ### 沙箱环境测试卡号 ```text title="沙箱环境测试卡号" line-numbers # [!code highlight] 标准测试卡号 卡号：4200000000000000 有效期：12/22 cvv: 123 cvv需为3位纯数字 # [!code highlight] 3DS交易测试卡号 3DS交易卡：4711100000000000 ``` ### 环境地址 ```text title="PingPong支付环境地址" line-numbers # [!code highlight] 沙箱环境地址 沙箱环境 https://sandbox-acquirer-payment.pingpongx.com # [!code highlight] 生产环境地址 生产环境 https://acquirer-payment.pingpongx.com ``` ## 对接过程 ### 沙箱环境对接 1. 按照文件安装插件。 2. 插件安装完成之后，需要进行支付自测，并完成以下事项： * \[ ] 截图输入卡号的页面 * \[ ] 截图支付完成的最终跳转页面 * \[ ] 将截图发送到对接群，并通知技术支持 安装过程，有任何问题可以在对接群里需求技术支持。 *** 注意事项： > 沙箱环境下，不会对持卡人发起扣款，支付之后发货将造成损失，不发货将持卡人可能会发起投诉。因此在对接期间，需要谨慎操作，对接测试通过之后，因立即关闭支付通道，等待生产环境上线之后打开。 *** ### 生产环境对接 1. 插件在技术支持下完成第一轮的沙箱环境对接后将进入，网站资料和账户审查阶段，通过之后，会发放生产环境参数。 2. 获取到生产参数之后，完成以下事项 * \[ ] 将沙箱环境参数替换为生产参数。 * \[ ] 自测支付，并完成截图 * \[ ] 准备一个$1的商品链接。 3. 发送截图和商品链接，并通知技术支持，将由客户/技术支持对该商品链接发起真实交易测试。以验证对接结果和网站支付可用性。 4. 完成真实交易测试之后，需要商户发起退款，以便于验证退款流程。 5. 完成以上流程，网站对接结束，支付通道正式上线，支付可用。 ## 生产环境配置 ### 审核过程 从对接群中或者商务/客户处获得通知，审核通过。 登录[商户后台](https://pay.pingpongx.com/aq/websiteList) ```text:line-numbers title="urls/merchant-backend.txt" https://pay.pingpongx.com/aq/websiteList ``` ### 前往网站列表 如图所示，前往群组管理->查看详情->网站列表 ### 群组管理 > * ⚫ 从菜单栏选择【网站管理】-【群组管理】进入群组管理页面 > * ⚫ 该功能实现当前商户可点击“创建群组”新建群组;系统默认会给一个默认的群组 > * ⚫ 网站下挂于群组。 > * ⚫ 点击“查看详情”进入群组详情页面，可修改群组名称、查看复制 ID 号、查看群组下的网站。  ### 选择网站 根据当前对接网站的域名，在列表中选择对应的网站  ### 获取对应域名网站的accId  ### 获取秘钥 > 从菜单栏选择【系统管理】-【秘钥管理】默认进入秘钥管理页，可在此页面查 看网站秘钥。 进入秘钥管理后，可查看所有网站对应的秘钥，点击“秘钥详情”查看具体秘 > 钥字段。 > 状态为“正常”的秘钥可使用，当状态为“异常”时，将无法使用可联系相关业务 人员处理。  --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/operation/index.md description: >- 该文档介绍如何在PingPongCheckOut后台配置支付链信息，包括登录、维护品牌信息、添加支付链详情等步骤。适用于需要自定义支付邮件模板和控制支付链有效期的商户。特别注意业务订单号的唯一性和长度限制（64位）。 --- # 操作手册 ### 1.登录商户后台 登录您的账号密码进到PingPongCheckOut后台，请点击登录。 ### 2.维护支付链品牌信息 支付链品牌信息功能，是对用户收到支付邮件中，邮件Logo、网站等信息展示的配置，也包含支付链可支付有效期的配置。 (1) 功能菜单位置 (2) 功能展示 定义邮件模版 ### 3.添加支付链信息 支付链功能，用来维护支付信息，包括收件人邮箱、手机号、所消费的商品信息、品牌信息，通过这里可以维护发送给收件人的具体支付信息。 （1）功能菜单位置 （2）添加支付链界面展示 :::note 提示 支付链商品信息中的业务订单号，一般会作为商户侧交易的网站订单号，请注意唯一性和总字符⻓度(64位)的限制。 ::: ### 4.用户收到支付链邮件，进行支付 邮件内容参考： 订单确认页面： 支付页面： 收银台页面： 支付完成页面： ### 5.商户后台订单页展示 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/overview/index.md description: >- 介绍如何选择和配置在线支付产品的集成方式。涵盖从预构建集成到自定义结账体验的多种方案，适用于不同技术水平和需求的商户。推荐的集成方式包括跳转收银台、内嵌SDK及S2S，分别适合低技术投入、轻度定制和完全自定义场景。此外，还提供无代码集成选项如支付链，以及与各类平台和插件的兼容性支持。 --- # 概览 ## 集成概述 在开始使用在线支付产品之前，您可以查看在线支付API文档，先初步了解我们的对接流程。入驻完成之后就可以开始对接了。 您可以通过多种方式集成我们的API接口。这些范围从使用预构建的集成，到构建您的收银台界面以完全控制您的结账体验。我们建议您根据您的需求和能力做出选择。 ## 推荐的集成 ### 收银台-跳转收银台 如果您想花费最少的技术精力在您的网站上运行结账页面，请尝试将客户重定向到PingPongCheckOut托管页面，以便您可以专注于对您重要的事情。我们负责整个付款过程。 ### 收银台-内嵌 SDK 如果您想在结账时向客户显示统一的付款方式列表，同时仍然希望自定义某些页面外观，请尝试集成js sdk，而无需广泛的前端开发工作。 ### S2S 如果您想完全控制结账页面的外观，并让您的客户通过您的用户界面付款，请尝试通过在后端直接使用我们的API构建来处理交易。请注意，此选项需要更多的时间和开发资源来实施和维护。 ## 无代码集成 ### 支付链 嵌入或共享一个到 PingPongCheckout 支付页面的链接，以接受没有网站的付款。 详见支付链 ## 与平台或插件集成 ### 平台 更多平台支持详见SaaS 建站平台 ### 插件 更多插件支持详见Plugins --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/payByLink/index.md description: >- 支付链是PingPong提供给商户的一种快捷收单方式，适用于无需网站对接的场景。通过在PingPongCheckout后台添加支付信息，生成链接发送至用户邮箱，用户点击后进入支付页面完成交易。支持全球范围内的支付，主要特点包括操作简便、快速集成。使用前需联系运营开通权限。 --- # 支付链 ## 支付链 支付链是PingPong提供给商户进行快捷收单操作的产品，无需商户网站对接，在PingPongCheckout商户后台添加支付链信息后，会发送支付链接到用户邮箱，用户访问支付链接即可通过PingPongCheckout支付收银台进行支付，支付完成后，商户可以登录到商户后台查看订单。 :::note 提示 支付链仅提供给部分商户使用，如需开通，请先联系运营开通相关权限 ::: 具体如何开通支付链，可以点击查看操作手册。 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/plugin/index.md' description: >- 插件模块介绍了一系列为开源电子商务平台设计的集成解决方案，旨在优化结账流程。这些插件支持PingPongCheckout支付功能，易于安装且配置简单，适用于希望提升客户支付体验的商家。 --- # Plugins 我们为主流的开源E-Commerce解决方案提供一系列插件，为您的购物者提供最佳的结账体验。我们的插件易于集成， 并配有开箱即用的PingPongCheckout支付平台功能。 ## 支持的插件 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/prestashop/index.md description: >- 该文档介绍Prestashop-PPPay插件的安装步骤，适用于版本1.7.6.6及以上的Prestashop商店。涵盖安装前提条件、具体安装过程以及配置商户参数的方法。同时提供沙箱环境和生产环境对接流程，包括测试卡号、截图验证等关键步骤，确保支付功能正确无误地集成到商店中。 --- # Prestashop-PPPay插件安装 ## 安装前提 > * Prestashop version = 1.7.6.6 > * php version >= 5.6 && <= 7.3 > * MySQL version 5.6, 5.7 > * chmod 777 /webRoot/Prestashop/var/logs 以下为非必要设置，若出现504错误可以检查下列选项 * \[ ] php ini执行超时时间 * \[ ] nginx 或者 apache 设置执行超时时间 payResultUrl *** ::: danger 注意 1. 同一个accId下订单号不能重复，必须是单调递增的，否则会引发订单状态问题； 2. 来源于不同数据库的订单不能共用同一个accId； 3. accId下已经有过交易，安装插件之前应该将id起始值设置为大于当前订单id最大的值； 4. 重置数据库，商店，或者accId迁往别的商店，应该检查accId下订单号最大值。 ::: ### 插件下载 ps\_pingpongpay.zip *** ## 安装过程 1. 登录网站后台 `选择 模块-> Module Manager ->上载插件 `  3. 将插件包拖入上传对话框 等待解包和安装执行完成  4. 等待安装完成  5. 安装完成之后 出现配置按钮 点击配置开始配置商户参数 6. 商户参数配置 ```text title="商户环境配置参数" line-numbers # [!code highlight] PingPong支付环境地址 沙箱环境 https://sandbox-acquirer-payment.pingpongx.com 生产环境 https://acquirer-payment.pingpongx.com # [!code highlight] 沙箱环境店铺参数 clientId: 2018092714313010016 accId: 2018092714313010016291 salt: F78BC96A55548B2319EE68E0 # [!code highlight] 沙箱环境测试卡号 卡号：4200000000000000 有效期：12/22 cvv: 123 其它随便填, cvv需为3位纯数字 ```  7. 点击保存 保存商户参数 安装完成 可以测试支付流程 ## 环境参数 ### 沙箱环境店铺参数 ```text title="沙箱环境店铺参数" line-numbers # [!code highlight] PingPong沙箱环境店铺参数 clientId: 2018092714313010016 accId: 2018092714313010016291 salt: F78BC96A55548B2319EE68E0 ``` ### 沙箱环境测试卡号 ```text title="沙箱环境测试卡号" line-numbers # [!code highlight] 标准测试卡号 卡号：4200000000000000 有效期：12/22 cvv: 123 cvv需为3位纯数字 # [!code highlight] 3DS交易测试卡号 3DS交易卡：4711100000000000 ``` ### 环境地址 ```text title="PingPong支付环境地址" line-numbers # [!code highlight] 沙箱环境地址 沙箱环境 https://sandbox-acquirer-payment.pingpongx.com # [!code highlight] 生产环境地址 生产环境 https://acquirer-payment.pingpongx.com ``` ## 对接过程 ### 沙箱环境对接 1. 按照文件安装插件。 2. 插件安装完成之后，需要进行支付自测，并完成以下事项： * \[ ] 截图输入卡号的页面 * \[ ] 截图支付完成的最终跳转页面 * \[ ] 将截图发送到对接群，并通知技术支持 安装过程，有任何问题可以在对接群里需求技术支持。 *** 注意事项： > 沙箱环境下，不会对持卡人发起扣款，支付之后发货将造成损失，不发货持卡人可能会发起投诉。因此在对接期间，需要谨慎操作，对接测试通过之后，因立即关闭支付通道，等待生产环境上线之后打开。 *** ### 生产环境对接 * 插件在技术支持下完成第一轮的沙箱环境对接后将进入，网站资料和账户审查阶段，通过之后，会发放生产环境参数。 * 获取到生产参数之后，完成以下事项 * \[ ] 将沙箱环境参数替换为生产参数。 * \[ ] 自测支付，并完成截图 * \[ ] 准备一个$1的商品链接。 发送截图和商品链接，并通知技术支持，将由客户/技术支持对该商品链接发起真实交易测试。以验证对接结果和网站支付可用性。 * 完成真实交易测试之后，需要商户发起退款，以便于验证退款流程。 * 完成以上流程，网站对接结束，支付通道正式上线，支付可用。 ### 生产环境配置 ### 审核过程 从对接群中或者商务/客户处获得通知，审核通过。登录[商户后台](https://pay.pingpongx.com/aq/websiteList) ```text:line-numbers title="urls/merchant-backend.txt" https://pay.pingpongx.com/aq/websiteList ``` ### 前往网站列表 如图所示，前往群组管理->查看详情->网站列表 ### 群组管理 > * ⚫ 从菜单栏选择【网站管理】-【群组管理】进入群组管理页面 > * ⚫ 该功能实现当前商户可点击“创建群组”新建群组;系统默认会给一个默认的群组 > * ⚫ 网站下挂于群组。 > * ⚫ 点击“查看详情”进入群组详情页面，可修改群组名称、查看复制 ID 号、查看群组下的网站。  ### 选择网站 根据当前对接网站的域名，在列表中选择对应的网站  ### 获取对应域名网站的accId  ### 获取秘钥 > 从菜单栏选择【系统管理】-【秘钥管理】默认进入秘钥管理页，可在此页面查 看网站秘钥。进入秘钥管理后，可查看所有网站对应的秘钥，点击“秘钥详情”查看具体秘 > 钥字段。 > 状态为“正常”的秘钥可使用，当状态为“异常”时，将无法使用可联系相关业务 人员处理。  --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/sass/index.md' description: >- 介绍如何在主流SaaS建站平台上集成PingPongCheckout支付，适用于希望无需额外开发即可快速接入支付解决方案的商家。只需简单配置，支持Shopify、Magento等平台，覆盖全球主要市场，提供安全便捷的支付体验。 --- # SaaS 建站平台 PingPongCheckout和主流的SaaS建站服务提供商建立了合作。您在平台上的店铺，无需任何开发投入，只需在我们的引导下， 做一些简单的设置，即可接入PingPongCheckout支付。 ## 支持的建站平台 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/integrate/sdk-elements/index.md description: >- PingPong Element SDK 支持下单并支付、绑定钱包等多元支付场景。采用全新架构设计,提供统一的API接口、灵活的事件模型和可扩展的支付组件。集成流程包括引入SDK脚本、初始化配置、创建支付元素、事件监听与处理,并提供营销活动集成功能。 --- # PingPong Element SDK 集成指南 ## SDK集成流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant User as 👤 用户 participant Browser as 🌐 浏览器 participant Frontend as 💻 商户前端 participant Backend as 🏪 商户后端 participant SDK as 📦 Element SDK participant PP as 🔄 PingPong服务端 Note over User, PP: 🚀 Element SDK 完整集成流程 User->>Browser: 选择商品 Browser->>Frontend: 打开支付页面 Note over Frontend, Backend: 📋 初始化阶段 Frontend->>+Backend: 请求初始化 sdkAccessToken Backend->>+PP: 请求初始化 sdkAccessToken PP-->>-Backend: 返回初始化 sdkAccessToken Backend-->>-Frontend: 返回初始化 sdkAccessToken Frontend->>+SDK: 使用 sdkAccessToken 初始化 SDK Note right of SDK: PingPongSDK.init() SDK->>+PP: 查询店铺配置 PP-->>-SDK: 返回店铺配置 SDK-->>-Frontend: SDK 初始化完成 SDK->>Frontend: 触发 ready 事件 Frontend->>SDK: 创建支付元素 Note right of SDK: createElement() SDK-->>Frontend: 支付元素已就绪 Frontend->>Browser: 在支付页面中渲染支付按钮 Note over User, PP: 💳 支付流程开始 Frontend->>User: 显示支付按钮 User->>Frontend: 点击支付按钮 Frontend->>+SDK: 触发支付流程 SDK->>+Frontend: 调用 createOrder() activate Frontend Note over Frontend: 校验 billing、shipping、优惠券 Frontend->>+Backend: 发送订单详情 Backend->>+PP: 下单（原V4下单接口） PP-->>-Backend: 返回交易 token Backend-->>-Frontend: 返回交易 token Frontend-->>-SDK: 从 createOrder 返回 token deactivate Frontend SDK->>+PP: 请求支付（支付信息 + token） PP->>PP: 处理支付 Note right of PP: • 风控检查
• 支付路由
• 第三方调用 PP-->>-SDK: 支付响应 alt ❌ 支付失败 SDK->>Frontend: 调用 error(code, msg) activate Frontend Note over Frontend: 处理支付失败逻辑 deactivate Frontend else ✅ 支付成功或处理中 SDK->>Browser: 跳转到支付结果页面 Note right of Browser: merchantResultUrl else 🔒 需要 3DS 验证 SDK->>Browser: 跳转到 3DS 验证页面 end Note over User, PP: 🎯 支付流程结束 ``` ## 架构设计 ### 核心模块 | 模块 | 职责 | | --- | --- | | **PingPongSDK** | SDK 唯一入口,暴露 init / createElement 方法 | | **PingPongElement** | 所有支付按钮的基类,提供 .on() / .off() 事件机制 | ### 支付模式 SDK 支持两种主要模式: * **Payment**: 下单并支付模式,适用于标准支付流程 * **Vault**: PayPal 独立签约模式,用于绑定钱包 ## 接入流程 ### 1. 获取 sdkAccessToken 商户后端系统通过调用获取 sdkAccessToken 接口得到访问凭证。 **支付场景:** * 调用 `/v4/session/init` 接口获取 sdkAccessToken **签约场景:** * POST 调用已有签约接口获取 sdkAccessToken 和 JS URL ### 2. 引入 Element SDK 根据您的业务环境,选择相应的 SDK 版本进行引入: :::: code-tabs @tab 🧪 沙箱环境 ```html ``` @tab 🇪🇺 FRA 生产环境 ```html ``` @tab 🇸🇬 SG 生产环境 ```html ``` :::: ### 3. 初始化 SDK #### 入参说明 ::::: field-group :::: field name="mode" type="string" required 业务模式 `Payment`(支付) 或 `Vault`(PayPal 独立签约) :::: :::: field name="env" type="string" required 运行环境 `sandbox`(沙箱) 或 `production`(生产) :::: :::: field name="amount" type="string" required 交易金额 用于收银台展示 :::: :::: field name="currency" type="string" required 交易币种 :::: :::: field name="country" type="string" required 国家/地区代码 如 `US`、`CN`、`UK` 等 :::: :::: field name="accId" type="string" required 商户账户 ID :::: :::: field name="locale" type="string" required 界面语言 `en`、`zh-CN` 等 :::: :::: field name="region" type="string" optional default="fra" 地区 `sg` 或 `fra` :::: :::: field name="sdkAccessToken" type="string" required SDK 访问凭证 :::: :::: field name="merchantResultUrl" type="string" required 支付完成后的跳转地址 :::: :::: field name="createOrder" type="Function" optional 下单函数 mode 为 `Payment` 时必传。该函数接收一个包含 `payMethod` 的对象参数,表示用户选择的支付方式 :::: :::: field name="goods" type="Array" required 商品信息数组 详见下方 [goods 数组结构](#goods-数组结构) :::: :::: field name="biztype" type="string" optional 业务类型 可选值: `CodeGrant` :::: :::: field name="recurringInfoDTO" type="Object" optional Recurring 配置，ApplePay 签约必传 :::: ::::: #### 初始化示例 ```javascript:line-numbers title="src/sdk-init.js" await PingPongSDK.init({ mode: 'Payment', // 业务模式: Payment 或 Vault env: 'sandbox', // 运行环境 amount: '19.99', // 交易金额 currency: 'USD', // 交易币种 country: 'US', // 国家/地区代码 accId: 'ACC_123', // 商户账户ID locale: 'en', // 语言设置 region: 'fra', // 地区: sg 或 fra sdkAccessToken: 'your_sdk_token', // SDK访问令牌 merchantResultUrl: 'https://merchant-result.com', // 支付完成跳转地址 // mode 为 Payment 时必传 createOrder: async ({payMethod}) => { console.log('用户选择的支付方式:', payMethod); // 调用商户后端下单接口 const response = await fetch('/xx/xx', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ payMethod, // 传递支付方式到后端 xx: 'xx' }) }); const result = await response.json(); return result.token; // 返回订单 token }, // 商品信息数组（必填） goods: [ { name: '商品名称', description: '商品描述', imgUrl: 'https://example.com/product.jpg', sku: 'SKU123', unitPrice: '19.99', number: '2', virtualProduct: 'N' } ], // ApplePay 签约时必传 recurringInfoDTO: { recurringPaymentStartDate: '2024-06-01 00:00:00', recurringPaymentIntervalUnit: 'month', recurringPaymentIntervalCount: '6', recurringPaymentEndDate: '2024-12-01 00:00:00' } }); ``` ### goods 数组结构 商品信息数组包含每个商品的详细信息。 ::::: field-group :::: field name="name" type="string" required 商品名称 :::: :::: field name="description" type="string" optional 商品描述 :::: :::: field name="imgUrl" type="string" optional 商品图片 URL :::: :::: field name="sku" type="string" optional 商品 SKU :::: :::: field name="unitPrice" type="string" required 商品单价 :::: :::: field name="number" type="string" required 商品数量 :::: :::: field name="virtualProduct" type="string" optional 是否为虚拟产品 `Y` 或 `N` :::: ::::: **示例:** ```javascript:line-numbers title="src/goods-example.js" goods: [ { name: '无线蓝牙耳机', description: '高品质音质，30小时续航', imgUrl: 'https://cdn.example.com/product1.jpg', sku: 'HEADPHONE-BT-001', unitPrice: '99.99', number: '1', virtualProduct: 'N' }, { name: '音乐会员月卡', description: '畅听千万首正版音乐', imgUrl: 'https://cdn.example.com/product2.jpg', sku: 'VIP-MUSIC-1M', unitPrice: '15.00', number: '1', virtualProduct: 'Y' } ] ``` ### 4. 创建支付元素 #### 4.1 Apple Pay 按钮 ```javascript:line-numbers title="src/apple-pay.js" const applePay = await PingPongSDK.createElement('applePayButton', { buttonType: 'buy', // 按钮类型: buy | plain buttonColor: 'black', // 按钮颜色: black | white | white-outline style: { width: '100%', height: '40px', borderRadius: '4px' }, payDiscount: { // 营销活动配置(可选) activityNo: 'EEE', costAmount: '19.99', // 原始金额 discountAmount: '2.00' // 折扣金额 } }); ``` #### 4.2 Google Pay 按钮 ```javascript:line-numbers title="src/google-pay.js" const googlePay = await PingPongSDK.createElement('googlePayButton', { buttonType: 'buy', // 按钮类型: buy | subscribe buttonColor: 'black', // 按钮颜色: black | white style: { width: '100%', height: '40px', borderRadius: '4px' }, payDiscount: { activityNo: 'EEE', costAmount: '19.99', discountAmount: '2.00' } }); ``` #### 4.3 PayPal 按钮 ```javascript:line-numbers title="src/paypal.js" const paypal = await PingPongSDK.createElement('paypalButton', { buttonType: 'buttons', // buttons | marks | card-fields | funding-eligibility style: { borderRadius: 4, color: 'gold', // gold | blue | silver | white | black height: 40, label: 'paypal', // paypal | checkout | buynow | pay | installment | subscribe | donate layout: 'vertical', // vertical | horizontal shape: 'rect' // rect | pill | sharp } }); // PayPal 不需要监听 completed 事件 // 当支付完成时,SDK 会发起重定向到 merchantResultUrl ``` ### 5. 事件监听 所有支付元素都支持统一的事件模型: ```javascript:line-numbers title="src/event-listeners.js" // 监听 ready 事件 applePay.on('ready', () => { console.log('Apple Pay 已渲染'); }); // 监听 success 事件 applePay.on('success', (event) => { console.log('Apple Pay 支付完成', event.detail); // event.detail 包含 transactionId 等信息 }); // 监听 error 事件 applePay.on('error', (event) => { console.error('Apple Pay 错误', event.detail); // event.detail 包含 code 和 message }); // 监听 cancel 事件 applePay.on('cancel', () => { console.log('Apple Pay 用户取消'); }); ``` ### 6. 挂载与卸载 ```javascript:line-numbers title="src/lifecycle.js" // 挂载到指定容器 applePay.mount('#apple-pay-container'); // 卸载元素 applePay.unmount(); ``` ## API 参考 ### PingPongSDK.init() 初始化 SDK 配置。 **参数:** ::::: field-group :::: field name="mode" type="string" required `Payment` 或 `Vault` :::: :::: field name="env" type="string" required `sandbox` 或 `production` :::: :::: field name="amount" type="string" required 交易金额 :::: :::: field name="currency" type="string" required 交易币种 :::: :::: field name="country" type="string" required 国家/地区代码 如 `US`、`CN`、`UK` 等 :::: :::: field name="accId" type="string" required 商户账户 ID :::: :::: field name="locale" type="string" required 界面语言 :::: :::: field name="region" type="string" optional default="fra" `sg` 或 `fra` :::: :::: field name="sdkAccessToken" type="string" required SDK 访问凭证 :::: :::: field name="merchantResultUrl" type="string" required 支付完成跳转地址 :::: :::: field name="createOrder" type="Function" optional mode 为 `Payment` 时必传。该函数接收一个包含 `payMethod` 的对象参数,表示用户选择的支付方式 :::: :::: field name="goods" type="Array" required 商品信息数组 :::: :::: field name="biztype" type="string" optional 业务类型 可选值: `CodeGrant` :::: :::: field name="recurringInfoDTO" type="Object" optional ApplePay 签约必传 :::: ::::: ### PingPongSDK.createElement() 创建支付元素实例。 **参数:** ::::: field-group :::: field name="type" type="string" required `applePayButton`、`googlePayButton`、`paypalButton` :::: :::: field name="options" type="object" required 元素配置参数 :::: ::::: **返回:** Promise\
生成访问凭证 PP-->>-Merchant: 返回sdkAccessToken Merchant->>Frontend: 2️⃣ 传递sdkAccessToken到前端 Frontend->>Frontend: 3️⃣ 引入JS-SDK脚本 Note right of Frontend: CDN加载:
沙箱/生产环境 Frontend->>+SDK: 4️⃣ 初始化收银台 PingPong.Checkout.create() Note right of SDK: 参数包含:• amount, currency• tradeCountry• sdkAccessToken• paymentMethods SDK->>SDK: 5️⃣ 渲染收银台界面 SDK-->>-Frontend: 收银台准备就绪 opt 🔄 [动态更新 - 可选] Note over Frontend, SDK: 🔧 更新收银台要素:• 金额变化• 国家变化 Frontend->>+SDK: updateCheckoutHook({amount, tradeCountry}) SDK->>SDK: 更新收银台显示 SDK-->>-Frontend: 更新完成 end Note over Frontend, PP: 💳 支付流程开始 Frontend->>+SDK: 6️⃣ 用户点击支付按钮 opt 🔍 [支付前检验 - 可选] SDK->>+Frontend: 7️⃣ 触发beforeCheckoutHook Note right of Frontend: 业务逻辑:• 库存检查• 埋点上报• 订单创建 Frontend->>+Merchant: 调用商户接口 Merchant-->>-Frontend: 返回订单token Frontend-->>-SDK: 返回处理结果 end SDK->>+PP: 8️⃣ 发起支付请求 Note right of PP: 调用下单接口
处理支付逻辑 PP->>PP: 9️⃣ 处理支付 Note right of PP: • 风控检查• 支付路由• 第三方调用 alt ✅ [支付成功] PP-->>SDK: 🎉 支付成功 SDK-->>-Frontend: 支付完成回调 Note over Frontend: 页面跳转
或显示成功信息 else ❌ [支付失败] PP-->>SDK: ❌ 支付失败 SDK->>+Frontend: 🚨 触发checkoutFailedHook Note right of Frontend: 自定义错误处理:• 错误提醒• 日志记录• 重试逻辑 Frontend-->>-SDK: 错误处理完成 SDK-->>Frontend: 显示错误信息 end Note over Merchant, PP: 🎯 SDK集成流程完成 ``` # 接入流程 ## 1. 获取 sdkAccessToken 接口 商户后端系统通过获取 sdkAccessToken 接口 得到JS-SDK访问凭证（token），该凭证用于前端JS-SDK的初始化调用。 ## 2. 引入Javascript-SDK 复制以下代码，通过CDN地址引入 PingPongCheckout Javascript-SDK ::: code-tabs @tab 🧪 沙箱环境 ```html ``` @tab 🇪🇺 FRA 生产环境 ```html ``` @tab 🇸🇬 SG 生产环境 ```html ``` @tab 🇺🇸 US 生产环境 ```html ``` ::: ### 3. 初始化收银台 将 `pp-checkout` 标签插入 `html` `body` 中 ```html:title="components/checkout.html" :line-numbers
${message}
PingPong 支付收银台
正在初始化收银台...
PingPong 支付收银台
正在初始化收银台...
{{ error }}
传入token pingpongCheckout-->>-商户网站后端: 3️⃣ 响应结果 商户网站后端-->>-商户网站前端: 返回初始支付状态 Note over 持卡人,pingpongCheckout: 🚀 token支付过程 loop 轮询获取支付状态 商户网站前端->>+商户网站后端: 查询支付状态 商户网站后端-->>-商户网站前端: 返回当前支付状态 Note over 商户网站前端: 若状态为最终状态则结束轮询 end 商户网站前端-->>-持卡人: 显示最终支付结果 pingpongCheckout->>+商户网站后端: 4️⃣ 📡 异步通知 商户网站后端-->>-pingpongCheckout: 5️⃣ 🟢 响应OK ``` [//]: # "
" [//]: # "
"
[//]: # " ![]()
"
[//]: # "
"
以下是需要集成的API清单
下单并支付接口
调 下单并支付接口 传入token，bizType和merchantUserId。
##### 关键入参:
| 参数名 | 类型 | 是否必填 | 描述 |
|----------------|--------|------|--------------------------------|
| token | String | M | 已有字段，传授权或者签约完成获取的token |
| bizType | String | M | 已有字段，新增类型标识认证授权,固定传"CodeGrant" |
| merchantUserId | String | M | 会员ID，用户在商户网站的会员ID |
> 调用下单并支付接口的时候入参中必须要传入merchantUserId，并且要和认证的时候传入的merchantUserId一致，否则会报错token不存在
下单并支付接口入参示例如下：
::: code-tabs
@tab JSON
```json
{
"accId": "2023042011040310224447",
"clientId": "2023042011040310224",
"signType": "SHA256",
"sign": "{{Sign}}",
"version": "1.0",
"bizContent": {
"captureDelayHours": 0,
"amount": 100,
"currency": "HKD",
"requestId": "{{requestId}}",
"payResultUrl": "https://www.baidu.com",
"notificationUrl": "https://test-acquirerpay.pingpongx.com/qa/notify",
"merchantTransactionId": "{{merchantTransactionId}}",
"shopperIP": "192.168.1.1",
"token": "7dda0a6f6958105204fd6637001f900efd9b3168c948b68b6f7f2bf063eadf97",
"bizType": "CodeGrant",
"merchantUserId": "126048960513465",
"paymentMethod": {
"type": "AlipayHK"
},
"customer": {
"email": "pass@pingpongx.com"
},
"device": {
"orderTerminal": "02"
}
}
}
```
> 其他同现有APM支付参数即可
## 异步通知
::: danger 注意
1. 当http code 为200的时候，表明商户已经收到报文，商户无需返回额外信息。
2. 响应报文异常重试2次
:::
### 签约异步通知
### 支付方式
具体支持使用CodeGrant支付方式列表
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/onlinePayment/features/tokenization/networkToken/index.md
description: >-
NetworkToken是在线支付模块中的一个功能，用于通过卡组token实现安全支付。适用于需要提高交易安全性与效率的场景。关键参数包括paymentMethod.type（固定为networkToken）、schemeTokenValue（卡组token）、paymentBrand（卡品牌，支持
---
# NetworkToken
## 关键入参说明
使用NetworkToken支付必须要在下单接口或者下单并支付接口的入参基础上添加下面这几个参数：
| 参数字段 | 参数类型 | 参数属性 | 参数说明 |
|-----------------------------------------|------------|------|-----------------------------------------|
| paymentMethod.type | String(16) | C | 固定传入：networkToken，如果用卡组的token必传 |
| paymentMethod.cardInfo.schemeTokenValue | String(16) | C | 卡组的token，如果用卡组的token必传 |
| paymentMethod.cardInfo.paymentBrand | String(16) | C | 卡品牌，如果用卡组的token必传，可选值为visa/MasterCard |
| paymentMethod.cardInfo.tokenCryptogram | String | C | 加密的数值字符串，用于验证卡片和终端之间的交易数据。如果用卡组的token必传 |
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/onlinePayment/features/tokenization/overview/index.md
description: >-
Tokenization技术用于安全存储购物者的支付信息，支持主要卡品牌及部分本地支付方式。通过生成令牌，可实现更快的结账、订阅支付、自动充值等功能。首次支付时收集支付信息并生成令牌，后续支付使用该令牌即可。默认按商户accId存储令牌。若未完全符合PCI
DSS要求，建议使用Tokenizatio
---
# Tokenization
## Tokenization
使用Tokenization 技术允许您安全地存储每个购物者的一个或多个支付信息。
这样，您可以提供订阅支付、购物者账户自动充值以及通过使用他们存储的卡片提供更快的结账体验。
我们支持主要的卡品牌和一些本地支付方式。
令牌化的好处包括：
1. 允许购物者存储他们的支付信息，以便之后更快地结账。
2. 向购物者提供他们存储的支付信息以便后续支付。
3. 为订阅或非固定时间表的合同保存支付信息。
4. 提交订阅的后续支付或购物者账户的自动充值。
要保存购物者的支付信息，您只需要在进行支付时传递一些额外的参数。在首次支付中，我们从购物者那里收集支付信息并为其生成一个令牌。然后，令牌被发送到您的服务器以供将来使用。对于后续支付，您需要使用令牌发出请求。
默认情况下，令牌按商户accId存储。
::: warning 提示
要收集原始的信用卡数据，您需要完全符合PCI DSS（支付卡行业数据安全标准）的要求。如果您已经完全符合PCI DSS的要求，您可以选择创建自己的令牌保险库（Token Vault），或者存储原始信用卡数据以提供更快的结账选项。
:::
::: note 提示
如果您还没有完全符合PCI DSS（支付卡行业数据安全标准）的要求，我们建议您使用Tokenization 技术来进行支付。通过使用令牌，您可以为您的购物者提供改进的结账体验。
:::
## 实施方案
您可以为以下几种定期支付类型创建并使用令牌进行支付：
* 国际信用卡: CardOnFile
* 本地支付: CodeGrant
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/onlinePayment/integration/index.md
description: >-
快速启动指南帮助开发者简化PingPongCheckout在线支付API的集成过程。文档涵盖支付回调和查单实现，指导用户从零开始到调试完成整个流程，并提供参考文档支持。适用于需要快速接入安全支付解决方案的电子商务网站与应用，确保交易顺利进行的同时提升用户体验。
---
# 支付回调和查单实现指引
## 快速启动
## 简化您的集成应用
## 调试您的应用
## 参考文档
## 集成您的业务
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/onlinePayment/IssuerResponseCodes/index.md
description: >-
发卡行响应代码定义了在线支付过程中银行返回的各种状态码及其含义。适用于处理支付请求时遇到的不同错误情况，帮助开发者快速定位问题并采取相应措施。每个响应代码对应特定的支付失败原因，如账户余额不足、卡片过期等，确保交易流程的透明度和可控性。
---
# Issuer Response Codes
## 发卡行响应代码
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/onlinePayment/Klarna/index.md
description: >-
Klarna测试资源提供用于在线支付集成的测试账号和支付物料信息，支持美国、芬兰、德国及奥地利等地区的支付模拟。关键特性包括对账单和运输地址信息的严格校验，以及虚拟行业接入时的特殊配置需求。
---
# Klarna测试资源
### 测试账号：
| clientId | accId | salt |
|:--------------------|:-----------------------|:-------------------------|
| 2022092115464510103 | 2022092115464510103123 | 79DAA521F03DC90BAB03B070 |
### 支付物料：
| country | currency | phone | code | name | street | postcode | city |
|:--------|:---------|:--------------|:-------|:------------------|:------------------------|:---------|:---------|
| US | USD | 3055787342 | 123456 | John Doe | 123 Main St Apartment 4 | 10001 | New York |
| FI | EUR | 358040123456 | 123456 | Matti Meikäläinen | Esimerkkikatu 123 | 00100 | Helsinki |
| DE | EUR | 4901761428434 | 123456 | Max Mustermann | Musterstraße 123 | 10115 | Berlin |
| AT | EUR | 6762600456 | 123456 | Johann Schmidt | Hauptstraße 50 | 1040 | Wien |
Klarna对 billing，shipping中的国家，城市，地址信息会做严格校验，测试的时候不同国家需要取不同的支付物料信息。
::: tip
虚拟行业在接入时需要提前报备，在报备配置完成情况下可免除billing,shipping相关信息收集。沙箱环境联调可提前告知技术支持人员进行沙箱环境特殊配置
:::
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/onlinePayment/modify/Capture/index.md
description: >-
Capture功能用于国际信用卡支付等支持单独捕获的支付方式，分为授权和捕获两个步骤。支持自动和手动捕获策略，默认为自动捕获。手动捕获需设置captureDelayHours参数并调用CAPTURE-预授权确认API。关键参数包括merchantTransactionId、merchantCaptu
---
# Capture
## 业务流程
对于支持单独Capture(捕获)的支付方式（如国际信用卡支付），支付过程分为两个步骤完成：
* Authorization：验证购物者的支付细节与发行方，并预留资金。
* CAPTURE：将预留的资金从购物者转移到您的账户。
```mermaid
sequenceDiagram
participant 商户网站 as 🏪 商户网站
participant pingpongCheckout as 🔄 pingpongCheckout
rect rgb(191, 223, 255)
note right of 商户网站: 📋 请求流程
activate 商户网站
activate pingpongCheckout
pingpongCheckout->>商户网站: 1️⃣ 🔐 Authorization状态: AUTH_SUCCESS
商户网站->>pingpongCheckout: 2️⃣ 💰 Capture 请求
pingpongCheckout->>商户网站: 3️⃣ 📊 Capture响应
deactivate 商户网站
deactivate pingpongCheckout
end
rect rgb(200, 220, 240)
note right of 商户网站: 📡 异步通知流程
activate 商户网站
activate pingpongCheckout
商户网站-->>pingpongCheckout: 📡 Capture 异步通知
pingpongCheckout-->>商户网站: 🟢 响应200
deactivate 商户网站
deactivate pingpongCheckout
end
```
[//]: # "bizType=Recurring pingpongCheckout-->>-商户网站后端: 3️⃣ 响应支付结果 deactivate 商户网站后端 Note over 商户网站前端,pingpongCheckout: 🔐 授权流程（首次支付） %% 轮询流程 activate 商户网站前端 loop 轮询支付状态 商户网站前端->>+商户网站后端: 4️⃣A 查询订单状态 商户网站后端-->>-商户网站前端: 5️⃣A 返回订单状态 end deactivate 商户网站前端 %% 异步通知流程（独立流程） pingpongCheckout-->>+商户网站后端: 4️⃣B 📡 异步通知 activate 商户网站后端 商户网站后端->>-pingpongCheckout: 5️⃣B 🟢 响应OK deactivate 商户网站后端 ``` [//]: # "
"
[//]: # " ![]()
"
[//]: # "
"
::: steps
1. 客户端向商户服务端发起订阅支付
用户在商户平台上选择订阅服务并发起支付请求
2. 商户服务端请求PingPongCheckout服务端
商户系统向PingPongCheckout发起一笔标记为订阅支付的交易
3. PingPongCheckout服务端响应支付结果
处理结果分为两种情况：
* 支付成功：授权成功，后续可以发起计划扣款
* 支付失败：授权失败，不能发起计划扣款
:::
### 计划扣款事件交互流程
```mermaid
sequenceDiagram
participant 商户网站后端 as 🏪 商户网站后端
participant pingpongCheckout as 🔄 pingpongCheckout
activate 商户网站后端
商户网站后端->>商户网站后端: 1️⃣ 🕐 商户定时任务触发
商户网站后端->>+pingpongCheckout: 2️⃣ 请求统一下单接口带上以下标记
bizType=Recurring
primaryMerchantTransactionId pingpongCheckout-->>-商户网站后端: 3️⃣ 响应支付结果 deactivate 商户网站后端 Note over 商户网站后端,pingpongCheckout: 💰 计划扣款（再次支付） %% 异步通知流程（独立流程） pingpongCheckout-->>+商户网站后端: 4️⃣ 📡 异步通知 activate 商户网站后端 商户网站后端->>-pingpongCheckout: 5️⃣ 🟢 响应OK deactivate 商户网站后端 ``` [//]: # [//]: # "
"
[//]: # " ![]()
"
[//]: # "
"
::: steps
1. 商户服务端执行计划扣款
根据订阅计划，商户系统在指定时间触发扣款流程
2. 商户服务端请求PingPongCheckout服务端
调用[下单并支付](/notes/zh/checkout/api/uniformly/)接口，发起一笔标记为订阅支付的交易，并带上发生授权时候的商户订单号
3. PingPongCheckout服务端响应支付结果
系统处理扣款请求并返回处理结果
:::
## API清单
## 服务端接入
### 持卡人授权
| 字段名称 | 类型 | 必填 | 描述 |
|:-----------------------------|:-----------|:----|:------------------------------------|
| bizType | String(64) | M | Recurring交易标识，固定值`Recurring` |
在请求下单并支付 时候新增参数`bizType`=`Recurring`，标记当前交易为recurring交易
### 计划扣款
| 字段名称 | 类型 | 必填 | 描述 |
|:-----------------------------|:-----------|:----|:------------------------------------|
| primaryMerchantTransactionId | String(64) | M | 首次成功下单时候异步通知中的merchantTransactionId |
| bizType | String(64) | M | Recurring交易标识，固定值`Recurring` |
商户服务端请求下单并支付，发起计划扣款
* 新增参数`bizType`=`Recurring`，标记当前交易为recurring交易
* 新增参数`primaryMerchantTransactionId`，值为首次扣款时候的`merchantTransactionId`
* 参数`cardInfo`由`primaryMerchantTransactionId`代替，不用传送
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/onlinePayment/sandbox/index.md
description: >-
沙箱环境提供给开发者进行接口开发和调试，账号仅限于该环境中使用。访问地址为https://sandbox-acquirer-payment.pingpongx.com。提供了多种测试账号与支持的本地支付方式，包括Wechat
Pay、AlipayCN等，并列出了可用于测试的卡号及其属性，如是否支持3
---
# 沙箱环境使用说明
沙箱环境用于开发者进行接口开发、调试，沙箱环境的账号仅可以在沙箱环境中使用。
## 访问地址
| env | host |
|:----|:-----------------------------------------------|
| 沙箱 | https://sandbox-acquirer-payment.pingpongx.com |
## 沙箱环境测试资源
### 测试账号
| clientId | accId | salt | 支持的本地支付方式 |
|:--------------------|:-----------------------|:-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 2018092714313010016 | 2018092714313010016289 | BCE27A281029F5EAF3CC0E82 | Klarna Wechat Pay AlipayCN AlipayHK DANA TrueMoney Wallet Rabbit LINE Pay GCash Boost TNG eWallet BPI |
| 2018092714313010016 | 2018092714313010016291 | F78BC96A55548B2319EE68E0 | DOKU BLIK EPS Giropay Multibanco Mybank Trustly PaybyBank Paysera Bancontact Grab Pay Skrill PromptPay |
### 测试卡号
| 测试卡号 | 过期年月 | cvv | 卡品牌 | 卡是否支持3DS | 可能的支付结果 |
|:-----------------|:--------|:------|:-----------------|:---------|:--------|
| 4012001037141112 | 12/27 | 840 | VISA | 不支持 | 成功/失败 |
| 5204740000001002 | 任意的将来时间 | 任意三位数 | Masrercard | 支持 | 成功/失败 |
| 5200000000001096 | 任意的将来时间 | 任意三位数 | Masrercard | 支持 | 成功/失败 |
| 341111599241000 | 12/25 | 123 | American Express | 不支持 | 成功/失败 |
| 6250947000000014 | 12/33 | 123 | CHINA\_UNION\_PAY | 不支持 | 成功/失败 |
::: note 提示
3D挑战页验证码: 1234
:::
## 测试用例
测试用例
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Afterpay/index.md
description: >-
Afterpay是一种先购买后分期付款的支付方式,适用于希望为客户提供灵活支付选项的在线商家。主要特点包括四次无息分期付款、覆盖澳大利亚、美国、英国等市场以及简单的集成流程,有助于提高转化率和平均订单价值。
---
# Afterpay
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/AkuLaku/index.md
description: >-
AkuLaku是一种先买后付的支付方式,主要服务于东南亚市场,允许消费者分月付款。该支付方式无需信用卡即可使用,支持多种还款期限选择,为用户提供了灵活便捷的支付体验,特别适合在线购物和小额消费场景。
---
# AkuLaku
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Alfamart/index.md
description: >-
Alfamart是一种在印度尼西亚广泛使用的现金支付方式，允许用户通过遍布全国的便利店网络进行支付。适用于没有银行账户或信用卡的消费者，支持在线购物、账单支付等多种场景。主要特点包括即时确认交易和广泛的地理覆盖范围。
---
# Alfamart
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Alipay/index.md
description: >-
Alipay是一种广泛应用于中国及部分亚洲地区的在线支付方式,支持网页、移动应用等多种场景。用户可通过支付宝账户或绑定银行卡完成快速安全的支付。商家接入Alipay后,能够覆盖更广泛的消费群体,提升交易成功率。
---
# Alipay
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/AlipayHK/index.md
description: >-
AlipayHK是一种在香港地区广泛使用的电子支付方式，支持用户通过手机应用进行线上及线下支付。主要特点包括便捷的二维码支付、即时转账以及丰富的本地化服务如缴费、购票等。适用于各类商户接入以满足香港消费者的支付需求。
---
# AlipayHK
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ApplePay/index.md
description: >-
Apple Pay 是一种安全无缝的支付方式，适用于应用内、实体店和网页支付。采用Tokenization技术存储支付信息，并通过Touch ID或Face
ID进行支付确认。在欧洲实施时符合PSD2 SCA要求。用户需使用兼容设备、Safari浏览器（网页支付）、位于支持地区并已添加银行卡至App
---
# ApplePay
Apple Pay 提供了一种安全且无缝的支付方式，可以在应用内、实体店和网页上使用。Apple Pay 采用Tokenization技术，将支付信息安全地存储在用户的 Apple Pay 兼容设备中，并通过 Touch ID 或 Face ID 进行支付确认。如果你在欧洲实施 Apple Pay，它是符合 PSD2 SCA（强客户认证）要求的。
当用户选择 Apple Pay 时，会显示一个支付表单，用户可以在其中选择银行卡并提供联系信息和送货地址。然后，系统会提示用户通过 Face ID 或 Touch ID 进行支付认证。
**付款人只有在满足以下条件时才能使用 Apple Pay 作为支付方式选项：**
1. 使用[兼容 Apple Pay 的设备](https://support.apple.com/en-us/102896)
2. 如果在网页上支付，则使用 Safari 浏览器。
3. 位于[Apple Pay 可用的国家或地区](https://support.apple.com/en-us/102775)
4. 已在他们的 Apple Pay 钱包中添加了一张现有的银行卡。详见[如何设置 Apple Pay](https://support.apple.com/zh-cn/guide/iphone/iph9b7f53382/ios)
**PCI合规和风控要求**
| 集成方式 | PCI DSS | 风控JS | 3DS组件 |
|:-----------------|:--------|:-----|:------|
| 内嵌收银台 | 无需 | 无需 | 无需 |
| 跳转收银台 | 无需 | 无需 | 无需 |
| Server To Server | 需要 | 无需 | 无需 |
---
---
url: >-
https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ApplePay/checkout/index.md
description: >-
介绍Apple Pay收银台集成流程，包括跳转收银台交互和订阅支付集成。适用于需要支持Apple
Pay支付的商户，覆盖全球多个地区。关键特性包括预下单获取支付URL、渲染收银台以及订阅支付模式下的自动扣费功能。集成过程中需设置`merchantUserId`、`createToken`等参数以建立
---
# Apple Pay 收银台集成
## ApplePay-跳转收银台交互流程
```mermaid
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#E3F2FD',
'primaryTextColor': '#0D47A1',
'primaryBorderColor': '#1976D2',
'lineColor': '#1565C0',
'secondaryColor': '#BBDEFB',
'tertiaryColor': '#90CAF9',
'background': '#F8FBFF',
'mainBkg': '#E3F2FD',
'secondBkg': '#BBDEFB',
'tertiaryBkg': '#90CAF9',
'actorBkg': '#2196F3',
'actorBorder': '#1976D2',
'actorTextColor': '#FFFFFF',
'actorLineColor': '#1565C0',
'signalColor': '#0D47A1',
'signalTextColor': '#0D47A1',
'c0': '#E8F4FD',
'c1': '#D1E7DD',
'c2': '#B3D9FF',
'c3': '#81C784',
'noteBkgColor': '#E1F5FE',
'noteTextColor': '#01579B',
'noteBorderColor': '#0288D1',
'loopTextColor': '#0D47A1',
'activationBkgColor': '#B3E5FC',
'activationBorderColor': '#0277BD'
}
}}%%
sequenceDiagram
participant Merchant as 🏪 商户后端
participant Frontend as 💻 商户前端
participant PP as 🔄 PingPong服务端
participant Hosted as 🛒 跳转收银台
participant Apple as 🍎 Apple Pay
Note over Merchant, Apple: 🚀 Apple Pay跳转收银台集成流程
Note over Merchant, Frontend: 📋 准备阶段:• 获取访问凭证• 准备跳转链接
Merchant->>+PP: 1️⃣ 获取paymentUrl
Note right of PP: 调用收银台预下单接口生成支付链接 PP-->>-Merchant: 返回paymentUrl Merchant->>Frontend: 2️⃣ 传递跳转参数到前端 Frontend->>Frontend: 3️⃣ 构建跳转链接 Note right of Frontend: 使用paymentUrl构建完整链接 Frontend->>+Hosted: 4️⃣ 跳转到PingPong收银台 Note right of Hosted: 在新窗口或当前页面打开收银台页面 Hosted->>Hosted: 5️⃣ 初始化收银台界面 Note right of Hosted: 显示支付方式列表
加载Apple Pay组件 Hosted-->>-Frontend: 收银台加载完成 Note over Hosted, Apple: 💳 Apple Pay支付流程 User->>Hosted: 6️⃣ 用户选择Apple Pay支付 Hosted->>+Apple: 7️⃣ 调用Apple Pay API Note right of Apple: • 显示Apple Pay界面• Touch ID/Face ID验证• 获取支付令牌 Apple-->>-Hosted: 返回加密支付令牌 Hosted->>+PP: 8️⃣ 发送支付请求(含加密令牌) PP->>PP: 9️⃣ 处理支付 Note right of PP: • 解密Apple Pay令牌• 风控检查• 支付路由处理 alt ✅ [支付成功] PP-->>Hosted: 🎉 支付成功 Hosted->>Hosted: 显示成功页面 Hosted-->>Frontend: 可选的页面回调 Note over Frontend: 支付成功处理和页面跳转 else ❌ [支付失败] PP-->>Hosted: ❌ 支付失败 Hosted->>Hosted: 显示错误页面 Hosted-->>Frontend: 可选的错误回调 Note right of Frontend: 错误处理和用户提示 end Note over Merchant, PP: 🎯 Apple Pay跳转收银台流程完成 ``` ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`paymentUrl`用于跳转收银台 ### Step2 渲染收银台 使用Step1获取的`paymentUrl`跳转收银台，接入文档: * 跳转收银台 ## Apple Pay 订阅支付集成 Apple Pay 支持订阅支付模式，允许商户为用户设置定期自动扣费服务。 ### 集成流程 #### Step1 首笔支付（跳转收银台模式） 首次订阅支付需要通过跳转收银台模式完成，用于建立订阅关系并获取支付令牌。使用收银台预下单接口。 **关键参数说明：** | 参数名称 | 参数说明 | 是否必填 | |:---------|:---------|:---------| | `merchantUserId` | 商户用户唯一标识 | 必填 | | `createToken` | 是否创建支付令牌，固定值"Y" | 必填 | | `bizType` | 业务类型，固定值"CodeGrant" | 必填 | | `recurringInfo` | 订阅信息对象 | 必填 | **recurringInfo 订阅信息参数：** | 参数名称 | 参数说明 | 示例值 | |:---------|:---------|:-------| | `recurringPaymentStartDate` | 订阅开始时间 | "2025-06-01 00:00:00" | | `recurringPaymentIntervalUnit` | 扣费周期单位 | "month" | | `recurringPaymentIntervalCount` | 扣费周期数量 | "6" | | `recurringPaymentEndDate` | 订阅结束时间 | "2025-12-01 00:00:00" | **完整请求示例：** **订阅支付特殊参数：** | 参数名称 | 参数值 | |:---------|:-------| | `bizType` | "CodeGrant" | | `createToken` | "Y" | | `merchantUserId` | "126048960513465" | **recurringInfo 参数示例：** ```json "recurringInfo": { "recurringPaymentStartDate": "2025-06-01 00:00:00", "recurringPaymentIntervalUnit": "month", "recurringPaymentIntervalCount": "6", "recurringPaymentEndDate": "2025-12-01 00:00:00" } ``` #### Step2 获取支付令牌 首笔支付成功后，系统会通过交易异步通知返回支付令牌（token）。 ::: warning 重要提醒 * 只有首次交易状态为 `SUCCESS` 时才能获取有效的支付令牌 * 请妥善保存令牌，用于后续自动扣费 * 令牌与 `merchantUserId` 绑定，请确保一致性 ::: #### Step3 后续自动扣费（Non-Hosted模式） 使用获取的令牌进行后续自动扣费，调用下单并支付接口。 **关键参数：** | 参数名称 | 参数说明 | 是否必填 | |:---------|:---------|:---------| | `bizType` | 业务类型，固定值"CodeGrant" | 必填 | | `merchantUserId` | 与首笔支付保持一致 | 必填 | | `token` | 从首笔支付异步通知中获取 | 必填 | **二次扣款请求示例：** **二次扣款特殊参数：** | 参数名称 | 参数值 | |:---------|:-------| | `bizType` | "CodeGrant" | | `merchantUserId` | "126048960513465" | | `token` | "81cf697a30731d407b87b680e044a351" | ### 注意事项 1. **令牌管理**：支付令牌有效期为20年，请关注令牌状态并及时处理失效情况 2. **订阅周期**：合理设置订阅周期，避免过于频繁的扣费 3. **用户体验**：建议在订阅前明确告知用户扣费规则和取消方式 4. **异常处理**：做好扣费失败的处理逻辑，如重试机制、用户通知等 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ApplePay/s2s_decryptionMode/index.md description: >- 介绍如何通过解密Token模式集成ApplePay API，适用于需要符合PCI合规的商户。此模式下，商户使用自持证书对支付Token进行解密，并将信息传递给PingPongCheckout以完成支付流程。主要步骤包括请求下单并支付，以及处理不同状态码如SUCCESS、PROCESSING和FAIL --- # ApplePay API集成-解密Token模式 使用商户的证书，对支付Token进行解密，传送解密信息给PingPongCheckout，获取支付结果。 ## 1.解密Token模式交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Merchant as 🏪 商户后端 participant Frontend as 💻 商户前端 participant Apple as 🍎 Apple Pay participant PP as 🔄 PingPong服务端 Note over Merchant, PP: 🔐 ApplePay解密Token模式交互流程 Note over Merchant, Frontend: 📋 准备阶段:• 前端集成Apple Pay JS API• 商户后端准备证书 Frontend->>+Apple: 1️⃣ 前端调用Apple Pay JS API Note right of Apple: • 显示Apple Pay界面• 用户身份验证• 获取支付令牌 Apple-->>-Frontend: 返回加密支付令牌 Frontend->>Merchant: 2️⃣ 发送加密令牌到商户后端 Note right of Merchant: 接收加密的Apple Pay支付令牌 Merchant->>Merchant: 3️⃣ 使用商户证书解密令牌 Note right of Merchant: • 使用私钥解密• 提取支付信息• 验证令牌有效性 Merchant->>+PP: 4️⃣ 发送解密后的支付信息 Note right of PP: 调用下单并支付API提交解密后的支付数据 PP->>PP: 5️⃣ 处理支付 Note right of PP: • 风控检查• 支付路由• 交易处理 alt ✅ [支付成功] PP-->>-Merchant: 🎉 支付成功响应 Merchant->>Merchant: 更新订单状态 Merchant-->>Frontend: 通知前端支付结果 else ❌ [支付失败] PP-->>-Merchant: ❌ 支付失败响应 Merchant->>Merchant: 记录失败原因 Merchant-->>Frontend: 通知前端支付失败 end Note over Merchant, PP: 🎯 ApplePay解密Token模式流程完成 ``` ## 2. 集成导航 ::: danger 提示 1. 根据您的集成情况，通过API（解密Token模式）接入ApplePay，您需要符合PCI合规。 2. 您需要提前完成对ApplePay API 页面部分交互集成。 ::: ### 请求下单并支付 在API下单并支付的响应中： 1. status 为 `SUCCCESS` 时，订单已支付。 2. status 为 `PROCESSING` 时，订单已创建，但未支付。 3. status 为 `FAILED` 时，订单创建失败。 ## 3. 关键参数 ## 4. 参数示例 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ApplePay/s2s_encryptionMode/index.md description: >- 介绍如何通过PingPongCheckout组件集成Apple Pay API，使用加密Token模式。适用于需要支持Apple Pay支付的商户，覆盖全球主要市场。关键步骤包括传送加密Token至服务端进行解密处理以完成支付。请求下单并支付时，响应状态码`SUCCESS`表示支付成功，`PROCE --- # ApplePay API集成-加密Token模式 使用PingPongCheckout组件，实现Apple Pay API集成。商户传送加密Token给PingPongCheckout服务端，PingPongCheckout服务端对加密Token进行解密，完成支付。 ## ApplePay-加密Token交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant M as 🏪 商户后端 participant F as 💻 商户前端 participant A as 🍎 Apple Pay participant P as 🔄 PingPong服务端 Note over F,A: 1. 发起支付 F->>+A: 调用Apple Pay API A-->>-F: 返回加密令牌 Note over F,M: 2. 令牌传递 F->>M: 发送加密令牌 Note over M,P: 3. 支付处理 M->>+P: 提交到PingPong P->>P: 解密令牌 P->>P: 执行支付 alt 支付成功 P-->>M: 🎉 支付成功响应 Note over M: 更新订单状态 M-->>F: 通知支付成功 else 支付失败 P-->>M: ❌ 支付失败响应 Note over M: 记录失败原因 M-->>F: 通知支付失败 end deactivate P ``` ## 集成导航 ::: note 提示 1. 根据您的集成情况，通过API（加密Token模式）接入ApplePay,要提前完成对ApplePay API 页面部分交互集成 ::: ### 请求下单并支付 在API下单并支付的响应中： 1. status 为 `SUCCCESS` 时，订单已支付。 2. status 为 `PROCESSING` 时，订单已创建，但未支付。 3. status 为 `FAILED` 时，订单创建失败。 ### 关键参数 ### 参数示例 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ApplePay/s2s/index.md description: >- 介绍如何通过Server To Server方式集成Apple Pay，接受信用卡和借记卡付款。适用于需要符合PCI DSS要求的商家。集成步骤包括风控组件和3DS组件集成、请求下单并支付等。支持两种Apple Pay传参方式。 --- # ApplePay集成-S2S 通过集成收银台，接受信用卡和借记卡付款。 ## PCI合规 ::: note 提示 根据您的集成情况，PingPongCheckout 可能要求您提交 PCI DSS 文档，然后才能在生产环境中接受信用卡支付。 ::: 接受Apple Pay付款，需要符合PCI DSS的要求。详见PCI DSS 合规导航 | 集成方式 | PCI DSS | 风控JS | 3DS组件 | |:-----------|:--------|:-----|:-------------| | 内嵌收银台 | 无需 |无需 | 无需 | | 跳转收银台 | 无需 |无需 | 无需 | | Server To Server | 需要 |无需 | 无需 | ## 集成导航 ### Step1 风控组件和3DS组件集成 详见 Dynamic 3D Secure ### Step2 请求下单并支付 在API下单并支付的响应中： 1. status 为 `SUCCCESS` 时，订单已支付。 2. status 为 `PROCESSING` 时，订单已创建，但未支付。 1. `bizContent.threeDContinue` = `false` 无需3DS验证,您可以等待异步通知通知。 2. `bizContent.threeDContinue` = `true`,需要3DS验证，您需要跳转到3DS验证页面。 3. status 为 `FAILED` 时，订单创建失败。 详见 国际信用卡支付 目前，有两种Apple Pay 传参方式被支持： ::: cardList 2 ```yaml - name: Encryption Mode desc: 您传递 Apple 的加密的消息，PingPongCheckout 会自动解密。 bgColor: '#F0DFB1' textColor: '#242A38' - name: Decryption Mode desc: 您预先解密Apple 的加密的消息，并将解密后的消息传递到PingPongCheckout。 bgColor: '#DFEEE7' textColor: '#2A3344' ``` ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ApplePay/sdk_domain_association/index.md description: >- Apple Pay 域名验证指南介绍如何在网站上启用 Apple Pay 功能。适用于希望在其网站上集成 Apple Pay 的商户。关键步骤包括获取和部署验证文件，确保文件路径、名称及内容正确，并支持 HTTPS 访问。完成验证后，Apple 将自动检测并确认域名控制权，允许商户使用 Apple --- # Apple Pay On Web JS-SDK商户域名验证申请流程 ## 1.申请材料 请将`申请材料`发送给邮箱`acq-pmteam@pingpong.com`，并抄送到`acq-tech@pingpongx.com`和 `acq-ts@pingpongx.com`。 1. 商户名称 2. 商户 AccId 3. 商户 ClientId 4. 商户 域名（如果存在多个，请填写多个，注意和accId,clientId保持配对） ## 域名验证流程 为了在您的网站上启用 Apple Pay 功能，您需要完成 Apple 的域名验证流程，证明您对该域名拥有控制权。以下是详细步骤： ### step-1：获取验证文件 1. 您将通过邮件收到一个名为 `apple-developer-merchantid-domain-association.txt` 的验证文件。该文件由Apple 预生成，请勿手动修改。 2. 此文件包含 Apple 预先生成的唯一字符串，用于验证您对域名的所有权。 3. **重要：** 请勿修改此文件的内容，任何更改都将导致验证失败。 ### step-2：部署验证文件 1. 在您的 Web 服务器上创建 `.well-known` 目录（如果尚不存在）。 2. 将 `apple-developer-merchantid-domain-association.txt` 文件上传到此目录中。 3. 确保文件可通过 HTTPS 协议访问。 ``` https://您的域名/.well-known/apple-developer-merchantid-domain-association.txt ``` ## 验证要求 * **文件路径**：必须位于 `/.well-known/` 目录下 * **文件名**：必须严格为 `apple-developer-merchantid-domain-association.txt` * **文件内容**：必须与 Apple 提供的原始内容完全一致 * **访问协议**：必须支持 HTTPS 访问 ## 验证确认 完成部署后，您可以通过以下方式确认验证文件是否正确配置： 1. 在浏览器中访问 `https://您的域名/.well-known/apple-developer-merchantid-domain-association.txt` 2. 确认返回的内容与您收到的原始文件内容完全一致 3. 确认文件能够正常下载且无任何错误 ## shell 脚本示意 下面通过shell脚本说明域名验证文件的部署过程。 ::: danger 提示 此脚本将检查并部署 Apple Pay 域名验证文件。 脚本只做流程说明和参考，请根据您的实际情况进行修改，请勿直接运行。 ::: ```bash #!/bin/bash # Apple Pay 域名验证文件部署脚本 # 配置变量 DOMAIN="example.com" # 替换为您的域名 WEB_ROOT="/var/www/$DOMAIN" # 替换为您的网站根目录 FILE_PATH="$HOME/Downloads/apple-developer-merchantid-domain-association.txt" # 替换为验证文件的本地路径 # 显示欢迎信息 echo "===== Apple Pay 域名验证文件部署工具 =====" echo "域名: $DOMAIN" echo "网站根目录: $WEB_ROOT" echo "验证文件: $FILE_PATH" echo "========================================" # 检查验证文件是否存在 if [ ! -f "$FILE_PATH" ]; then echo "错误: 验证文件不存在于 $FILE_PATH" echo "请确保您已下载 Apple 提供的验证文件" exit 1 fi # 创建 .well-known 目录 echo "正在创建 .well-known 目录..." mkdir -p "$WEB_ROOT/.well-known" if [ $? -ne 0 ]; then echo "错误: 无法创建 .well-known 目录，请检查权限" exit 1 fi # 设置目录权限 echo "设置目录权限..." chmod 755 "$WEB_ROOT/.well-known" # 复制验证文件 echo "复制验证文件到目标位置..." cp "$FILE_PATH" "$WEB_ROOT/.well-known/apple-developer-merchantid-domain-association.txt" if [ $? -ne 0 ]; then echo "错误: 无法复制验证文件，请检查权限" exit 1 fi # 设置文件权限 echo "设置文件权限..." chmod 644 "$WEB_ROOT/.well-known/apple-developer-merchantid-domain-association.txt" # 验证部署 echo "验证文件部署..." if command -v curl &> /dev/null; then echo "使用 curl 验证文件访问..." curl -s -o /dev/null -w "HTTP状态码: %{http_code}\n" "https://$DOMAIN/.well-known/apple-developer-merchantid-domain-association.txt" echo "验证文件内容（前20个字符）:" curl -s "https://$DOMAIN/.well-known/apple-developer-merchantid-domain-association.txt" | head -c 20 echo "..." else echo "curl 未安装，请手动验证文件是否可访问:" echo "https://$DOMAIN/.well-known/apple-developer-merchantid-domain-association.txt" fi echo "========================================" echo "部署完成！请在浏览器中访问以下地址确认验证文件是否正确部署:" echo "https://$DOMAIN/.well-known/apple-developer-merchantid-domain-association.txt" echo "" echo "如果您能看到文件内容，且内容与 Apple 提供的原始文件完全一致，则表示文件已成功部署。" ``` ## 常见问题 * **404 错误**：检查文件路径和名称是否正确 * **内容不匹配**：确认文件未被修改，且未出现编码问题 * **HTTPS 问题**：确保您的域名已正确配置 SSL 证书 完成验证后，Apple 将自动检测您的域名验证状态，验证成功后您将能够在网站上使用 Apple Pay 功能。 > **注意**：域名验证是启用 Apple Pay 的必要步骤，请确保严格按照要求完成配置。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ApplePay/sdk/index.md description: >- ApplePay内嵌收银台集成文档介绍了如何在网站中集成ApplePay支付方式，适用于需要为用户提供便捷支付体验的在线商户。覆盖全球多个国家和地区，支持订阅支付模式。集成流程包括提交域名申请、请求预下单获取accessToken、渲染内嵌收银台以及设置定期自动扣费服务。 --- # ApplePay 内嵌收银台集成 ## ApplePay-内嵌收银台交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Merchant as 🏪 商户后端 participant Frontend as 💻 商户前端 participant PP as 🔄 PingPong服务端 participant Hosted as 🛒 内嵌收银台 participant Apple as 🍎 Apple Pay Note over Merchant, Apple: 📱 ApplePay内嵌收银台交互流程 Note over Merchant, Frontend: 📋 准备阶段:• 获取访问凭证• 准备内嵌收银台 Merchant->>+PP: 1️⃣ 获取accessToken Note right of PP: 调用收银台预下单接口
生成内嵌收银台访问凭证 PP-->>-Merchant: 返回accessToken Merchant->>Frontend: 2️⃣ 传递accessToken到前端 Frontend->>+PP: 3️⃣ 初始化内嵌收银台 Note right of Frontend: 使用accessToken初始化Hosted-JS-SDK PP-->>-Frontend: 返回收银台配置 Frontend->>+Hosted: 4️⃣ 渲染内嵌收银台 Note right of Hosted: 在商户页面内嵌显示收银台
加载Apple Pay组件 Hosted-->>-Frontend: 内嵌收银台加载完成 Note over Hosted, Apple: 💳 Apple Pay支付流程 User->>Hosted: 5️⃣ 用户选择Apple Pay支付 Hosted->>+Apple: 6️⃣ 调用Apple Pay API Note right of Apple: • 显示Apple Pay界面• 用户身份验证• 获取支付令牌 Apple-->>-Hosted: 返回加密支付令牌 Hosted->>+PP: 7️⃣ 发送支付请求(含加密令牌) PP->>PP: 8️⃣ 处理支付 Note right of PP: • 解密Apple Pay令牌• 风控检查• 支付路由处理 alt ✅ [支付成功] PP-->>Hosted: 🎉 支付成功 Hosted->>Hosted: 显示成功页面 Hosted-->>Frontend: 支付成功回调 Note over Frontend: 支付成功处理和页面更新 else ❌ [支付失败] PP-->>Hosted: ❌ 支付失败 Hosted->>Hosted: 显示错误页面 Hosted-->>Frontend: 支付失败回调 Note right of Frontend: 错误处理和用户提示 end Note over Merchant, PP: 🎯 ApplePay内嵌收银台流程完成 ``` ## 集成导航 ::: danger 提示 使用SDK集成需要将您的网站域名提交PingPongCheckout的域名白名单中。 ::: ### step0 提交申请 请将申请材料发送给邮箱`acq-pmteam@pingpong.com`，并抄送到`acq-ts@pingpongx.com` **申请材料如下：** 1. 商户名称 2. 商户 AccId 3. 商户 ClientId 4. 网站域名 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken`用于内嵌收银台渲染 ### Step2 渲染收银台 使用Step1获取的`accessToken`渲染内嵌收银台，接入文档:内嵌收银台 ## Apple Pay 订阅支付集成 Apple Pay 支持订阅支付模式，允许商户为用户设置定期自动扣费服务。 ### 集成流程 #### Step1 首笔支付（内嵌收银台模式） 首次订阅支付需要通过内嵌收银台模式完成，用于建立订阅关系并获取支付令牌。使用收银台预下单接口。 **关键参数说明：** | 参数名称 | 参数说明 | 是否必填 | |:---------|:---------|:---------| | `merchantUserId` | 商户用户唯一标识 | 必填 | | `createToken` | 是否创建支付令牌，固定值"Y" | 必填 | | `bizType` | 业务类型，固定值"CodeGrant" | 必填 | | `recurringInfo` | 订阅信息对象 | 必填 | **recurringInfo 订阅信息参数：** | 参数名称 | 参数说明 | 示例值 | |:---------|:---------|:-------| | `recurringPaymentStartDate` | 订阅开始时间 | "2025-06-01 00:00:00" | | `recurringPaymentIntervalUnit` | 扣费周期单位 | "month" | | `recurringPaymentIntervalCount` | 扣费周期数量 | "6" | | `recurringPaymentEndDate` | 订阅结束时间 | "2025-12-01 00:00:00" | **完整请求示例：** | paymentMethods | scenario | |:---------------|:---------| | ApplePay | subscription | **订阅支付特殊参数：** | 参数名称 | 参数值 | |:---------|:-------| | `bizType` | "CodeGrant" | | `createToken` | "Y" | | `merchantUserId` | "126048960513465" | **recurringInfo 参数示例：** ```json "recurringInfo": { "recurringPaymentStartDate": "2025-06-01 00:00:00", "recurringPaymentIntervalUnit": "month", "recurringPaymentIntervalCount": "6", "recurringPaymentEndDate": "2025-12-01 00:00:00" } ``` #### Step2 获取支付令牌 首笔支付成功后，系统会通过交易异步通知返回支付令牌（token）。 ::: warning 重要提醒 * 只有首次交易状态为 `SUCCESS` 时才能获取有效的支付令牌 * 请妥善保存令牌，用于后续自动扣费 * 令牌与 `merchantUserId` 绑定，请确保一致性 ::: #### Step3 后续自动扣费（Non-Hosted模式） 使用获取的令牌进行后续自动扣费，调用下单并支付接口。 **关键参数：** | 参数名称 | 参数说明 | 是否必填 | |:---------|:---------|:---------| | `bizType` | 业务类型，固定值"CodeGrant" | 必填 | | `merchantUserId` | 与首笔支付保持一致 | 必填 | | `token` | 从首笔支付异步通知中获取 | 必填 | **二次扣款请求示例：** | paymentMethods | scenario | |:---------------|:---------| | ApplePay | recurring | **二次扣款特殊参数：** | 参数名称 | 参数值 | |:---------|:-------| | `bizType` | "CodeGrant" | | `merchantUserId` | "126048960513465" | | `token` | "81cf697a30731d407b87b680e044a351" | ### 注意事项 1. **令牌管理**：支付令牌有效期为20年，请关注令牌状态并及时处理失效情况 2. **订阅周期**：合理设置订阅周期，避免过于频繁的扣费 3. **用户体验**：建议在订阅前明确告知用户扣费规则和取消方式 4. **异常处理**：做好扣费失败的处理逻辑，如重试机制、用户通知等 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Argencard/index.md description: >- Argencard是阿根廷的本土信用卡品牌,隶属于Prisma Medios de Pago公司。作为阿根廷最早的信用卡之一,它在本地市场拥有广泛认可度,支持实体店和在线支付,并提供分期付款、积分奖励等优惠。该卡在全国范围内被广泛接受,适用于零售商店、餐厅和在线商户。对于跨境电商,支持Argenca --- # Argencard Argencard是阿根廷的本土信用卡品牌,隶属于Prisma Medios de Pago公司。作为阿根廷最早的信用卡之一,Argencard在本地市场拥有悠久的历史和广泛的认可度。它提供多种类型的信用卡,适合不同消费需求的用户。Argencard支持实体店和在线支付,并提供分期付款、积分奖励等优惠。该卡在阿根廷全国范围内被广泛接受,包括零售商店、餐厅和在线商户。对于在阿根廷开展业务的商家,尤其是跨境电商,支持Argencard支付可以有效提升本地用户的支付体验和购买意愿。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Aupay/index.md description: >- AuPay是一种便捷的移动支付方式,适用于日本市场。用户可通过手机应用程序完成在线及实体店的支付,支持多种充值方式和优惠活动。主要特点包括快速支付、安全保障以及与各大商家合作提供的专属折扣。 --- # AuPay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Aupay/checkout/index.md description: 介绍如何通过集成收银台接受Au Pay支付，适用于日本市场。首先需请求收银台预下单以获取paymentUrl，随后渲染并跳转至收银台完成支付流程。 --- # Au Pay-收银台集成 通过集成收银台，接受Au Pay支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`paymentUrl` ### Step2 渲染收银台 接入文档:跳转收银台 ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Aupay/s2s/index.md description: >- Au Pay-API集成文档介绍了如何通过API实现下单并支付的功能。适用于需要在日本地区支持Au Pay支付方式的商家，提供服务器到服务器的支付请求与重定向完成支付流程。关键步骤包括调用下单并支付API以及根据返回的paymentRedirectUrl进行页面重定向以完成支付。 --- # Au Pay-API集成 ## 集成导航 ## step1 请求下单并支付 请求API:下单并支付 ## 重定向 下单并支付响应中获取参数`paymentRedirectUrl`。并重定向到该地址，根据页面提示完成支付。 详见Non-hosted 本地支付 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Aupay/sdk/index.md description: >- 介绍如何通过集成Au Pay-JSSDK在收银台接受Au Pay支付。适用于日本地区的在线商家，支持通过API预下单并渲染收银台以完成支付流程。关键步骤包括请求收银台预下单获取accessToken及使用内嵌JS-SDK渲染收银台。 --- # Au Pay-JSSDK集成 通过集成收银台，接受Au Pay支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken` ### Step2 渲染收银台 接入文档:内嵌JS-SDK ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Aura/index.md description: >- Aura是巴西的信用卡品牌,由Aura Financeira发行,提供多种类型的信用卡以满足不同消费者需求。其特点包括灵活的信用额度、分期付款选项和积分奖励计划,广泛接受于零售商店、超市及在线商城。Aura还通过移动应用方便用户管理账户和支付账单,并支持多种在线支付场景。适用于希望吸引更多本地消费者 --- # Aura Aura是巴西的信用卡品牌,由Aura Financeira发行。作为一家专注于消费金融的公司,Aura提供多种类型的信用卡,满足不同消费者的需求。Aura卡的特点包括灵活的信用额度、分期付款选项和积分奖励计划。它在巴西的零售商店、超市和在线商城中被广泛接受。Aura还提供移动应用,方便用户管理账户、查看交易和支付账单。近年来,Aura加强了在数字支付领域的布局,支持多种在线支付场景。对于在巴西市场运营的商家,特别是零售和电子商务领域,支持Aura支付可以吸引更多本地消费者,提高销售额。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BancoDoBrasil/index.md description: >- Banco do Brasil是一种支付方式,主要服务于巴西地区。支持通过银行转账、信用卡和借记卡等多种方式进行在线支付,为用户提供便捷安全的支付体验。适用于电子商务、公共服务缴费等场景,具有广泛的用户基础和较高的市场认可度。 --- # Banco do Brasil --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BancomatPay/index.md description: >- Bancomat Pay是一种电子支付方式,适用于意大利境内在线和实体店铺的支付。支持即时转账、移动支付等功能,用户可以通过银行账户直接进行支付,具有便捷安全的特点。 --- # Bancomat Pay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Bancontact/index.md description: >- Bancontact是一种在比利时广泛使用的在线支付方式,支持即时银行转账。适用于电子商务网站和移动应用,提供快速安全的支付体验。主要特点包括:实时交易确认、高安全性以及广泛的银行网络覆盖,几乎涵盖所有比利时的主要银行。 --- # Bancontact --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Banorte/index.md description: >- Banorte是一种墨西哥主要的在线支付方式,支持个人和企业通过银行转账或信用卡完成交易。覆盖整个墨西哥地区,提供安全便捷的支付体验,适用于电子商务、公共服务缴费等多种场景。 --- # Banorte --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BBVABancomer/index.md description: >- BBVA Bancomer是一种墨西哥主要的在线银行支付方式，允许用户通过其银行账户直接进行安全便捷的支付。适用于电子商务平台、公共服务缴费及各类在线交易场景。覆盖地区为墨西哥全境，支持实时支付确认和退款功能，确保交易过程中的资金安全与高效流转。 --- # BBVA Bancomer --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BCA/index.md description: >- BCA是印度尼西亚的一种银行转账支付方式，支持通过BCA银行账户进行在线支付。适用于印尼境内的电子商务平台和各类线上服务，提供即时转账确认功能，确保交易安全快速完成。 --- # BCA --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BDOOnlinePayment/index.md description: >- BDO(Banco de Oro)是菲律宾最大的银行之一,提供全面的在线银行支付服务。用户可通过BDO银行账户进行安全高效的网上支付、转账和金融交易。该支付方式具有强大的银行背景、高度安全性、广泛的ATM网络支持等优势,是菲律宾市场最受信赖的支付方式之一。 --- # BDO --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BLIK/index.md description: >- BLIK是一种基于移动银行的支付方式，主要用于波兰地区。用户通过手机银行应用生成一次性代码完成在线支付，无需提供银行卡信息，确保交易安全便捷。适用于电子商务、公共服务缴费等多种场景。 --- # BLIK --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BNI/index.md description: >- BNI是一种支付方式，适用于印度尼西亚地区的在线和线下交易。支持银行转账、信用卡及借记卡等多种支付手段，特点是操作简便、安全性高，并且在印尼拥有广泛的用户基础和接受度。 --- # BNI --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Boleto/index.md description: >- Boleto是一种巴西常用的支付方式，允许客户通过打印的票据在指定银行、ATM或网上银行完成支付。主要特点包括广泛覆盖巴西地区，支持多种支付渠道如实体店、线上平台等，并提供一定的支付期限。适用于希望为巴西用户提供本地化支付体验的商家。 --- # Boleto --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BoletoFlash/index.md description: >- Boleto Flash是一种现代化的巴西支付方式，通过二维码或支付链接提供即时处理和24/7全天候服务。适用于没有银行账户的消费者，支持在柜台、网上银行或移动设备上支付。与传统Boleto相比，Boleto Flash提供更快捷、更便捷的支付体验，但传统Boleto因其普及性和可靠性仍广泛使用。 --- # Boleto Flash 通过巴西任何支持网点的柜台或网上银行支付在线服务费用。 它在该国非常受欢迎，那里有相当多的消费者没有银行账户。 向消费者提供支付代码（或条形码），然后使用该代码以现金或通过家庭银行完成支付。 Boleto Flash是传统Boleto的现代化版本，提供更快速和便捷的支付体验，而传统Boleto则因其普及性和可靠性仍然广泛使用。选择哪种方式取决于用户的具体需求和偏好。 **差别：** 1. 处理速度： * Boleto Flash: 即时处理，支付确认通常在几分钟内完成。 * 传统Boleto: 处理时间较长，可能需要1-3个工作日。 2. 可用时间： * Boleto Flash: 24/7全天候可用。 * 传统Boleto: 通常受银行营业时间限制。 3. 支付方式： * Boleto Flash: 主要通过移动设备和在线方式支付。 * 传统Boleto: 可以在银行、ATM或网上银行支付。 4. 技术特性： * Boleto Flash: 使用二维码或支付链接。 * 传统Boleto: 使用条形码。 5. 市场普及度： * Boleto Flash: 正在快速增长，但相对较新。 * 传统Boleto: 在巴西已广泛使用多年。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Book/index.md description: >- Book是一种支付方式，允许用户通过银行转账完成在线购物。主要适用于欧洲地区，特别是德国、奥地利和荷兰。该支付方式具有高度安全性，支持实时交易确认，并提供多种语言界面以适应不同国家和地区的需求。 --- # Book --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Boost/index.md description: >- Boost是一种电子钱包支付方式，主要在马来西亚广泛使用。用户可以通过扫描二维码或输入手机号码完成支付，支持多种货币结算。Boost提供便捷的移动支付体验，适用于线上购物、餐饮服务及日常消费等多种场景。 --- # Boost --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BPI/index.md description: >- BPI是一种在菲律宾广泛使用的在线银行支付方式，支持用户通过其银行账户直接进行安全快捷的支付。主要特点包括实时交易确认、高安全性及便捷的操作流程，适用于电子商务网站和移动应用中需要快速结算的场景。 --- # BPI --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Bradesco/index.md description: >- Bradesco是一种巴西主要银行提供的支付方式,支持在线转账、信用卡和借记卡支付。适用于电子商务平台,覆盖整个巴西地区。其特点包括安全可靠、即时确认交易以及广泛接受度高,为商家提供便捷的收款解决方案。 --- # Bradesco --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BRI/index.md description: BRI是一种支持印度尼西亚地区的支付方式，通过银行转账完成交易。适用于电商平台、旅游服务等在线支付场景。主要特点包括操作便捷、安全性高以及支持多种货币结算。 --- # BRI --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/BSI/index.md description: >- BSI是一种电子支付方式，适用于欧洲地区。支持即时转账和直接扣款，提供安全高效的支付体验。主要特点包括快速结算、低手续费以及与多家银行系统兼容，特别适合在线商家和个人用户进行跨境交易时使用。 --- # BSI --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Cabal/index.md description: >- Cabal是阿根廷信用合作社联盟创立的支付卡品牌,在阿根廷、巴西、乌拉圭和巴拉圭等南美国家广泛使用。提供信用卡、借记卡和预付卡服务,支持实体店和在线支付。特点包括灵活的支付选项、优惠利率和广泛的商户网络。Cabal与国际支付网络合作,卡片可全球使用。面向南美市场的商家,特别是中小企业,接受Cabal --- # Cabal Cabal是阿根廷的支付卡品牌,由阿根廷信用合作社联盟(Federación Argentina de Cooperativas de Crédito)创立。作为一个合作社信用系统,Cabal在阿根廷、巴西、乌拉圭和巴拉圭等南美国家广泛使用。Cabal提供信用卡、借记卡和预付卡服务,支持实体店和在线支付。其特点包括灵活的支付选项、优惠的利率和广泛的商户网络。Cabal还与国际支付网络合作,使其卡片可在全球使用。对于面向南美市场的商家,特别是中小企业,接受Cabal支付可以扩大客户群,提高本地市场渗透率。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Caixa/index.md description: >- Caixa是一种主要在巴西使用的支付方式，支持借记卡、信用卡及预付卡等多种支付手段。其特点是安全便捷，广泛应用于线上购物、公共服务缴费等场景。商家接入Caixa后，能够覆盖更广泛的客户群体，提升交易成功率。 --- # Caixa --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/cardIntegrationWidthCheckout/index.md description: >- 国际卡集成-收银台模块介绍如何通过集成PingPong收银台接受信用卡和借记卡付款，支持VISA、MasterCard等主流卡种。覆盖全球，提供内嵌JS-SDK、跳转收银台及API三种集成方式，其中API集成需满足PCI DSS要求。该解决方案简化了支付流程并确保符合PCI合规标准，同时支持3D S --- # 国际卡集成-收银台 通过集成收银台，接受信用卡和借记卡付款。 ## PCI合规 ::: note 提示 根据您的集成情况，PingPongCheckout 可能要求您提交 PCI DSS 文档，然后才能在生产环境中接受信用卡支付。 ::: 接受信用卡和借记卡付款，需要符合PCI DSS的要求。详见PCI DSS 合规导航 PingPong 收银台 集成了大多数的支付方式。通过集成收银台，您可以轻松的接受信用卡和借记卡付款。并且PingPong收银台可以帮助您符合PCI合规的要求，降低加入成本。 | 集成方式 | PCI DSS | |:------|:--------| | 内嵌收银台 | 无需 | | 跳转收银台 | 无需 | | API | 需要 | ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken`或者`paymentUrl` | paymentMethods | |:------| | VISA | | MasterCard | | American Express | | Discover | | JCB | | CHINA UNION PAY | ### Step2 渲染收银台 跳转收银台/内嵌JS-SDK 接入文档: * 内嵌JS-SDK * 跳转收银台 ## 立即Capture和手动Capture 默认情况下，所有信用卡支付在授权后立即被捕获。或者，您可以设置使用手动捕获。 详见Capture ::: danger Alert 授权只在有限的时间(一般为7天)内有效。如果授权的支付没有被捕获或取消，一旦错过预定的截止日期，它将过期，并且将会自动`VOID`。 ::: ## 3D Secure 收银台已自动集成3D Secure。当用户使用3D Secure时，收银台会自动跳转到3D Secure页面。 1. 使用PingPongCheckout的风控系统自动决策：我们将通过风控体系自动决策。需要3D Secure时，自动决策为3D Secure，收银台会自动跳转到3D Secure页面。 2. 自定义决策：如果您有自己的风控体系和成熟的风控经验，需要手动控制3D Secure，可以使用`executeThreeD`参数。详见 Dynamic 3D Secure ::: danger Alert 在使用自定义决策功能情况下，如果您的收购处理实体和您的客户的发行者处理实体都在欧洲经济区(EEA)、摩纳哥，您的支付属于 PSD2 SCA 范围。为此，您可能需要大部分交易设置3DS验证，除了TRA豁免的情况。 ::: ## 记住卡号 如果您传送了参数`merchantUserId`，收银台可以记住卡号。当用户再次支付时，收银台会自动填充卡号。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/cardIntegrationWidthS2S/index.md description: >- 国际卡集成-S2S介绍如何通过收银台接受信用卡和借记卡付款，支持VISA、MasterCard等主流卡种。覆盖全球，需符合PCI DSS合规要求。提供内嵌或跳转收银台集成方式以降低商家PCI负担，API集成则需提交PCI DSS文档。支付流程包括风控及3DS验证步骤，支持立即或手动捕获资金。 --- # 国际卡集成-S2S 通过集成收银台，接受信用卡和借记卡付款。 ## PCI合规 ::: note 提示 根据您的集成情况，PingPongCheckout 可能要求您提交 PCI DSS 文档，然后才能在生产环境中接受信用卡支付。 ::: 接受信用卡和借记卡付款，需要符合PCI DSS的要求。详见PCI DSS 合规导航 | 集成方式 | PCI DSS | |:------|:--------| | 内嵌收银台 | 无需 | | 跳转收银台 | 无需 | | API | 需要 | ## 集成导航 ### Step1 风控组件和3DS组件集成 详见 Dynamic 3D Secure ### Step2 请求下单并支付 在API下单并支付的响应中： 1. status 为 `SUCCCESS` 时，订单已支付。 2. status 为 `PROCESSING` 时，订单已创建，但未支付。 1. `bizContent.threeDContinue` = `false` 无需3DS验证,您可以等待异步通知通知。 2. `bizContent.threeDContinue` = `true`,需要3DS验证，您需要跳转到3DS验证页面。 3. status 为 `FAILED` 时，订单创建失败。 详见 国际信用卡支付 | paymentMethod | |:------| | VISA | | MasterCard | | American Express | | Discover | | JCB | | UPIPay | ## 立即Capture和手动Capture 默认情况下，所有信用卡支付在授权后立即被捕获。或者，您可以设置使用手动捕获。 详见Capture ::: danger Alert 授权只在有限的时间(一般为7天)内有效。如果授权的支付没有被捕获或取消，一旦错过预定的截止日期，它将过期，并且将会自动`VOID`。 ::: ## 3D Secure * S2S集成需要您嵌入风控JS和3DS组件。 * 无法嵌入JS组件，请向商务或者风控申请API接入3DS方式。 1. 使用PingPongCheckout的风控系统自动决策：我们将通过风控体系自动决策。需要3D Secure时，自动决策为3D Secure，收银台会自动跳转到3D Secure页面。 2. 自定义决策：如果您有自己的风控体系和成熟的风控经验，需要手动控制3D Secure，可以使用`executeThreeD`参数。详见 Dynamic 3D Secure ::: danger Alert 在使用自定义决策功能情况下，如果您的收购处理实体和您的客户的发行者处理实体都在欧洲经济区(EEA)、摩纳哥，您的支付属于 PSD2 SCA 范围。为此，您可能需要大部分交易设置3DS验证，除了TRA豁免的情况。 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/CartaoMercadoLivre/index.md description: >- Cartao MercadoLivre是MercadoLibre推出的支付卡,面向其用户,提供信用卡和预付卡服务。持卡人可在平台上享受现金返还、免息分期等优惠,并支持实体店支付和ATM取现。作为MercadoPago生态系统的一部分,该卡在巴西及其他南美国家广受欢迎,有助于提高商家销售额和客户忠诚度 --- # Cartao MercadoLivre Cartao MercadoLivre是由南美最大的电子商务平台MercadoLibre推出的支付卡。这张卡主要面向MercadoLibre的用户,提供信用卡和预付卡服务。持卡人可在MercadoLibre平台上享受特别优惠,如现金返还、免息分期和额外积分。除了在线购物,Cartao MercadoLivre还支持实体店支付和ATM取现。作为MercadoPago支付生态系统的一部分,这张卡在巴西和其他南美国家广受欢迎。对于在MercadoLibre平台上经营的商家,支持Cartao MercadoLivre支付可以提高销售额和客户忠诚度。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/CashApp/index.md description: >- Cash App是一种移动支付方式，允许用户通过智能手机发送、接收和存储资金。主要在美国地区使用，支持即时转账、直接存款以及购买比特币等功能。商家和个人均可利用其便捷性进行交易，无需传统银行账户即可完成大部分金融操作。 --- # Cash App --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Cencosud/index.md description: >- Cencosud信用卡是由南美零售巨头Cencosud集团发行的支付卡，主要在智利、阿根廷、巴西、秘鲁和哥伦比亚等国家使用。持卡人可在Cencosud旗下的超市、百货商店和购物中心（如Jumbo、Easy和Paris）享受积分奖励、专属折扣和分期付款等优惠。该卡还支持在线支付，方便用户在集团的电商平 --- # Cencosud Cencosud信用卡是由南美零售巨头Cencosud集团发行的支付卡。Cencosud在智利、阿根廷、巴西、秘鲁和哥伦比亚等国家拥有广泛的业务网络。这张卡主要用于Cencosud旗下的超市、百货商店和购物中心,如Jumbo、Easy和Paris等。持卡人可享受积分奖励、专属折扣和分期付款等优惠。Cencosud卡还支持在线支付,方便用户在集团的电商平台上购物。对于在南美市场经营的商家,尤其是零售业,接受Cencosud卡支付可以吸引大量忠实客户。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/CIMB/index.md description: >- CIMB是一种支付方式，主要服务于东南亚地区，包括马来西亚、印度尼西亚、泰国等。支持网上银行转账和信用卡支付等多种交易手段，具有高度的安全性和便捷性，适用于电子商务和个人间转账。 --- # CIMB --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/CMRFalabella/index.md description: >- CMR Falabella是智利Falabella集团的信用卡品牌,广泛用于Falabella旗下商店及其他商户。提供积分奖励、分期付款和特别折扣等优惠,并与多家银行合作推出联名卡,扩大使用范围。近年来,CMR Falabella推出移动应用,方便客户管理账户和支付。支持CMR Falabella支 --- # CMR Falabella CMR Falabella是智利零售巨头Falabella集团旗下的信用卡品牌,成立于1980年。作为智利流行的支付方式,它主要用于Falabella旗下商店,也被其他商户广泛接受。CMR Falabella提供积分奖励、分期付款和特别折扣等优惠。该卡与多家银行合作推出联名卡,扩大了使用范围。近年来,CMR Falabella推出移动应用,方便客户管理账户和支付。对在智利开展电子商务的商家而言,支持CMR Falabella支付可显著提升本地客户的购物体验。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/CoBadgedCards/index.md description: >- Cartes Bancaires是一种主要在法国及其海外领土使用的支付方式，支持借记卡和信用卡交易。该支付方式覆盖了广泛的商业领域，从零售到在线服务，具有高安全性与便捷性特点。适用于希望进入法国市场的商家。 --- # Cartes Bancaires --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/commonIntegration/index.md description: >- 介绍支付方式接入流程，包括收银台和S2S两种模式。收银台模式通过预下单获取accessToken或paymentUrl后，可选择内嵌JS-SDK或跳转收银台完成支付；S2S模式则直接请求下单并支付，获取paymentUrl跳转至钱包支付页面。适用于需要灵活集成支付功能的场景，覆盖地区广泛，支持多种支 --- ::: note 提示 参数中的 device 设备信息，accessModel取值，需要根据具体场景填写对应的编号，不同的编号会展示不同支付形态，具体可以参考下单接口 ::: # 集成导航 ## 收银台 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken`或者`paymentUrl` ### Step2 渲染收银台 跳转收银台/内嵌JS-SDK 接入文档: * 内嵌JS-SDK * 跳转收银台 ## S2S ### Step1 请求S2S下单并支付 在APIS2S下单并支付的响应中，您可以获取`paymentUrl` 并跳转到对应的钱包支付页面 ## 请求参数 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Cordial/index.md description: >- Cordial是阿根廷的信用卡品牌,由Cordial Compañía Financiera S.A.发行,提供多种类型的信用卡以满足不同客户需求。Cordial卡具有灵活的分期付款选项、积分奖励计划和专属优惠,在阿根廷的零售商店、超市和在线商城中广泛接受。Cordial还提供移动应用,方便用户管理 --- # Cordial Cordial是阿根廷的信用卡品牌,由Cordial Compañía Financiera S.A.发行。作为一家专注于消费金融的公司,Cordial提供多种类型的信用卡,满足不同客户群的需求。Cordial卡的特点包括灵活的分期付款选项、积分奖励计划和专属优惠。它在阿根廷的零售商店、超市和在线商城中被广泛接受。Cordial还提供移动应用,方便用户管理账户、查看交易和支付账单。对于在阿根廷市场运营的商家,特别是零售和电子商务领域,支持Cordial支付可以吸引更多本地消费者,提高销售转化率。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Cordobesa/index.md description: >- Cordobesa是阿根廷科尔多瓦省的本地信用卡品牌,由Banco de Córdoba发行。该卡在省内广泛使用,提供信用卡和借记卡服务,支持实体店支付、在线购物和ATM取现。Cordobesa卡具有优惠利率、灵活分期付款选项及本地商户专属优惠。适用于科尔多瓦省内的中小企业和电商平台,有助于吸引当地 --- # Cordobesa Cordobesa是阿根廷科尔多瓦省的本地信用卡品牌,由Banco de Córdoba发行。作为一种区域性支付卡,Cordobesa在科尔多瓦省内拥有广泛的使用范围和高度的认可度。它提供信用卡和借记卡服务,支持实体店支付、在线购物和ATM取现。Cordobesa卡的特点包括优惠的利率、灵活的分期付款选项和本地商户的专属优惠。对于在科尔多瓦省经营的商家,特别是中小企业和本地电商平台,支持Cordobesa支付可以有效吸引当地消费者,提高客户忠诚度和销售额。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Cultureland/index.md description: >- Cultureland是一种预付卡支付方式，主要应用于韩国市场。用户可通过购买Cultureland预付卡为在线游戏、音乐、电影等数字内容充值。该支付方式支持多种面额，便于不同消费层次的用户使用。 --- # Cultureland --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/DANA/index.md description: >- DANA是一种在印度尼西亚广泛使用的电子钱包支付方式,支持在线购物、账单支付及个人间转账。用户可通过银行账户或合作网点充值,享受便捷安全的移动支付体验。主要特点包括快速交易确认、高安全性以及与多家本地服务提供商集成。 --- # DANA --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/DANA/danaIntegration/index.md description: >- DANA是一种适用于印度尼西亚的电子钱包支付方式，支持收银台和S2S两种集成模式。在收银台模式下，通过预下单获取accessToken或paymentUrl后渲染收银台；S2S模式则直接请求下单并支付，获取paymentUrl跳转至钱包支付页面。设备信息和接入模式需根据具体场景填写对应编号。 --- ::: note 提示 参数中的 device 设备信息，accessModel取值，需要根据具体场景填写对应的编号，不同的编号会展示不同支付形态，具体可以参考下单接口 ::: # 集成导航 ## 收银台 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken`或者`paymentUrl` ### Step2 渲染收银台 跳转收银台/内嵌JS-SDK 接入文档: * 内嵌JS-SDK * 跳转收银台 ## S2S ### Step1 请求S2S下单并支付 在APIS2S下单并支付的响应中，您可以获取`paymentUrl` 并跳转到对应的钱包支付页面 ## 请求参数 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/docomo/index.md description: >- docomo是一种在日本广泛使用的移动支付方式，支持通过手机进行便捷的线下和线上支付。主要特点包括快速、安全以及与多种商家和服务的良好兼容性，适用于日常购物、餐饮及公共服务缴费等多种场景。 --- # docomo --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/DOKUVA/index.md description: >- DOKU VA是一种虚拟账户支付方式，允许用户通过银行转账完成支付。适用于印尼市场，支持主要本地银行。特点是即时到账确认和便捷的支付体验，特别适合电商平台和需要快速结算的企业使用。 --- # DOKU VA --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/DOKUWallet/index.md description: >- DOKU Wallet 是一种电子钱包支付方式，适用于印尼地区的在线交易。支持多种充值途径如银行转账、便利店充值等，为用户提供便捷安全的支付体验。主要特点包括即时到账、易于使用及广泛的应用场景，适合电商、游戏内购等多种支付需求。 --- # DOKU Wallet --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/dragonpay/index.md description: >- Dragonpay是一种电子支付方式，主要服务于菲律宾地区的用户。支持多种支付渠道，包括银行转账、在线银行支付及线下支付点付款等，为用户提供便捷安全的支付体验。适用于电子商务网站、旅游服务预订以及各类线上交易场景。 --- # Dragonpay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/DuitNow/index.md description: >- DuitNow是一种即时支付方式,主要用于马来西亚的个人和企业间转账。支持通过手机号码、身份证号或银行账号进行快速安全的资金转移,覆盖马来西亚主要银行及金融机构。特点是操作简便、到账迅速,适用于日常消费、账单支付等场景。 --- # DuitNow --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Efecty/index.md description: >- Efecty是一种在哥伦比亚广泛使用的现金支付方式,允许用户通过遍布全国的网点进行付款。主要特点包括即时交易确认、无需银行账户即可使用以及支持多种支付场景,如账单支付、电子商务等。 --- # Efecty --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/EggMoney/index.md description: 'Egg Money是一种电子钱包支付方式,适用于亚洲多个国家和地区,支持快速转账、在线购物和账单支付。用户可以轻松绑定银行卡,享受便捷安全的支付体验。' --- # Egg Money --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Elo/index.md description: >- Elo是巴西本土支付卡品牌,提供信用卡、借记卡和预付卡服务,在巴西广泛使用。该支付方式专为本地市场设计,符合巴西消费习惯,并通过国际合作实现全球使用。近年来,Elo积极拓展移动支付和非接触支付,支持多种数字钱包。面向巴西市场的电商和跨境商户集成Elo支付可提升用户体验,扩大市场份额。 --- # Elo Elo是巴西本土支付卡品牌,2011年由三大银行联合创立。提供信用卡、借记卡和预付卡服务,在巴西广泛使用。Elo卡专为本地市场设计,提供符合巴西消费习惯的功能和优惠。通过国际合作,Elo卡也可在全球使用。近年来,Elo积极拓展移动支付和非接触支付,支持多种数字钱包。对面向巴西市场的电商和跨境商户而言,集成Elo支付可提升本地用户体验,扩大市场份额。Elo持续创新,巩固其在巴西支付领域的地位。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/EPS/index.md description: >- EPS是一种奥地利的在线银行转账支付方式，允许用户通过其网上银行账户安全地完成支付。主要特点包括即时确认交易、高安全性以及广泛覆盖奥地利的主要银行。适用于需要快速且安全支付选项的电子商务场景。 --- # EPS --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/FPX/index.md description: >- FPX是一种马来西亚的在线银行转账支付方式,允许用户通过本地银行账户直接进行安全快捷的支付。适用于电子商务网站、政府服务及各类在线交易场景。主要特点包括实时交易确认、支持多家主流银行以及无需额外注册即可使用。 --- # FPX --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GameCulture/index.md description: >- Game Culture是一种专为游戏内购设计的支付方式，支持全球多个国家和地区。该支付方式允许玩家通过多种渠道购买虚拟商品和服务，包括但不限于信用卡、第三方支付平台等。其主要特点包括快速结算、高度安全性和用户友好的界面设计。 --- # Game Culture --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GCash/index.md description: >- GCash是一种菲律宾流行的电子钱包支付方式，允许用户通过移动应用进行快速安全的在线交易。主要特点包括即时转账、账单支付、手机充值及购物付款等。广泛应用于日常消费场景，如超市购物、餐饮服务以及线上平台支付。 --- # GCash --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GooglePay/index.md description: >- Google Pay 是一种数字钱包技术，允许用户在实体店、App 和网上使用存储在 Google 账户中的信用卡或借记卡进行支付。支持面部识别和指纹识别验证交易，适用于大多数发行银行和国家。使用条件包括兼容设备、支持的浏览器、HTTPS 服务及有效 SSL 证书。Android 设备需运行 And --- # GooglePay Google Pay 是一种数字钱包技术，使购物者能够在实体店、App 内或网上使用兼容设备上存储在 Google 账户中的任何信用卡或借记卡进行无缝支付。 购物者可以使用面部识别或指纹识别通过结账过程来验证交易. Google Pay 还使购物者能够检索存储在其关联账户中的卡片，包括来自 Google Play、Chrome 或 Android 设备的卡片。对于这些交易，根据卡片类型，购物者可能需要进行验证。 谷歌支付适用于大多数发行银行和国家，使其成为增长最快的支付方式之一。 **付款人只有在满足以下条件时才能使用 Google Pay 作为支付方式选项：** * 使用兼容 Google Pay 的设备。 * 如果在网页上支付，则使用支持 Google Pay 的浏览器（如 Chrome、Safari、Firefox 等）。 * 位于 Google Pay 可用的国家或地区 * 所有集成 Google Pay 的页面都必须通过 HTTPS 服务。您的域名必须具有有效的 SSL 证书。 要使用 Google Pay，用户的设备必须满足以下要求： * Android 设备需运行 Android 4.4 (KitKat) 或更高版本 * 设备必须安装 Google Play 服务 16.0.0 或更高版本 * 用户需要在 Google 账户中添加支付方式 对于开发人员集成 Google Pay API，还需满足以下要求： * 开发环境需要 Android Studio 3.0 或更高版本 * 应用的目标 API 级别建议为 26 或更高 * 需要使用最新版本的 Google Play 服务库 了解更多关于兼容性要求的信息，请参考： * [Google Pay 支持的设备](https://developers.google.com/pay/issuers/overview/supported-devices#compatibility_requirements) * [Google Pay API Android 设置前提条件](https://developers.google.com/pay/api/android/guides/setup#app%20prerequisites) * [Google Wallet 支持的设备和功能](https://support.google.com/wallet/answer/14187106?sjid=1565778547611136477-NC\&visit_id=638912664571713484-955916255\&rd=1) 接受Google Pay付款，有一些合规需求。 | 集成方式 | PCI DSS | 风控JS | 3DS接入处理 | |:----------------------------|:--------|:-----|:-----------------------| | 内嵌收银台 | 无需 | 无需 | 无需-自动集成 | | 跳转收银台 | 无需 | 无需 | 无需-自动集成 | | Server To Server（传输加密Token） | 无需 | 需要 | 需要-手动集成 | | Server To Server（传输解密Token） | 需要 | 需要 | 需要-手动集成 | | 行业 | billing Address | shipping Address | goods | tradeCountry | |:-------|:----------------|:-----------------|:------|:---------------------| | 实物电商行业 | 必填 | 必填 | 必填 | 可选 | | 虚拟行业 | 可选 | 可选 | 必填 | 必填，收银台自动传送/S2S需要手动传入 | --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GooglePay/hosted/index.md description: >- Google Pay 跳转收银台集成支持订阅支付模式，允许商户为用户设置定期自动扣费服务。覆盖地区广泛，主要特点包括通过跳转收银台完成首笔支付并获取支付令牌，后续使用该令牌进行自动扣费。关键参数如`merchantUserId`、`createToken`和`bizType`需在请求中指定。 --- # Google Pay 跳转收银台集成 ## GooglePay-跳转收银台交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Merchant as 🏪 商户后端 participant Frontend as 💻 商户前端 participant PP as 🔄 PingPong服务端 participant Hosted as 🌐 跳转收银台 participant Google as 🌐 Google Pay Note over Merchant, Google: 🚀 GooglePay跳转收银台集成流程 Note over Merchant, Frontend: 📋 准备阶段:• 获取访问凭证• 准备跳转链接 Merchant->>+PP: 1️⃣ 获取accessToken/paymentUrl Note right of PP: 调用收银台预下单接口
生成访问凭证或支付链接 PP-->>-Merchant: 返回accessToken或paymentUrl Merchant->>Frontend: 2️⃣ 传递跳转参数到前端 Frontend->>Frontend: 3️⃣ 构建跳转链接 Note right of Frontend: 使用paymentUrl
或accessToken构建完整链接 Frontend->>+Hosted: 4️⃣ 跳转到PingPong收银台 Note right of Hosted: 在新窗口或当前页面
打开收银台页面 Hosted->>Hosted: 5️⃣ 初始化收银台界面 Note right of Hosted: • 显示支付方式列表• 加载Google Pay组件 Hosted-->>-Frontend: 收银台加载完成 Note over Hosted, Google: 💳 Google Pay支付流程 User->>Hosted: 6️⃣ 用户选择Google Pay支付 Hosted->>+Google: 7️⃣ 调用Google Pay API Note right of Google: • 显示Google Pay界面• 用户验证身份• 获取支付令牌 Google-->>-Hosted: 返回加密支付令牌 Hosted->>+PP: 8️⃣ 发送支付请求(含加密令牌) PP->>PP: 9️⃣ 处理支付 Note right of PP: • 解密Google Pay令牌• 风控检查• 支付路由处理 alt ✅ [支付成功] PP-->>Hosted: 🎉 支付成功 Hosted->>Hosted: 显示成功页面 Hosted-->>Frontend: 可选的页面回调 Note over Frontend: 支付成功处理
和页面跳转 else ❌ [支付失败] PP-->>Hosted: ❌ 支付失败 Hosted->>Hosted: 显示错误页面 Hosted-->>Frontend: 可选的错误回调 Note right of Frontend: 错误处理
和用户提示 end Note over Merchant, PP: 🎯 Google Pay跳转收银台流程完成 ``` ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken`或者`paymentUrl` ### Step2 渲染收银台 接入文档:跳转收银台 ## Google Pay 订阅支付集成 Google Pay 支持订阅支付模式，允许商户为用户设置定期自动扣费服务。 ### 集成流程 #### Step1 首笔支付（跳转收银台模式） 首次订阅支付需要通过跳转收银台模式完成，用于建立订阅关系并获取支付令牌。使用收银台预下单接口。 **关键参数说明：** | 参数名称 | 参数说明 | 是否必填 | |:---------|:---------|:---------| | `merchantUserId` | 商户用户唯一标识 | 必填 | | `createToken` | 是否创建支付令牌，固定值"Y" | 必填 | | `bizType` | 业务类型，固定值"CodeGrant" | 必填 | **完整请求示例：** | paymentMethods | scenario | |:---------------|:---------| | GooglePay | subscription | **订阅支付特殊参数：** | 参数名称 | 参数值 | |:---------|:-------| | `bizType` | "CodeGrant" | | `createToken` | "Y" | | `merchantUserId` | "126048960513465" | #### Step2 获取支付令牌 首笔支付成功后，系统会通过交易异步通知返回支付令牌（token）。 ::: warning 重要提醒 * 只有首次交易状态为 `SUCCESS` 时才能获取有效的支付令牌 * 请妥善保存令牌，用于后续自动扣费 * 令牌与 `merchantUserId` 绑定，请确保一致性 ::: #### Step3 后续自动扣费（Non-Hosted模式） 使用获取的令牌进行后续自动扣费，调用下单并支付接口。 **关键参数：** | 参数名称 | 参数说明 | 是否必填 | |:---------|:---------|:---------| | `bizType` | 业务类型，固定值"CodeGrant" | 必填 | | `merchantUserId` | 与首笔支付保持一致 | 必填 | | `token` | 从首笔支付异步通知中获取 | 必填 | **二次扣款请求示例：** | paymentMethods | scenario | |:---------------|:---------| | GooglePay | recurring | **二次扣款特殊参数：** | 参数名称 | 参数值 | |:---------|:-------| | `bizType` | "CodeGrant" | | `merchantUserId` | "126048960513465" | | `token` | "81cf697a30731d407b87b680e044a351" | ### 注意事项 1. **令牌管理**：支付令牌有效期为20年，请关注令牌状态并及时处理失效情况 2. **订阅周期**：合理设置订阅周期，避免过于频繁的扣费 3. **用户体验**：建议在订阅前明确告知用户扣费规则和取消方式 4. **异常处理**：做好扣费失败的处理逻辑，如重试机制、用户通知等 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GooglePay/s2s_decryptionMode/index.md description: >- 介绍了解密Token模式下Google Pay API的集成方法，适用于需要符合PCI合规且接入风控及3DS组件的商户。此模式通过商户证书解密支付Token，并将解密信息传递给PingPongCheckout以完成支付过程。主要覆盖地区为全球，关键特性包括支持动态3DS验证和异步通知机制。 --- # Google Pay API集成-解密Token模式 使用商户的证书，对支付Token进行解密，传送解密信息给PingPongCheckout，获取支付结果。 ## 1.解密Token模式交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Merchant as 🏪 商户后端 participant Frontend as 💻 商户前端 participant PP as 🔄 PingPong服务端 participant Risk as 🛡️ 风控组件 participant Google as 🌐 Google Pay Note over Merchant, Google: 🚀 GooglePay解密Token集成流程 Note over Merchant, Frontend: 📋 前置准备:
• PCI合规环境
• 集成Google Pay API
• 集成风控和3DS组件 Frontend->>+Google: 1️⃣ 初始化Google Pay API Note right of Google: • 加载Google Pay组件
• 配置支付环境(商户证书)
• 验证商户配置 Google-->>-Frontend: Google Pay组件就绪 Note over Frontend, Google: 💳 获取支付令牌 Frontend->>+Google: 2️⃣ 用户发起支付
包含: 金额、货币、商户信息 Note right of Google: • 显示Google Pay界面
• 用户选择支付方式
• 生物识别验证 Google-->>-Frontend: 3️⃣ 返回加密支付令牌
🔐 包含加密的卡片信息 Note right of Frontend: 获得加密的Google Pay支付令牌
准备发送到后端处理 Frontend->>+Merchant: 4️⃣ 提交加密令牌到后端
📦 包含: Token + 订单信息 Note right of Merchant: 接收加密的Google Pay令牌
开始后端处理流程 Merchant->>Merchant: 5️⃣ 解密支付令牌
🔓 获取真实卡片信息 Note right of Merchant: 使用商户证书解密Google Pay令牌
提取: 卡号、有效期、CVV等
验证令牌完整性 Merchant->>+Risk: 6️⃣ 风控检查和3DS验证
🛡️ 安全评估 Note right of Risk: • 风险评估分析
• 3D Secure验证
• 反欺诈检测
• 合规性检查 Risk-->>-Merchant: 风控验证结果
✅ 通过/❌ 拒绝/🔄 需要3DS Merchant->>+PP: 7️⃣ 发起支付请求
📋 完整支付信息 Note right of PP: 请求包含:
• 解密后的支付信息
• 风控验证结果
• 交易详细信息
• 商户配置参数 PP->>PP: 8️⃣ 处理支付
⚙️ 核心支付逻辑 Note right of PP: • 验证支付信息完整性
• 二次风控验证
• 支付路由选择
• 与银行通信处理 alt 🎉 支付成功 PP-->>Merchant: ✅ 支付成功响应
包含: 交易ID + 状态 Merchant->>Merchant: 📝 记录成功日志
更新订单状态 Note over Frontend: • 显示成功页面
• 更新订单状态
• 发送确认邮件
• 库存扣减处理 else ❌ 支付失败 PP-->>Merchant: ⚠️ 支付失败响应
包含: 错误码 + 失败原因 Merchant->>Merchant: 📋 记录失败日志
分析失败原因 Note over Frontend: • 显示错误信息
• 提供重试选项
• 记录失败原因
• 用户友好提示 else 🔄 需要3DS验证 PP-->>Merchant: 🔐 需要3DS验证
返回验证URL Note over Frontend: • 跳转到3DS页面
• 用户完成身份验证
• 返回验证结果
• 继续支付流程 Merchant->>PP: 🔄 重新提交支付
附带3DS验证结果 PP-->>Merchant: ✅ 最终支付结果
处理完成 end PP-->>-PP: 处理完成 Merchant-->>-Frontend: 🎊 通知最终结果
包含完整状态信息 Note over Merchant, PP: 🎯 GooglePay解密Token流程完成
✨ 安全、高效、用户友好 rect rgb(240, 248, 255) Note over Merchant, Google: 💡 关键要点:
• 商户需要PCI合规环境进行Token解密
• 风控和3DS验证是必要的安全措施
• 支持多种支付结果的处理流程
• 确保用户数据安全和隐私保护 end ``` ## 2. 集成导航 ::: danger 提示 1. 根据您的集成情况，通过API（解密Token模式）接入Google Pay，您需要符合PCI合规并且接入风控组件和3DS组件。 2. 您需要提前完成对Google Pay API 页面部分交互集成。 ::: ### 2.1 Step0 前置条件 集成Google Pay Web支付组件，详见Google Pay文档 ### 2.2 Step1 前端组件集成 详见 Dynamic 3D Secure ### 2.3 Step2 请求下单并支付 在API下单并支付的响应中： 1. status 为 `SUCCCESS` 时，订单已支付。 2. status 为 `PROCESSING` 时，订单已创建，但未支付。 1. `bizContent.threeDContinue` = `false` 无需3DS验证,您可以等待异步通知通知。 2. `bizContent.threeDContinue` = `true`,需要3DS验证，您需要跳转到3DS验证页面。 3. status 为 `FAILED` 时，订单创建失败。 ## 3. 关键参数 ## 4. 参数示例 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GooglePay/s2s_encryptionMode/index.md description: >- 介绍如何通过PingPongCheckout组件集成Google Pay API，采用加密Token模式实现安全支付。适用于需要接入风控和3DS验证的商户。支持地区广泛，主要特点包括服务器端解密Token以完成交易，确保数据传输的安全性。 --- # Google Pay API集成-加密Token模式 ## GooglePay-加密Token交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Merchant as 🏪 商户后端 participant Frontend as 💻 商户前端 participant PP as 🔄 PingPong服务端 participant Risk as 🛡️ 风控组件 participant Google as 🟦 Google Pay Note over Frontend, Google: 🔒 GooglePay加密Token流程 Frontend->>Google: 1️⃣ 初始化Google Pay API Note right of Google: 加载组件, 配置环境 Google->>Frontend: Google Pay组件就绪 Frontend->>Google: 2️⃣ 用户发起支付 Google->>Frontend: 3️⃣ 返回加密支付令牌 Frontend->>Risk: 4️⃣ 风控检查和3DS验证 Risk->>Frontend: 风控验证结果 Frontend->>Merchant: 5️⃣ 提交加密令牌和风控结果 Merchant->>PP: 6️⃣ 发起支付请求 PP->>PP: 7️⃣ 处理支付 alt ✅ [支付成功] PP->>Merchant: 🎉 支付成功 Merchant->>Frontend: 通知支付结果 else ❌ [支付失败] PP->>Merchant: ❌ 支付失败 Merchant->>Frontend: 通知失败结果 end ``` ## 集成导航 ::: note 提示 1. 根据您的集成情况，通过API（加密Token模式）接入Google Pay，您需要接入风控组件和3DS组件。 2. 您需要提前完成对Google Pay API 页面部分交互集成。 ::: ### Step0 前置条件 集成Google Pay Web支付组件，详见Google Pay文档 ### Step1 风控组件和3DS组件集成 详见 Dynamic 3D Secure ### Step2 请求下单并支付 在API下单并支付的响应中： 1. status 为 `SUCCCESS` 时，订单已支付。 2. status 为 `PROCESSING` 时，订单已创建，但未支付。 1. `bizContent.threeDContinue` = `false` 无需3DS验证,您可以等待异步通知通知。 2. `bizContent.threeDContinue` = `true`,需要3DS验证，您需要跳转到3DS验证页面。 3. status 为 `FAILED` 时，订单创建失败。 ### 关键参数 ### 参数示例 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GooglePay/sdk/index.md description: >- Google Pay 内嵌收银台集成文档介绍了如何在网站中集成Google Pay支付方式，覆盖全球多个地区。集成流程包括提交申请、请求收银台预下单和渲染内嵌收银台。支持订阅支付模式，允许商户为用户设置定期自动扣费服务。关键参数包括merchantUserId、createToken和bizType --- # Google Pay 内嵌收银台集成 ## GooglePay-内嵌收银台交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant Merchant as 🏪 商户后端 participant Frontend as 💻 商户前端 participant SDK as 📦 内嵌收银台 participant PP as 🔄 PingPong服务端 participant Google as 🌐 Google Pay Note over Merchant, Google: 🚀 GooglePay内嵌收银台集成流程 Note over Merchant, Frontend: 📋 准备阶段:• 获取访问凭证• 引入收银台组件 Merchant->>+PP: 1️⃣ 获取accessToken Note right of PP: 调用收银台预下单接口
生成访问凭证 PP-->>-Merchant: 返回accessToken Merchant->>Frontend: 2️⃣ 传递accessToken到前端 Frontend->>+SDK: 3️⃣ 渲染内嵌收银台 Note right of SDK: 使用accessToken初始化
Google Pay支付组件 SDK->>SDK: 4️⃣ 初始化Google Pay组件 SDK-->>Frontend: 收银台准备就绪 Note over Frontend, Google: 💳 Google Pay支付流程 Frontend->>SDK: 5️⃣ 用户选择Google Pay支付 SDK->>+Google: 6️⃣ 调用Google Pay API Note right of Google: • 显示Google Pay界面• 用户验证身份• 获取支付令牌 Google-->>-SDK: 返回加密支付令牌 SDK-->>Frontend: 令牌获取成功 Frontend->>SDK: 7️⃣ 确认支付 SDK->>+PP: 8️⃣ 发送支付请求(含加密令牌) PP->>PP: 9️⃣ 处理支付 Note right of PP: • 解密Google Pay令牌• 风控检查• 支付路由处理 alt ✅ [支付成功] PP-->>SDK: 🎉 支付成功 SDK-->>Frontend: 支付完成回调 Note over Frontend: 页面跳转
或显示成功信息 else ❌ [支付失败] PP-->>SDK: ❌ 支付失败 SDK-->>Frontend: 显示错误信息 Note right of Frontend: 错误处理
和用户提示 end PP-->>-SDK: 支付流程结束 SDK-->>-Frontend: 收银台流程结束 Note over Merchant, PP: 🎯 Google Pay内嵌收银台流程完成 ``` ## 集成导航 ::: danger 提示 使用SDK集成需要将您的网站域名提交PingPongCheckout的域名白名单中。 ::: ### step0 提交申请 请将申请材料发送给邮箱`acq-pmteam@pingpong.com`，并抄送到`acq-ts@pingpongx.com` **申请材料如下：** 1. 商户名称 2. 商户 AccId 3. 商户 ClientId 4. 网站域名 5. 商户网站页面截图（从选择商品，到下单展示Google Pay），文字需要转成英文版，规范：1. 文字改为 “Google Pay” 2. Google Pay Logo 需要改为正式的，参考 https://developers.google.com/pay/api/web/guides/brand-guidelines#mark（需科学上网） ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken`用于内嵌收银台渲染 ### Step2 渲染收银台 使用Step1获取的`accessToken`渲染内嵌收银台，接入文档:内嵌收银台 ## Google Pay 订阅支付集成 Google Pay 支持订阅支付模式，允许商户为用户设置定期自动扣费服务。 ### 集成流程 #### Step1 首笔支付（内嵌收银台模式） 首次订阅支付需要通过内嵌收银台模式完成，用于建立订阅关系并获取支付令牌。使用收银台预下单接口。 **关键参数说明：** | 参数名称 | 参数说明 | 是否必填 | |:---------|:---------|:---------| | `merchantUserId` | 商户用户唯一标识 | 必填 | | `createToken` | 是否创建支付令牌，固定值"Y" | 必填 | | `bizType` | 业务类型，固定值"CodeGrant" | 必填 | **完整请求示例：** | paymentMethods | scenario | |:---------------|:---------| | GooglePay | subscription | **订阅支付特殊参数：** | 参数名称 | 参数值 | |:---------|:-------| | `bizType` | "CodeGrant" | | `createToken` | "Y" | | `merchantUserId` | "126048960513465" | #### Step2 获取支付令牌 首笔支付成功后，系统会通过交易异步通知返回支付令牌（token）。 ::: warning 重要提醒 * 只有首次交易状态为 `SUCCESS` 时才能获取有效的支付令牌 * 请妥善保存令牌，用于后续自动扣费 * 令牌与 `merchantUserId` 绑定，请确保一致性 ::: #### Step3 后续自动扣费（Non-Hosted模式） 使用获取的令牌进行后续自动扣费，调用下单并支付接口。 **关键参数：** | 参数名称 | 参数说明 | 是否必填 | |:---------|:---------|:---------| | `bizType` | 业务类型，固定值"CodeGrant" | 必填 | | `merchantUserId` | 与首笔支付保持一致 | 必填 | | `token` | 从首笔支付异步通知中获取 | 必填 | **二次扣款请求示例：** | paymentMethods | scenario | |:---------------|:---------| | GooglePay | recurring | **二次扣款特殊参数：** | 参数名称 | 参数值 | |:---------|:-------| | `bizType` | "CodeGrant" | | `merchantUserId` | "126048960513465" | | `token` | "81cf697a30731d407b87b680e044a351" | ### 注意事项 1. **令牌管理**：支付令牌有效期为20年，请关注令牌状态并及时处理失效情况 2. **订阅周期**：合理设置订阅周期，避免过于频繁的扣费 3. **用户体验**：建议在订阅前明确告知用户扣费规则和取消方式 4. **异常处理**：做好扣费失败的处理逻辑，如重试机制、用户通知等 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GoPay/index.md description: >- GoPay是一种便捷的在线支付方式，适用于亚洲多个地区，特别是东南亚。支持多种货币结算，提供即时转账、账单支付及移动充值等功能。商家和个人用户均可通过API轻松集成，享受低费率和高安全性的支付体验。 --- # GoPay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/GrabPay/index.md description: >- GrabPay是一种电子钱包支付方式,主要在东南亚地区使用,支持新加坡、马来西亚、菲律宾等国家。用户可通过绑定银行卡或充值的方式进行支付,适用于线上购物、打车服务及日常消费等多种场景。其特点是操作简便、安全性高,并且能够提供多种优惠活动吸引消费者。 --- # GrabPay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Hipercard/index.md description: >- Hipercard是巴西知名的信用卡品牌,由Itaú Unibanco集团运营,在全国尤其是东北地区广泛使用。支持实体店和在线支付,提供灵活的支付选项、积分奖励计划和专属商户优惠。适用于零售和电商企业,接受Hipercard支付可有效吸引本地消费者,提高销售转化率。 --- # Hipercard Hipercard是巴西知名的信用卡品牌,最初由Bompreço超市连锁创立,现归Itaú Unibanco集团所有。作为巴西本土支付解决方案,Hipercard在全国范围内广泛使用,特别是在东北地区。它提供信用卡服务,支持实体店和在线支付。Hipercard的特点包括灵活的支付选项、积分奖励计划和专属商户优惠。近年来,Hipercard加强了在电子商务领域的应用,支持多种在线支付场景。对于在巴西市场运营的商家,尤其是零售和电商企业,接受Hipercard支付可以有效吸引本地消费者,提高销售转化率。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/iDEAL/index.md description: >- iDeal是一种荷兰在线银行转账支付方式,适用于荷兰消费者通过网银直接向商家付款。覆盖荷兰主要银行,提供安全、即时的支付确认,无需信用卡,适合各种在线购物场景。 --- # iDeal --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Indomaret/index.md description: >- Indomaret是一种便捷的现金支付方式,主要在印度尼西亚使用。顾客可以在全国范围内的Indomaret便利店通过出示支付码完成线上订单的现金支付,适用于没有银行账户或信用卡的人群。此支付方式简单快捷,支持即时确认收款。 --- # Indomaret --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/InternationalCards/index.md description: >- VISA是一种国际信用卡支付方式,广泛应用于全球范围内的线上及线下交易。支持多种货币结算,具有快速便捷、安全可靠的特点,适用于跨境电子商务、旅游消费等多种场景。 --- # VISA --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Itau/index.md description: >- Itau是一种主要在巴西使用的在线银行支付方式，支持用户通过其Itau银行账户安全快捷地完成支付。适用于电子商务、公共服务缴费等多种场景，具有实时到账、高安全性及便捷性等特点。 --- # Itau --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Kakaopay/index.md description: >- Kakaopay是一种流行的韩国移动支付方式，支持通过手机应用进行在线和离线支付。主要特点包括快速转账、便捷的二维码支付以及与Kakao生态系统内的多种服务无缝集成。适用于需要覆盖韩国市场的电子商务平台和个人用户。 --- # Kakaopay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Klarna/index.md description: >- Klarna是一种流行的“先买后付”支付方式，覆盖超过20个国家。支持四种主要支付选项：立即支付、延期支付、分期付款和融资。使用Klarna前会进行风险检查以确保交易安全。 --- # Klarna Klarna是一种流行的“先买后付”支付方式，适用于超过20个国家。使用Klarna，付款人可以选择以下付款方式： 1. Pay now：通过银行卡、直接借记或其他资金来源立即支付全部金额。 2. Pay later：在商品送达后再付款，例如在30天内付款。 3. Pay in parts(分期付款)：分几次（例如3次或4次）逐步支付总金额。 4. Financing：由Klarna提供的定期贷款。 在批准付款之前，Klarna会对付款人进行风险检查。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Klarna/integrationWithCheckout/index.md description: >- 介绍如何通过集成Klarna收银台接受支付，适用于实物电商和虚拟行业。支持内嵌JS-SDK和跳转收银台两种方式，无需PCI DSS合规。关键参数包括账单地址、配送地址、商品信息等，并需确保商品总价与支付金额一致。支持多种语言显示，但需匹配交易国家和币种。Klarna自带钱包功能，支持中断后继续支付。 --- # Klarna-收银台 通过集成收银台，接受Klarna支付。 ## PCI合规 | 集成方式 | PCI DSS | |:------|:--------| | 内嵌收银台 | 无需 | | 跳转收银台 | 无需 | | API | 无需 | ## 集成导航 跳转收银台/内嵌JS-SDK 接入文档: * 内嵌JS-SDK * 跳转收银台 ## klarna必要参数 | 行业 | billing Address | shipping Address |goods | tradeCountry | |:-------|:----------------|:-----------------|:-----------------|:---------------------| | 实物电商行业 | 必填 | 必填 | 必填 | 可选 | | 虚拟行业 | 可选 | 可选 | 必填 | 必填，收银台自动传送/S2S需要手动传入 | ::: note 特殊参数规则 1. goods参数的单价乘以数量求和后的结果应大于等于支付金额 （sum(goods\[0-N].unitPrice \* goods\[0-N].number) => amount） 2. 运费及额外费用设置 goods 里面新增一个对象 name和description 设置为shipping-fee unitPrice=运费 3. 为了提高转换率，我们建议您收集付款人姓名和账单地址，如果您暂时没有收集表单可以打开收银台可以打开账单地址收集选项。 4. klarna交易币种和交易国家必须对应，列表详见 klarna支付详情页 5. 只有当指定的区域设置与请求中使用的国家和货币匹配时，才能以另一种语言呈现 Klarna 收银台页面。默认情况下，结帐页面呈现为英文(en-US)。 ::: ## 再支付 Klarna有自己的钱包,在pingpong支付跳转钱包支付时放弃支付,用户可在钱包继续完成支付订单.pingpong会根据订单完成结果查询获得交易结果 ## 3D Secure Klarna 无需集成3D Secure ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Klarna/integrationWithS2S/index.md description: >- Klarna-S2S是一种通过API接受Klarna付款的方式，允许商户自定义结账页面。适用于实物电商和虚拟行业，无需PCI DSS合规。主要特点包括：覆盖欧洲、北美等地，支持多种支付方式如分期付款；关键参数有billingAddress、shippingAddress及goods等，且需确保商品总 --- # Klarna-S2S 使用我们的API接受Klarna付款，并构建自己的付款表单，以完全控制结账页面的外观和体验。 ## PCI合规 | 集成方式 | PCI DSS | |:------|:--------| | 内嵌收银台 | 无需 | | 跳转收银台 | 无需 | | API | 无需 | ## 集成导航 在API下单并支付的响应中获取参数`paymentRedirectUrl`, 重定向到该地址完成支付 详见Non-hosted 本地支付 ## klarna必要参数 | 行业 | billing Address | shipping Address |goods |tradeCountry | |:-------|:----------------|:-----------------|:-----------------|:---------------------| | 实物电商行业 | M | M | M |可选 | | 虚拟行业 | O | O | M |必填，收银台自动传送/S2S需要手动传入 | ::: note 特殊参数规则 1. goods参数的单价乘以数量求和后的结果应大于等于支付金额 （sum(goods\[0-N].averageUnitPrice \* goods\[0-N].number) => amount） 2. 运费及额外费用设置 goods 里面新增一个对象 name和description 设置为shipping-fee averageUnitPrice=运费 3. 为了提高转换率，我们强烈建议您收集付款人姓名和账单地址。 4. klarna交易币种和交易国家必须对应，列表详见 klarna支付详情页 5. 只有当指定的区域设置与请求中使用的国家和货币匹配时，才能以另一种语言呈现 Klarna 收银台页面。默认情况下，结帐页面呈现为英文(en-US)。 ::: ## 再支付 Klarna有自己的钱包,在PingPongCheckout跳转钱包支付时放弃支付,用户可在钱包继续完成支付订单.PingPongCheckout会根据订单完成结果查询获得交易结果 ## 3D Secure Klarna 无需集成3D Secure --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Konbini/index.md description: >- Konbini是一种在日本广泛使用的便利店支付方式。顾客在网上下单后，会收到一个带有条形码的账单，可于指定时间内在任意一家合作便利店完成付款。主要特点包括无需银行账户、操作简便以及广泛的便利店网络覆盖。 --- # Konbini --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Konbini/checkout/index.md description: >- Konbini-收银台集成文档介绍了如何通过集成收银台接受Konbini支付。适用于日本市场的线上支付场景，提供便捷的预下单和渲染收银台步骤。关键特性包括生成`paymentUrl`以及最佳实践指南。 --- # Konbini-收银台集成 通过集成收银台，接受Konbini支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`paymentUrl` ### Step2 渲染收银台 接入文档:跳转收银台 ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Konbini/s2s/index.md description: >- Konbini-API集成文档介绍了如何通过API实现日本便利店支付方式的集成。适用于需要支持日本本地支付场景的应用。主要步骤包括调用下单并支付API，获取重定向URL，并引导用户至指定页面完成支付。 --- # Konbini-API集成 ## 集成导航 ## step1 请求下单并支付 请求API:下单并支付 ## 重定向 下单并支付响应中获取参数`paymentRedirectUrl`。并重定向到该地址，根据页面提示完成支付。 详见Non-hosted 本地支付 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Konbini/sdk/index.md description: >- Konbini-JSSDK集成介绍如何通过API请求和JS-SDK渲染收银台，以接受日本地区的便利店支付。主要步骤包括请求预下单获取accessToken以及根据接入文档内嵌JS-SDK渲染收银台。适用于希望为用户提供线下支付选项的在线商家。 --- # Konbini-JSSDK集成 通过集成收银台，接受Konbini支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken` ### Step2 渲染收银台 接入文档:内嵌JS-SDK ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/KoreanBanks/index.md description: >- Korea Banks 介绍韩国各大银行的在线支付方式。适用于电子商务平台和各类线上服务，支持即时转账和信用卡支付等功能。覆盖整个韩国地区，以其便捷性和安全性受到广泛欢迎。 --- # Korea Banks --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/KoreanCards/index.md description: >- 韩国卡支付方式支持使用韩国本地发行的信用卡和借记卡进行在线支付。适用于与韩国商家交易或在韩国境内消费，具有便捷、安全的特点。主要覆盖地区为韩国，支持多种主流银行发行的卡片。 --- # Korea Cards --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/KoreanCards/localCardKoreaintegration/index.md description: >- Local Cards Korea 支持韩国本地银行卡支付，适用于需要接入韩国本地银行支付的场景。集成方式包括收银台和S2S模式。收银台模式下通过预下单获取accessToken或paymentUrl后渲染页面；S2S模式则直接请求下单并支付获取paymentUrl。注意，S2S模式需指定具体的本地 --- ::: note 提示 参数中的 device 设备信息，accessModel取值，需要根据具体场景填写对应的编号，不同的编号会展示不同支付形态，具体可以参考下单接口 ::: # 集成导航 ## 收银台 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken`或者`paymentUrl` ### Step2 渲染收银台 跳转收银台/内嵌JS-SDK 接入文档: * 内嵌JS-SDK * 跳转收银台 ## S2S ### Step1 请求S2S下单并支付 在APIS2S下单并支付的响应中，您可以获取`paymentUrl` 并跳转到对应的钱包支付页面 ## 请求参数 ::: note 提示 S2S 模式下需要上传 paymentMethod.type 选择具体的本地银行进行支付；收银台模式下会根据配置展示所有的本地银行卡，无法指定展示某个具体的本地银行卡支付 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/LinkAja/index.md description: >- LinkAja是一种由中国移动推出的支付方式,适用于中国移动用户在中国大陆进行线上及线下支付。其主要特点包括便捷的手机号绑定、快速支付流程以及广泛覆盖的商家支持。 --- # LinkAja --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Magna/index.md description: >- Magna是智利Cencosud集团发行的支付卡品牌,主要用于集团旗下零售商店如Paris百货、Jumbo超市等。持卡人可享受专属折扣、积分奖励及灵活分期付款选项,并支持在线支付。近年来,Magna扩大了接受范围,与更多第三方商户合作,增加了卡片使用灵活性,适用于希望吸引智利本地消费者的零售商和电商 --- # Magna Magna是智利的支付卡品牌,由Cencosud集团发行。作为Cencosud旗下的私有标签信用卡,Magna主要用于集团旗下的零售商店,如Paris百货、Jumbo超市和Easy家居用品店。持卡人可享受专属折扣、积分奖励和灵活的分期付款选项。Magna卡还支持在线支付,方便用户在Cencosud的电商平台上购物。近年来,Magna扩大了其接受范围,与更多第三方商户合作,增加了卡片的使用灵活性。对于在智利市场运营的零售商和电商平台,支持Magna支付可以吸引大量本地消费者,提高销售转化率和客户忠诚度。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Mandiri/index.md description: >- Mandiri是一种在印度尼西亚广泛使用的支付方式，支持银行转账和电子钱包。适用于在线购物、账单支付及各类电子商务交易。主要特点包括实时到账、安全可靠以及用户界面友好。 --- # Mandiri --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/MBway/index.md description: >- MBway是一种即时支付方式，主要服务于法国地区的银行客户。用户通过手机应用或网上银行快速完成转账和支付，支持多种场景如在线购物、账单支付等。其特点是操作简便、安全性高且处理速度快。 --- # MBway --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/MCash/index.md description: >- MCash是一种便捷的移动支付方式，主要服务于东南亚地区。用户可通过手机应用完成快速安全的转账、充值和缴费等操作。支持多种货币结算，并提供实时交易通知与24/7客户服务。 --- # MCash --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/merPay/index.md description: >- merPay是一种电子支付方式,适用于日本市场,支持线上购物、账单支付及个人转账等功能。用户可通过手机应用轻松完成支付,具有操作简便、安全性高等特点,并提供多种优惠活动以吸引消费者使用。 --- # merPay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/MobilePayments/index.md description: >- 移动支付是韩国广泛使用的支付方式,支持通过智能手机应用程序完成交易。适用于线上购物、线下零售及服务支付场景。主要特点包括便捷性、安全性以及与银行账户或信用卡的无缝连接。覆盖韩国全国,支持多种主流移动支付应用如KakaoPay和Naver Pay。 --- # Mobile Payments Korea --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/MobilePop/index.md description: >- Mobile Pop是一种移动支付方式，适用于在线购物和即时转账。主要特点包括快速便捷的支付体验、支持多种加密货币以及广泛覆盖亚洲地区。用户通过扫描二维码或输入支付码即可完成交易，无需携带实体钱包。 --- # Mobile Pop --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Multibanco/index.md description: >- Multibanco是一种在葡萄牙广泛使用的支付方式，支持通过ATM、网上银行或移动应用进行支付。用户可以使用Multibanco生成的参考代码，在指定时间内完成支付。这种支付方法适用于电子商务交易，尤其受到没有信用卡用户的欢迎。 --- # Multibanco --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Mybank/index.md description: >- Mybank是一种基于支付宝平台的支付方式，适用于中国地区。主要特点包括支持大额交易、快速到账以及与阿里巴巴生态系统的无缝集成。商家可以通过Mybank为消费者提供灵活多样的支付选项，增强用户体验。 --- # Mybank --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Nativa/index.md description: >- Nativa是阿根廷国家银行发行的本土支付卡品牌,提供信用卡和借记卡服务,广泛应用于日常消费、网上购物及ATM取现。该卡在阿根廷全国范围内被高度信任并广泛接受,以其优惠利率和灵活支付选项著称。对于阿根廷境内的商户尤其是电子商务平台而言,支持Nativa支付有助于吸引更多本地消费者,提升销售转化率。 --- # Nativa Nativa是阿根廷的本土支付卡品牌,由Banco de la Nación Argentina(阿根廷国家银行)发行。作为国有银行的产品,Nativa卡在阿根廷拥有广泛的使用范围和高度的信任度。它提供信用卡和借记卡服务,适用于日常消费、网上购物和ATM取现。Nativa卡的特点包括全国范围内的广泛接受度、优惠的利率和灵活的支付选项。对于在阿根廷经营的商户,特别是电子商务平台,支持Nativa支付可以吸引大量本地客户,提高销售转化率。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Naverpay/index.md description: >- Naverpay是一种韩国主流的在线支付方式，支持用户通过Naver账户进行安全便捷的支付。适用于电子商务网站和移动应用，提供快速结账体验。主要特点包括支持多种支付手段如信用卡、银行转账等，并且覆盖全韩国地区。 --- # Naverpay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Naverpay/naverpayIntegration/index.md description: >- Naverpay是一种支付方式，适用于韩国市场。支持收银台和S2S两种集成模式。在收银台模式下，通过预下单获取accessToken或paymentUrl后渲染收银台；S2S模式则直接请求下单并支付，获取paymentUrl跳转至钱包支付页面。设备信息和访问模型需根据具体场景填写。 --- ::: note 提示 参数中的 device 设备信息，accessModel取值，需要根据具体场景填写对应的编号，不同的编号会展示不同支付形态，具体可以参考下单接口 ::: # 集成导航 ## 收银台 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken`或者`paymentUrl` ### Step2 渲染收银台 跳转收银台/内嵌JS-SDK 接入文档: * 内嵌JS-SDK * 跳转收银台 ## S2S ### Step1 请求S2S下单并支付 在APIS2S下单并支付的响应中，您可以获取`paymentUrl` 并跳转到对应的钱包支付页面 ## 请求参数 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Octopus/index.md description: >- 八达通是一种非接触式智能卡支付方式，广泛应用于香港地区的公共交通、零售商店及公共服务。支持快速小额支付，无需签名，方便快捷。用户可在通过多种渠道进行充值，并享受部分商家的优惠折扣。 --- # 八达通 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/overview/index.md description: >- 支付方式介绍文档提供了多种支付手段的概览，包括信用卡、借记卡、电子钱包及银行转账等。每种支付方式均详细介绍其适用地区、交易流程、费用结构及安全特性。此文档适用于希望了解并集成不同支付解决方案至其服务中的商家和技术人员。 --- # Payment Methods PingPongCheckout 支持全球多种支付方式，包括信用卡、借记卡、电子钱包及银行转账等。使用下方筛选器按国家/地区或币种过滤，查看支持的支付方式详情。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/OVO/index.md description: >- OVO是一种在印尼广泛使用的电子钱包,适用于线上购物、账单支付及线下交易等多种场景。用户通过绑定银行账户或直接充值来使用该服务,支持二维码支付和转账功能,为个人和商家提供便捷安全的支付解决方案。 --- # OVO --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/OXXO/index.md description: >- OXXO是一种在墨西哥广泛使用的现金支付方式。消费者可以在任何OXXO便利店通过提供生成的条形码或参考号完成付款。此支付方式适用于没有银行账户或信用卡的用户，具有高普及率和便利性。 --- # OXXO --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/P24/index.md description: >- P24是一种主要在波兰使用的在线银行转账支付方式，允许用户通过其银行账户直接进行安全快速的支付。适用于希望为波兰客户提供本地化支付体验的电商和在线服务提供商。支持的主要银行包括PKO Bank Polski, mBank等。 --- # P24 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PagBank/index.md description: >- PagBank是一种巴西流行的数字银行支付方式，支持用户通过其账户进行在线支付。主要特点包括快速转账、账单支付及手机充值等服务。适用于电商平台、应用程序内购买等多种场景，为用户提供便捷安全的支付体验。 --- # PagBank --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PagoEfectivo/index.md description: >- Pago Efectivo是一种主要在秘鲁使用的现金支付方式，允许消费者通过指定的实体点如银行、药店或便利店完成在线购物的付款。该支付方法特别适用于没有银行账户或信用卡的用户，提供了一种便捷且安全的交易手段。 --- # Pago Efectivo --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Paidy/index.md description: >- Paidy是一种日本的信用支付方式，允许消费者在线购物时先购买后付款。适用于希望提高转化率并扩大客户基础的电子商务平台。无需信用卡，用户仅需提供电话号码和邮箱即可完成注册。主要特点包括快速结账流程、无额外费用以及广泛的商户接受度。 --- # Paidy --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/papara/index.md description: >- Papara是一种电子钱包支付方式,主要服务于土耳其市场。支持即时转账、账单支付及在线购物等多种支付场景。用户可通过手机应用轻松管理账户,享受便捷安全的支付体验。 --- # papara --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Pay-easy/index.md description: >- Pay-easy是一种便捷的在线支付方式，适用于日本地区的银行转账。用户可以通过此服务轻松完成账单支付、学费缴纳等日常金融交易。其主要特点包括操作简便、支持多种银行以及实时到账，为用户提供安全可靠的支付体验。 --- # Pay-easy --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Pay-easy/checkout/index.md description: >- 介绍如何通过集成收银台接受Pay-easy支付，适用于希望在日本市场提供便捷在线支付选项的商家。文档详细说明了从请求预下单到渲染收银台的具体步骤，并提供了最佳实践指南以确保顺利接入。 --- # Pay-easy 收银台集成 通过集成收银台，接受PayPay支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`paymentUrl` ### Step2 渲染收银台 接入文档:跳转收银台 ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Pay-easy/s2s/index.md description: >- Pay-easy API集成文档提供了在日本地区使用Pay-easy进行支付的API集成指南。通过调用下单并支付API，商户可以获取支付重定向链接paymentRedirectUrl，并引导用户至该链接完成支付过程。适用于需要支持银行转账支付方式的在线商家。 --- # Pay-easy API集成 ## 集成导航 ## step1 请求下单并支付 请求API:下单并支付 ## 重定向 下单并支付响应中获取参数`paymentRedirectUrl`。并重定向到该地址，根据页面提示完成支付。 详见Non-hosted 本地支付 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Pay-easy/sdk/index.md description: >- 介绍如何通过集成Pay-easy JSSDK在网站上接受PayPay支付。适用于希望在日本市场提供便捷支付选项的商家。文档详细说明了从请求收银台预下单到渲染收银台的具体步骤，包括获取accessToken及使用内嵌JS-SDK的最佳实践指南。 --- # Pay-easy JSSDK集成 通过集成收银台，接受PayPay支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken` ### Step2 渲染收银台 接入文档:内嵌JS-SDK ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayByBank/index.md description: >- Pay By Bank是一种直接银行转账支付方式，允许用户通过其银行账户安全快捷地完成在线支付。主要适用于欧洲地区，支持即时支付确认和高安全性标准。无需额外注册或存储敏感信息，适合各类电子商务平台及服务提供商使用。 --- # Pay By Bank --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayByBank/checkout/index.md description: >- 介绍如何通过集成收银台接受Pay By Bank支付方式。适用于希望在欧洲地区提供银行直接支付选项的商家，支持多种货币和语言。首先需请求收银台预下单以获取paymentUrl，随后根据接入文档指引渲染并跳转至收银台页面完成交易流程。 --- # Pay By Bank-收银台集成 通过集成收银台，接受 Pay By Bank 支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`paymentUrl` ### Step2 渲染收银台 接入文档:跳转收银台 ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayByBank/s2s/index.md description: >- Pay By Bank-API集成支持通过银行直接支付。适用于需要提供便捷、安全支付选项的在线商家。主要特点包括覆盖欧洲多个国家，通过API下单并支付，获取paymentRedirectUrl后重定向完成支付流程。 --- # Pay By Bank-API集成 ## 集成导航 ### step1 请求下单并支付 请求API:下单并支付 ### 重定向 下单并支付响应中获取参数`paymentRedirectUrl`。并重定向到该地址，根据页面提示完成支付。 详见Non-hosted 本地支付 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayByBank/sdk/index.md description: >- 介绍如何通过集成JSSDK接受Pay By Bank支付。适用于需要在网站或应用中直接嵌入银行支付选项的商家。主要步骤包括请求收银台预下单以获取accessToken，以及使用内嵌JS-SDK渲染收银台界面。此支付方式覆盖英国等地区，提供安全便捷的资金转移服务。 --- # Pay By Bank-JSSDK集成 通过集成收银台，接受 Pay By Bank 支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken` ### Step2 渲染收银台 接入文档:内嵌JS-SDK ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayCash/index.md description: >- PayCash是一种快速便捷的在线支付方式，适用于需要即时交易确认和个人间转账的场景。支持全球超过100个国家和地区使用，主要特点包括零手续费、实时到账以及高度安全性。 --- # PayCash --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PAYCO/index.md description: >- PAYCO是一种在韩国广泛使用的移动支付方式，支持线上购物、账单支付及个人转账等功能。用户可以通过手机应用程序轻松完成支付操作，具有便捷性和安全性高的特点。商家集成PAYCO后，能够为消费者提供多样化的支付选择，提升用户体验。 --- # PAYCO --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Payconiq/index.md description: >- Payconiq是一种便捷的移动支付方式,主要在比利时和卢森堡使用。用户可以通过手机应用程序快速安全地进行在线或面对面交易。其特点包括即时转账、账单支付及支持多种货币。适用于个人间转账、购物付款等多种场景,提供高效且安全的支付体验。 --- # Payconiq --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Paymaya/index.md description: >- Paymaya是菲律宾领先的数字金融服务平台,提供电子钱包和在线支付解决方案。用户可以通过Paymaya进行快速便捷的线上线下支付、转账、账单缴费等服务。该平台支持多种充值方式,具有高安全性和广泛的商户接受度,是菲律宾市场重要的移动支付工具。 --- # Paymaya --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Paynow/index.md description: >- Paynow是一种便捷的在线支付方式，适用于新加坡地区。支持个人与企业通过银行账户或参与银行的应用程序即时转账收款。其特点包括快速交易确认、高度安全性和用户友好界面。 --- # Paynow --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayPal/index.md description: >- PayPal 是一种全球广泛使用的在线支付方式，支持个人和商家进行快速、安全的交易。适用于电子商务网站、移动应用以及跨境支付等多种场景。主要特点包括用户账户体系完善、支持多种货币转换、提供买家卖家保护机制等。覆盖地区几乎遍布全球，尤其在北美和欧洲市场普及率极高。 --- # PayPal --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayPay/index.md description: >- PayPay是一种便捷的移动支付方式，主要在日本广泛使用。用户可以通过扫描二维码完成支付，支持线上及线下多种消费场景。该支付方式具有操作简单、交易速度快的特点，并且与多家银行和金融机构合作，确保了资金的安全性和服务的稳定性。 --- # PayPay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayPay/checkout/index.md description: >- 介绍如何通过集成收银台接受PayPay支付，适用于日本市场。主要步骤包括请求收银台预下单以获取paymentUrl，以及渲染收银台完成支付流程。遵循最佳实践确保顺利接入。 --- # PayPay-收银台集成 通过集成收银台，接受PayPay支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`paymentUrl` ### Step2 渲染收银台 接入文档:跳转收银台 ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayPay/s2s/index.md description: >- PayPay-API集成文档介绍了如何通过API实现下单并支付功能。适用于希望在日本市场提供便捷移动支付选项的商家，支持从请求下单到用户完成支付的全流程。关键步骤包括调用下单并支付API及处理重定向以完成支付。 --- # PayPay-API集成 ## 集成导航 ## step1 请求下单并支付 请求API:下单并支付 ## 重定向 下单并支付响应中获取参数`paymentRedirectUrl`。并重定向到该地址，根据页面提示完成支付。 详见Non-hosted 本地支付 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayPay/sdk/index.md description: >- 介绍如何通过集成PayPay-JSSDK在日本地区接受PayPay支付。首先需要请求收银台预下单以获取accessToken，然后根据接入文档渲染内嵌JS-SDK的收银台界面。遵循最佳实践指南可以确保顺利完成集成。 --- # PayPay-JSSDK集成 通过集成收银台，接受PayPay支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken` ### Step2 渲染收银台 接入文档:内嵌JS-SDK ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Paypo/index.md description: >- Paypo是波兰领先的先买后付(BNPL)支付解决方案,为消费者提供灵活的分期付款选择。支持30天免息延期付款,以及4-9期的分期付款服务。通过简化的在线支付流程,Paypo为波兰电子商务提供了便捷、安全的支付体验,帮助商家提升转化率并增强客户购物体验。交易金额范围为10 PLN至8,000 PLN。 --- # Paypo --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Paysafecard/index.md description: >- Paysafecard是一种预付费在线支付方式，允许用户通过购买实体或电子卡进行安全的在线支付。适用于不愿意或无法使用银行账户或信用卡的消费者。主要在欧洲、北美及部分亚洲地区广泛使用，支持多种面额，提供匿名且方便快捷的支付体验。 --- # Paysafecard --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Paysera/index.md description: >- Paysera是一种电子钱包支付方式，广泛应用于欧洲地区。用户可以方便地进行在线购物、转账和收款。支持多种货币，并提供安全便捷的支付体验。主要特点包括快速交易确认、低手续费以及易于集成的API接口。 --- # Paysera --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Payso/index.md description: >- Payso是一种香港地区流行的移动支付解决方案,支持用户通过智能手机进行便捷的线上线下支付。主要特点包括快速支付、安全加密、多场景适用等功能。广泛应用于零售、餐饮、交通及在线电商等领域,为用户提供高效的数字支付体验。 --- # Payso --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PayWithIyzico/index.md description: >- 介绍iyzico支付方式，一种广泛应用于土耳其及周边地区的在线支付解决方案。支持多种支付手段如信用卡、借记卡和分期付款等，具有高安全性与便捷性，适用于电子商务网站集成，帮助企业快速接入多样化的支付选项以提升用户体验。 --- # Pay with iyzico --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Permata/index.md description: >- Permata是一种支持印尼地区的在线银行转账支付方式。适用于希望通过银行账户直接进行安全、快速支付的用户。主要特点包括实时交易确认、支持多种货币以及提供详细的交易记录，确保每一笔交易的安全性和透明度。 --- # Permata --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PicPay/index.md description: >- PicPay是一种流行的巴西移动支付方式,支持个人和企业用户通过手机应用进行快速、安全的资金转账。该支付方式允许用户绑定银行卡或信用卡,并通过二维码扫描完成付款。PicPay还提供账单支付、手机充值等服务,覆盖全巴西地区,是线上购物及日常消费的理想选择。 --- # PicPay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PIX/index.md description: >- PIX是一种即时支付方式，主要在巴西使用。通过生成二维码或密钥实现个人、企业间的快速转账与支付。支持全天候操作，且交易成本低廉。适用于线上购物、账单支付等多种场景。 --- # PIX --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Presto/index.md description: >- Presto是哥伦比亚的私有标签信用卡,由Grupo Éxito零售集团推出,主要用于旗下超市、百货商店及其他零售网点。持卡人可享受专属折扣、积分奖励和灵活分期付款,并支持在线支付。近年来,Presto扩展了使用范围,与更多商户合作,增加了卡片实用性。适用于哥伦比亚市场的零售商和电商平台,以吸引本地 --- # Presto Presto是哥伦比亚的支付卡品牌,由Grupo Éxito零售集团推出。作为一种私有标签信用卡,Presto主要用于Éxito集团旗下的超市、百货商店和其他零售outlets。持卡人可享受专属折扣、积分奖励和灵活的分期付款选项。Presto卡还支持在线支付,方便用户在Éxito的电商平台上购物。近年来,Presto扩展了其使用范围,与其他商户合作,增加了卡片的实用性。对于在哥伦比亚市场运营的零售商和电商平台,支持Presto支付可以吸引大量本地消费者,提高客户忠诚度。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PromptPay/index.md description: >- PromptPay是泰国的一种在线银行支付方式，由泰国银行开发和监管。商家通过展示二维码供顾客使用参与银行的应用程序扫描或上传二维码截图完成支付。PromptPay支持手机号码、国民身份证号码、企业注册号码及数字钱包号码作为用户识别方式，实现跨行转账。该支付方式简化了支付流程，提高了支付效率，并确保 --- # PromptPay PromptPay是泰国的一种在线银行支付方式，由泰国银行（Bank of Thailand，BoT）开发和监管。使用PromptPay时，商家会向顾客展示一个二维码，顾客可以使用参与银行的任何一款应用程序进行支付。顾客可以通过扫描二维码或上传二维码截图来完成支付。 为了实现银行间资金转账，PromptPay系统通过以下几种方式来识别用户： * 手机号码 * 国民身份证号码 * 企业注册号码 * 数字钱包号码 这些信息作为代理标识，使得用户可以方便快捷地进行跨行转账。PromptPay的设计旨在简化支付流程，提高支付效率，同时确保交易的安全性。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/PSE/index.md description: >- PSE是一种针对哥伦比亚市场的在线支付方式，允许用户通过其银行账户直接进行支付。主要特点包括支持多家当地银行、实时交易确认以及高安全性。适用于电子商务平台和希望为哥伦比亚用户提供便捷支付选项的商家。 --- # PSE --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/QRIS/index.md description: >- Qris是一种基于二维码的支付方式，主要应用于印度尼西亚市场。支持多种电子钱包和银行应用，用户通过扫描商家提供的二维码完成支付。其特点包括便捷快速、广泛兼容以及增强的安全性措施。 --- # Qris --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/RabbitLINEPay/index.md description: >- RabbitLINEPay是一种结合了Rabbit Card和LINE Pay的支付方式，主要在日本和泰国使用。它支持线上购物、线下支付以及转账等功能，用户可以通过扫描二维码或条形码完成支付。此外，还提供了积分奖励机制，鼓励用户频繁使用。 --- # RabbitLINEPay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/RapiPago/index.md description: >- Rapi Pago是一种阿根廷的在线支付方式，允许用户通过银行账户或预付卡进行快速安全的支付。适用于电商平台、公共服务缴费等场景。主要特点包括即时交易确认和广泛的银行网络支持。 --- # Rapi Pago --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/RCBCOnlinePayment/index.md description: >- RCBC(Rizal Commercial Banking Corporation)是菲律宾主要银行之一提供的在线银行支付方式。用户可以通过RCBC银行账户进行安全便捷的在线支付和转账服务。该支付方式具有高安全性、即时到账、操作简便等特点,广泛应用于电子商务、账单缴费等场景。 --- # RCBC --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Rpay/index.md description: >- Rakuten Pay 是乐天集团推出的电子支付方式，适用于日本市场。支持线上购物、实体店铺支付及移动支付等多种场景。用户通过智能手机应用即可完成支付，享受便捷安全的支付体验。 --- # Rakuten Pay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/RuPay/index.md description: >- RuPay是印度本土支付卡网络,提供信用卡、借记卡和预付卡服务,广泛应用于实体店支付、在线购物和ATM取现。其特点包括低手续费、广泛的商户网络和针对印度市场的特色服务,支持非接触支付和移动支付,并与多个数字钱包集成。对于面向印度市场的商家,特别是电子商务平台,支持RuPay支付有助于吸引本地客户,扩 --- # RuPay RuPay是印度本土的支付卡网络,由印度国家支付公司(NPCI)开发和运营。作为印度政府推动金融普惠的重要工具,RuPay提供信用卡、借记卡和预付卡服务。RuPay卡在印度广泛使用,支持实体店支付、在线购物和ATM取现。其特点包括低手续费、广泛的商户网络和针对印度市场的特色服务。RuPay还支持非接触支付和移动支付,与多个数字钱包集成。对于面向印度市场的商家,特别是电子商务平台,支持RuPay支付对吸引本地客户至关重要,有助于扩大市场份额和提高用户粘性。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/SAMSUNGPAY/index.md description: >- SAMSUNGPAY 是一种便捷的移动支付方式,适用于三星手机用户在支持该服务的线上和线下商家进行支付。主要特点包括快速安全的交易处理、广泛的韩国市场覆盖率以及与三星设备生态系统的深度集成,提供指纹识别等生物认证方式确保交易安全。 --- # SAMSUNGPAY --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Santander/index.md description: >- Santander是一种支付方式，主要服务于西班牙、巴西及部分欧洲和拉丁美洲国家。支持网银转账、信用卡等多种支付手段，适用于电商购物、公共服务缴费等场景。其特点是安全可靠、操作简便，能够为用户提供快速便捷的支付体验。 --- # Santander --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Satispay/index.md description: >- Satispay是一种便捷的移动支付方式，主要服务于意大利市场。用户可以通过手机应用直接进行付款、收款及转账操作，支持多种消费场景如零售购物、公共服务缴费等。其特点包括即时到账、无需额外硬件以及提供安全的交易环境。 --- # Satispay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Sencillito/index.md description: >- Sencillito是一种便捷的在线支付方式，适用于拉丁美洲多个国家。用户可以通过银行转账或信用卡等多种方式进行快速支付。该支付方式支持一次性支付和订阅支付模式，提供安全、高效的交易体验。 --- # Sencillito --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/SEPADirectDebit/index.md description: >- SEPA是欧洲统一的支付体系，简化跨境欧元支付。主要包含SEPA直接借记(SDD)和SEPA信用转账(SCT)两种模式。SDD允许收款人在获得授权后直接扣款，适用于消费者和个人交易，支持8周内无理由退款及13个月未授权交易追溯。SCT由付款人发起，确认后不可撤销，需单独授权且无单方面退款机制。 --- # SEPA **SEPA支付系统概述** 单一欧元支付区(SEPA)是欧洲统一的支付体系，旨在简化跨境欧元支付，使其与国内支付一样高效便捷。SEPA主要包含两种核心支付模式：SEPA直接借记(SDD)和SEPA信用转账(SCT)，这两种模式在交易机制、可逆性和适用场景上存在显著差异。 **SEPA直接借记(SDD)详解【SEPA Direct Debit】** **基本原理** SEPA直接借记是一种由收款方发起的支付机制，允许收款人在获得付款人预先授权后，直接从付款人账户扣款。 **类型划分** > * **消费者直接借记(Core SDD)**：面向个人消费者的标准模式 > * **企业直接借记(B2B SDD)**：专为企业间交易设计 **退款机制** > * 消费者可在付款后**8周内无理由申请退款** > * 对于未授权交易，退款期限可延长至**13个月** > * 退款流程自动执行，无需收款方批准 **SEPA信用转账(SCT)详解【SEPA Credit Transfer】** **基本原理** SEPA信用转账是由付款人主动发起的支付方式，付款人指示其银行将资金转移至收款人账户。 **交易特性** * 交易一旦执行即被确认，基本不可撤销 * 每笔交易需付款人单独授权 * 无单方面退款机制，退款需收款方同意并主动发起 **退款机制对比** | 退款特性 | SEPA直接借记 (SDD) | SEPA信用转账 (SCT) | |---------|-------------------|-------------------| | **消费者退款权** | 付款后8周内可无理由退款 | 无法单方面退款，需收款方同意 | | **未授权交易** | 最长可追溯13个月 | - | | **退款流程** | 自动执行，无需收款方批准 | 需收款方主动发起退款交易 | **合规要求** | 集成方式 | PCI DSS | 风控JS | 3DS组件 | |:-------------------|:--------|:-----|:-------------| | 内嵌收银台 | 无需 |无需 | 无需 | | 跳转收银台 | 无需 |无需 | 无需 | | Server To Server | 无需 |无需 | 无需 | --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/SEPADirectDebit/checkout/index.md description: >- 介绍如何通过集成收银台接受SEPA Direct Debit支付，适用于欧洲经济区内的银行账户直接扣款。首先需请求收银台预下单以获取paymentUrl，随后根据接入文档跳转至收银台完成支付流程。遵循APM接入方式实践可优化用户体验。 --- # SEPA Direct Debit-收银台集成 通过集成收银台，接受SEPA Direct Debit支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`paymentUrl` ### Step2 渲染收银台 接入文档:跳转收银台 ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/SEPADirectDebit/s2s/index.md description: >- SEPA Direct Debit-API集成提供了一种通过API实现下单并支付的支付方式。适用于欧洲经济区内的企业，支持直接借记付款。关键步骤包括请求API下单并支付，获取`paymentRedirectUrl`后重定向至该地址完成支付。 --- # SEPA Direct Debit-API集成 ## 集成导航 ### step1 请求下单并支付 请求API:下单并支付 ### 重定向 下单并支付响应中获取参数`paymentRedirectUrl`。并重定向到该地址，根据页面提示完成支付。 详见Non-hosted 本地支付 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/SEPADirectDebit/sdk/index.md description: >- 介绍如何通过集成JS-SDK接受SEPA Direct Debit支付。适用于欧洲单一欧元支付区内的商户，支持安全、便捷地处理银行直接扣款交易。文档详细说明了从请求收银台预下单到渲染收银台的步骤，包括获取accessToken和使用内嵌JS-SDK的最佳实践。 --- # SEPA Direct Debit-JSSDK集成 通过集成收银台，接受SEPA Direct Debit支付。 ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken` ### Step2 渲染收银台 接入文档:内嵌JS-SDK ## 收银台接入最佳实践 详见APM 接入方式实践 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Servipag/index.md description: >- ServiPag是一种在智利广泛使用的支付方式，允许用户通过在线平台或实体网点完成账单支付。支持多种支付类型如公共服务费、信用卡还款等，为个人和企业提供便捷的支付解决方案。 --- # ServiPag --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ShopeePay/index.md description: >- ShopeePay 是一种电子钱包支付方式，主要应用于Shopee电商平台及其合作伙伴。支持地区包括印度尼西亚、马来西亚、菲律宾等东南亚国家。用户可以享受快速便捷的支付体验，并参与各种促销活动和优惠。 --- # ShopeePay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Skrill/index.md description: >- Skrill是一种全球性的在线支付方式,支持100多个国家和地区,提供快速、安全的在线转账服务。用户可以通过电子邮件地址进行收付款,支持多种货币,并可链接信用卡、借记卡和银行账户。主要特点包括即时支付确认、低手续费及多语言客户服务,适用于电子商务和个人转账等多种场景。 --- # Skrill --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/SPEI/index.md description: >- SPEI是墨西哥的一种即时银行转账支付方式。适用于希望在墨西哥境内实现快速安全转账的个人和企业用户。主要特点包括实时到账、支持多种货币以及广泛的银行网络覆盖，确保资金流转高效便捷。 --- # SPEI --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/TarjetaNaranja/index.md description: >- Tarjeta Naranja是阿根廷的领先信用卡品牌,提供创新信贷解决方案和广泛的商户网络。支持分期付款、零利率融资及虚拟卡选项,适用于在线和移动支付。其移动应用方便用户管理账户与支付。接受该支付方式有助于吸引阿根廷消费者,尤其在电商领域。 --- # Tarjeta Naranja Tarjeta Naranja是阿根廷领先的信用卡品牌,1985年创立于科尔多瓦。作为本土金融科技先驱,它以创新的信贷解决方案和广泛的商户网络闻名。Tarjeta Naranja提供多种支付选项,包括分期付款和零利率融资,深受欢迎。除实体卡外,还有虚拟卡选项,支持在线和移动支付。其移动应用让用户轻松管理账户和支付。对商家而言,接受Tarjeta Naranja有助于吸引阿根廷消费者,尤其在电商领域。该公司还致力于促进金融教育和普惠金融。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/TarjetaShopping/index.md description: >- Tarjeta Shopping是阿根廷知名信用卡品牌,由Tarshop S.A.发行,专为购物消费设计。该卡提供灵活的分期付款选项,在阿根廷零售商店、超市和在线商城广泛接受。持卡人可享受多种优惠和折扣,包括特定商户的专属优惠。此外,Tarjeta Shopping还推出了移动应用,方便用户管理账户 --- # Tarjeta Shopping Tarjeta Shopping是阿根廷知名的信用卡品牌,由Tarshop S.A.发行。作为一种专门针对购物消费的信用卡,它在阿根廷的零售市场中占有重要地位。Tarjeta Shopping提供灵活的分期付款选项,让消费者能够更轻松地进行大额购物。该卡在众多零售商店、超市和在线商城中被广泛接受。持卡人可以享受各种优惠和折扣,包括特定商户的专属优惠。近年来,Tarjeta Shopping也推出了移动应用,方便用户管理账户、查看交易和支付账单。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/TeenCash/index.md description: >- Teen Cash是一种专为青少年设计的预付卡支付方式,主要在北美地区使用。该支付方法允许家长为孩子设置消费限额和查看交易记录,以帮助管理孩子的财务行为。支持在线购物及部分实体店铺消费,特别适合希望培养孩子理财意识的家庭。 --- # Teen Cash --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/ThailandBanks/index.md description: >- KrungsriBank是泰国主要银行之一,提供包括二维码支付、P2P转账及账单支付在内的多种数字支付服务。通过SCB EASY移动应用,该行在泰国境内广泛支持电子商务与跨境支付需求,致力于推动无现金社会发展,同时兼顾传统银行业务。 --- # KrungsriBank Siam Commercial Bank是泰国最古老的银行,提供创新的数字支付解决方案。其移动银行app SCB EASY在泰国广泛使用,支持二维码支付、P2P转账和账单支付。为电子商务和跨境支付提供全面解决方案。作为泰国金融科技的领导者,Siam Commercial Bank不断推出新的数字服务,助力泰国向无现金社会转型,同时保持传统银行业务的稳健发展。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Tmoney/index.md description: >- T money是一种电子钱包支付方式,广泛应用于日本的公共交通、零售商店和在线购物。用户可通过手机应用或实体卡进行充值和支付,支持NFC技术实现快速交易。主要特点包括便捷性高、安全性好以及普及度广,适用于日常小额支付场景。 --- # T money --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/TNGeWallet/index.md description: >- TNGeWallet是一种电子钱包支付方式，主要在马来西亚地区使用。支持用户通过手机应用完成在线购物、转账及账单支付等功能。该支付方式具备安全便捷的特点，适用于各类线上交易场景。 --- # TNGeWallet --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/TOSS/index.md description: >- TOSS是一种韩国流行的在线支付方式，支持多种支付手段如信用卡、银行转账等。适用于电商网站和移动应用，提供便捷的支付体验。覆盖韩国主要银行与金融机构，支持即时支付确认及退款功能。 --- # TOSS --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Troy/index.md description: >- Troy是一种主要在土耳其使用的支付方式，支持借记卡和信用卡交易。适用于在线购物、账单支付等多种场景。具有快速结算、安全可靠的特点。商家接入后可以吸引更多土耳其本地消费者。 --- # Troy --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/TrueMoneyWallet/index.md description: >- TrueMoney Wallet 是一种电子钱包支付方式,主要在泰国及部分东南亚国家使用。支持用户通过手机应用完成在线购物、账单支付以及转账等操作。该支付方式具有便捷快速的特点,适用于电商平台、移动应用内购等多种场景,并提供多种语言版本以满足不同用户需求。 --- # TrueMoney Wallet --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Trustly/index.md description: >- Trustly是一种即时在线银行转账支付方式，允许消费者直接从其银行账户进行支付。主要特点包括无需注册、快速安全以及支持多种货币。适用于希望提供无缝支付体验的电子商务平台。覆盖欧洲及北美地区，特别适合需要高效处理交易的商家。 --- # Trustly --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Twint/index.md description: >- Twint是一种瑞士流行的移动支付方式,允许用户通过智能手机应用进行快速安全的转账和支付。适用于线上购物、实体店付款及个人间转账等多种场景。支持实时交易确认,无需携带现金或银行卡,并提供多种语言服务,覆盖全瑞士地区。 --- # Twint --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/UnionBankOnlinePayment/index.md description: >- UnionBank是菲律宾领先的数字化银行之一,提供便捷的在线银行支付服务。用户可通过UnionBank账户进行快速安全的网上支付、转账和账单缴费。该支付方式以其创新的数字银行解决方案、高安全标准和用户友好的界面著称,广泛应用于电子商务和在线交易场景。 --- # UnionBank --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/UnionPaySecurePay/index.md description: >- UnionPaySecurePay是中国银联提供的安全支付解决方案,适用于中国境内线上及移动支付场景。支持多种银行卡类型,通过加密技术保障交易安全,简化支付流程,提高支付成功率。商家可轻松集成此支付方式以覆盖广泛的中国消费者。 --- # UnionPaySecurePay --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/UPI/index.md description: >- UPI是一种即时支付系统，用于印度境内的银行间资金转账。支持通过手机号码或虚拟支付地址进行快速、安全的交易，无需提供敏感银行信息。广泛应用于个人对个人转账、在线购物及账单支付等多种场景。 --- # UPI --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/Venmo/index.md description: >- Venmo是一种便捷的移动支付服务，允许用户通过手机应用向朋友或商家付款。主要在美国使用，支持即时转账、账单拆分及在线购物。其特点是操作简便、社交性强，用户可以轻松添加好友并查看交易记录。 --- # Venmo --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/VirtualAccount/index.md description: >- DOKU VA 是一种虚拟账户支付方式，适用于印度尼西亚市场。支持用户通过银行转账至指定虚拟账户完成支付，提供便捷的在线支付体验。主要特点包括实时交易确认、支持多种本地银行以及易于集成到商户系统中。 --- # DOKU VA Qris（Quick Response Code Indonesian Standard）是印度尼西亚的统一二维码支付标准。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/virtualAccountKorea/index.md description: >- 虚拟账户支付是韩国常用的一种在线支付方式,允许用户通过银行转账完成付款。主要特点包括即时到账通知、支持多家韩国本地银行、适用于电商平台和各类线上服务场景。此支付方式提供便捷安全的交易体验,特别适合需要频繁小额支付的业务。 --- # Virtual Account Korea --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/VNMQR/index.md description: 'VNM QR是一种基于二维码的支付方式,适用于越南市场。用户通过扫描商家提供的二维码完成支付,支持多种电子钱包和银行应用,为消费者提供便捷安全的支付体验。' --- # VNM QR --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/WechatPay/index.md description: >- WechatPay是微信支付方式，适用于中国地区的PC端和移动端支付。主要特点包括：显示微信支付二维码、支持用户扫码支付、实时更新支付状态。在PC端，用户通过扫描二维码完成支付；在移动端，根据浏览器环境调起微信支付或显示二维码。使用时需确保域名已加入微信H5支付授权，并设置Referer请求头。 --- # WechatPay ## 支付域名授权 根据微信要求，需要将商户的域名加入微信的 H5 支付授权域名中。并且需设置 Referer 请求头。 我们默认将您的申请开户申报的域名加入微信的 H5 支付授权域名中。 如果您需要添加其他域名， 请您将相关申请信息发送到`acquire-risk@pingpongx.com`并抄送`acquire-ts@pingpongx.com`。 **申请材料：** 1. 商户Client ID 2. 商户授权域名 ## 支付场景说明 ### PC端支付 * 显示微信支付二维码 * 用户使用微信扫码完成支付 * 页面实时显示支付状态更新 ### 移动端支付 1. **微信内浏览器**：暂不支持直接调起微信支付，根据微信要求需要JSAPI调用。 2. **微信外浏览器**： * iOS：跳转到微信客户端 * Android：显示二维码或尝试调起微信 * 其他情况：显示二维码供扫码支付 :::danger 提示 * 您的域名必须加入微信 H5 支付授权域名。 * 微信对Referer 的要求严格，请务必设置 Referer 请求头。 * 确保用户通过页面跳转进入支付页面，而非直接访问支付链接 ::: ## 常见问题 ### 错误提示："商家参数格式有误，请联系商家解决" **问题原因：** * Referer 请求头为空或缺失 * 用户直接访问支付链接，未通过页面跳转 **解决方案：** 1. 确保用户通过页面跳转进入支付页面，而非直接访问支付链接 2. App 内 WebView 需手动设置 Referer 请求头： ```java Map
支付结果通知 Note over User, WeChat: 🎯 WeChat Pay跳转收银台流程完成 ``` ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`paymentUrl`用于跳转收银台 ### Step2 渲染收银台 使用Step1获取的`paymentUrl`跳转收银台，接入文档:跳转收银台 ## 重新支付 收银台若未支付成功，可以手动打开URL再次发起支付，一个收银台URL有效时长为48小时 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/WechatPay/miniProgram/index.md description: >- 微信小程序支付集成通过统一下单API实现，支持在小程序内完成支付。适用于中国大陆地区，主要特点包括无需跳转、基于微信小程序安全机制、标准化API调用流程及流畅快速的支付体验。关键参数包括用户openid、小程序AppID和订单终端标识。 --- # WeChat Pay 微信小程序支付集成 ## 🚀 快速开始 **核心特点**: * ✅ 无需跳转，小程序内完成支付 * 🛡️ 基于微信小程序安全机制 * 🔌 标准化API调用流程 * ⚡ 支付体验流畅快速 ## 微信小程序支付交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant User as 👤 用户 participant MiniApp as 📱 小程序前端 participant Merchant as 🏪 商户后端 participant PP as 🔄 PingPongCheckout服务端 participant WeChat as 💬 微信支付平台 Note over User, WeChat: 🚀 微信小程序支付流程 Note over User, MiniApp: 📋 准备阶段：用户在小程序内发起支付 User->>MiniApp: 1️⃣ 用户点击支付按钮 MiniApp->>MiniApp: 2️⃣ 获取用户openid Note right of MiniApp: 调用wx.getUserProfile()
或使用授权登录 MiniApp->>+Merchant: 3️⃣ 发送支付请求 Note right of Merchant: 包含商品信息、金额
和用户openid Merchant->>Merchant: 4️⃣ 业务验证 Note right of Merchant: 订单验证、库存检查
风控校验等 Merchant->>+PP: 5️⃣ 调用统一下单API Note right of PP: 包含小程序特有参数：
wxOpenId、wxAppId
device.orderTerminal=06 PP->>+WeChat: 6️⃣ 调用微信统一下单 Note right of WeChat: PSP调用微信
机构平台API WeChat-->>-PP: 7️⃣ 返回prepay_id等参数 PP-->>-Merchant: 8️⃣ 返回支付参数 Note right of PP: 包含extraParam.wxPrepayId
和其他必要参数 Merchant->>Merchant: 9️⃣ 构造小程序支付参数 Note right of Merchant: 生成支付签名
准备wx.requestPayment参数 Merchant-->>-MiniApp: 🔟 返回支付参数到小程序 MiniApp->>MiniApp: 1️⃣1️⃣ 调用wx.requestPayment() Note right of MiniApp: 使用返回的参数
调起微信支付 MiniApp->>+WeChat: 1️⃣2️⃣ 唤起微信支付界面 User->>WeChat: 1️⃣3️⃣ 用户完成支付认证 WeChat-->>-MiniApp: 1️⃣4️⃣ 支付结果回调 alt ✅ [支付成功] WeChat->>+PP: 1️⃣5️⃣ 异步支付结果通知 PP->>PP: 处理支付结果 PP->>+Merchant: 1️⃣6️⃣ 异步通知商户 Merchant-->>-PP: 确认接收通知 PP-->>-WeChat: 确认处理完成 MiniApp->>+Merchant: 1️⃣7️⃣ 查询支付结果 Merchant-->>-MiniApp: 返回支付成功状态 MiniApp-->>User: 1️⃣8️⃣ 显示支付成功页面 else ❌ [支付失败/取消] MiniApp-->>User: 显示支付失败信息 Note right of MiniApp: 用户可重试支付 end Note over User, PP: 🎯 微信小程序支付流程完成 ``` ## 集成导航 ::: note 提示 1. 微信小程序支付仅在微信小程序环境内可用，需要获取用户openid。 2. 您需要提前完成微信小程序的基础配置和支付权限申请。 3. 建议在沙箱环境充分测试后再上线生产环境。 ::: ### 前置条件 #### 🔧 微信小程序配置 **必要条件**： * ✅ 已开通微信小程序并通过认证 * ✅ 已获得微信支付商户号 * ✅ 已在微信支付商户平台开通JSAPI支付权限 * ✅ 已配置支付授权目录 ### 请求下单并支付 使用下单并支付接口创建微信小程序支付订单。 在API下单并支付的响应中： * status 为 `SUCCESS` 时，订单已支付成功 * status 为 `PROCESSING` 时，订单已创建，返回`extraParam.wxPrepayId`供小程序调用 * status 为 `FAILED` 时，订单创建失败 **关键参数：** | 参数 | 类型 | 必传 | 说明 | |--------------------------|--------|-----|-----------------------------| | `paymentMethod.wxOpenId` | String | 是 | 用户在小程序内的唯一标识，通过wx.login()获取 | | `paymentMethod.wxAppId` | String | 是 | 微信小程序的AppID，在小程序后台获取 | | `device.orderTerminal` | String | 是 | 固定传 `06`（微信小程序标识） | | `paymentMethod.type` | String | 是 | 固定传 `WeChat Pay` | **参数示例：** ### 小程序前端调用微信支付 获取API返回的`extraParam.wxPrepayId`后，在小程序中调用[`wx.requestPayment()`](https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestPayment.html)完成支付。 ::: steps 1. **获取用户openid** 使用[`wx.login()`](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html)获取code，后端换取openid ```javascript wx.login({ success: (res) => { // 发送code到后端换取openid this.getOpenIdFromBackend(res.code); } }); ``` 2. **发起支付请求** 将openid等参数传给商户服务端，商户服务端调用统一下单API ```javascript wx.request({ url: 'https://yourapi.com/payment/create', method: 'POST', data: { openid: this.data.openid, amount: this.data.amount, // 其他订单信息 } }); ``` 3. **调起微信支付** 使用返回的prepayId调用[`wx.requestPayment()`](https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestPayment.html) ```javascript wx.requestPayment({ timeStamp: paymentData.timeStamp, nonceStr: paymentData.nonceStr, package: `prepay_id=${prepayId}`, signType: 'RSA', paySign: paymentData.paySign, success: (res) => { // 支付成功，查询支付状态 this.queryPaymentResult(); }, fail: (err) => { // 支付失败处理 console.log('支付失败', err); } }); ``` 4. **处理支付结果** 监听支付回调，查询支付状态 ```javascript onPaymentSuccess() { // 向后端查询最终支付结果 wx.request({ url: 'https://yourapi.com/payment/query', success: (res) => { if (res.data.status === 'SUCCESS') { wx.redirectTo({ url: '/pages/success/success' }); } } }); } ``` ::: ## 完整代码示例 ### 📱 小程序前端实现 ```javascript // pages/payment/payment.js Page({ data: { orderInfo: {}, loading: false }, onLoad(options) { this.setData({ orderInfo: { amount: options.amount || '100', productName: options.productName || '测试商品' } }); }, // 获取用户openid async getOpenId() { return new Promise((resolve, reject) => { wx.login({ success: (res) => { wx.request({ url: 'https://yourapi.com/wechat/auth', method: 'POST', data: { code: res.code }, success: (result) => resolve(result.data.openid), fail: reject }); } }); }); }, // 发起支付 async requestPayment() { try { this.setData({ loading: true }); wx.showLoading({ title: '支付中...' }); const openid = await this.getOpenId(); const paymentRes = await this.createPaymentOrder(openid); if (paymentRes.code === '000000') { const paymentData = JSON.parse(paymentRes.bizContent); const prepayId = paymentData.extraParam.wxPrepayId; // 获取支付签名并调起支付 const signData = await this.getPaymentSign(prepayId); this.callWechatPay(signData, prepayId); } } catch (error) { console.error('支付请求异常', error); wx.showToast({ title: '支付请求失败', icon: 'error' }); } finally { this.setData({ loading: false }); wx.hideLoading(); } }, // 调起微信支付 callWechatPay(signData, prepayId) { wx.requestPayment({ timeStamp: signData.timeStamp, nonceStr: signData.nonceStr, package: `prepay_id=${prepayId}`, signType: 'RSA', paySign: signData.paySign, success: () => this.onPaymentSuccess(), fail: (err) => this.onPaymentFail(err) }); }, // 支付成功处理 onPaymentSuccess() { wx.showToast({ title: '支付成功', icon: 'success' }); setTimeout(() => { wx.navigateBack(); }, 1500); }, // 支付失败处理 onPaymentFail(error) { if (error.errMsg.includes('cancel')) { wx.showToast({ title: '支付已取消', icon: 'none' }); } else { wx.showToast({ title: '支付失败', icon: 'error' }); } } }); ``` ## 常见问题与解决方案 ### ⚠️ openid获取失败 **常见原因**： * 🔥 小程序登录流程不正确 * ⏰ code超过\*\*有效期（5分钟）\*\*使用 * 🔑 小程序AppID和AppSecret配置错误 **解决方案**： ```javascript // ✅ 正确的openid获取流程 wx.login({ success: (res) => { if (res.code) { // 🔥 立即发送到后端，不要延迟 this.getOpenIdFromServer(res.code); } else { console.log('登录失败！' + res.errMsg); } } }); ``` ::: tip 重要提醒 **code的有效期只有5分钟**，获取后应立即使用，避免缓存或延迟处理。 ::: ### ⏱️ prepayId无效或过期 **原因分析**： * 🔗 API调用未成功返回 * ⏰ prepayId**有效期为2小时**，已过期 * 🌐 网络延迟影响使用时效 ::: tip 最佳实践 获取prepayId后应**立即调起支付**，避免因延迟导致过期。建议在前端设置合理的超时提醒。 ::: ### 🔐 支付权限问题 **小程序支付权限未开通**： * ✅ 确认已开通**JSAPI支付权限** * 🔗 检查小程序与商户号的绑定关系 **支付目录配置错误**： * ⚙️ 在微信支付商户平台配置支付授权目录 * 🌐 确保支付页面的域名在授权目录范围内 ## 技术支持 ### 📚 参考文档 * **微信官方文档**: [小程序支付接入指南](https://pay.weixin.qq.com/doc/v3/merchant/4012791911) * **微信小程序API**: [wx.login() 登录接口](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html) * **微信支付API**: [wx.requestPayment() 支付接口](https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestPayment.html) ### 🛠️ 推荐工具 * **微信开发者工具**: 小程序开发和调试的官方工具 *** ::: important 上线前检查清单 在生产环境上线前，请确保完成以下检查： * 验证所有错误场景的处理逻辑 * 确认异步通知处理的正确性和==幂等性== * 检查支付金额、订单信息的准确性 * 配置生产环境的==HTTPS证书==和域名 * 设置合适的日志记录和==监控告警== ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/paymentMethods/WechatPay/s2s/index.md description: >- WeChat Pay Server To Server集成文档介绍了如何通过S2S方式实现微信支付。适用于PC、移动端浏览器及Webview内支付场景，覆盖中国大陆地区。关键参数包括`device.orderTerminal`和`shopperIP`。支持直接拉起微信支付或通过中间页处理支付流程，确 --- # WeChat Pay Server To Server 集成 ## WeChat Pay-Server To Server交互流程 ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant User as 👤 用户 participant Frontend as 💻 商户前端 participant Merchant as 🏪 商户后端 participant PP as 🔄 PingPong服务端 participant WeChat as 💬 WeChat Pay Note over User, WeChat: 🚀 WeChat Pay Server To Server集成流程 Note over User, Frontend: 📋 准备阶段:• 用户选择支付• 商户自建收银台 User->>Frontend: 1️⃣ 用户进入商户收银台页面 User->>Frontend: 2️⃣ 选择WeChat Pay支付方式 Frontend->>+Merchant: 3️⃣ 提交订单信息 Note right of Merchant: 订单验证
金额计算 Merchant->>+PP: 4️⃣ 调用下单并支付API Note right of PP: 创建支付订单
获取微信支付参数 PP-->>-Merchant: 返回支付参数（二维码/调起参数） Merchant->>-Frontend: 5️⃣ 返回支付参数到前端 Note over Frontend, WeChat: 💳 微信支付交互 alt 🖥️ [PC端支付] Frontend->>Frontend: 6a️⃣ 显示微信支付二维码 User->>WeChat: 7a️⃣ 用户扫码支付 WeChat->>WeChat: 用户完成支付授权 else 📱 [移动端支付] Frontend->>+WeChat: 6b️⃣ 调起微信客户端 Note right of WeChat: H5跳转微信支付
或微信内直接支付 User->>WeChat: 7b️⃣ 用户完成支付授权 WeChat-->>-Frontend: 支付结果页面跳转 end WeChat->>+PP: 8️⃣ 微信支付结果通知 PP->>PP: 9️⃣ 处理支付结果 Note right of PP: • 验证支付结果• 更新订单状态• 风控检查 PP->>+Merchant: 🔟 异步通知支付结果 Note right of Merchant: 订单状态更新
业务逻辑处理 Merchant-->>-PP: 确认通知接收 alt ✅ [支付成功] PP-->>WeChat: 支付处理完成 Note over Frontend, Merchant: 🔄 状态轮询（可选） Frontend->>+Merchant: 1️⃣1️⃣ 轮询支付状态 Merchant-->>-Frontend: 返回最新状态 Frontend->>Frontend: 1️⃣2️⃣ 显示支付成功页面 Note over Frontend: 商户自定义逻辑
支付完成处理 else ❌ [支付失败] PP-->>WeChat: 支付失败处理 Frontend->>Frontend: 显示支付失败页面 Note right of Frontend: 错误处理
用户提示 end Note over User, PP: 🎯 WeChat Pay Server To Server流程完成 ``` ## 集成导航 ### Step1 调用下单并支付 使用下单并支付接口直接发起微信支付 ### Step2 处理支付响应 根据不同支付场景处理返回的支付参数： **关键参数说明：** 1. `device.orderTerminal` * 02-PC端浏览器(pc) * 04-SDK(ios) * 05-SDK(Android) 2. `shopperIP` * 用户的公网IP地址，微信支付要求必须传递，否则会报错 * 请获取真实的消费者IP地址，不能使用localhost、127.0.0.1等回环地址 ## PC端支付 `device.orderTerminal` = `02` 下单并支付接口返回参数： * `qrCode` : 微信的`qrCode`，需要商户自行处理二维码展示 * `paymentRedirectUrl` : PingPongCheckout包装的二维码页面，只需要重定向到该页面 ## 移动端浏览器支付 `device.orderTerminal` = `04` 或 `05` 下单并支付接口返回参数： * `paymentRedirectUrl` : 对应微信的`mwebUrl`参数 ## Webview内支付 `device.orderTerminal` = `04` 或 `05` 下单并支付接口返回参数： * `paymentRedirectUrl` : 对应微信的`mwebUrl`参数 ### 方案1：Webview直接拉起微信支付 ::: steps 1. **请求下单并支付接口，获取`paymentRedirectUrl`。** 2. **设置 Referer** **Android：在 loadUrl 时添加 Referer** ```kotlin val headers = mutableMapOf
生成访问令牌 PP-->>-Merchant: 返回accessToken Merchant->>Frontend: 2️⃣ 传递accessToken到前端 Frontend->>Frontend: 3️⃣ 加载PingPong JavaScript SDK Note right of Frontend: 引入CDN资源
初始化SDK环境 Frontend->>+SDK: 4️⃣ 初始化收银台组件 Note right of SDK: 使用accessToken
渲染内嵌收银台UI SDK->>+PP: 5️⃣ 验证accessToken并获取配置 PP-->>-SDK: 返回收银台配置信息 SDK-->>-Frontend: 收银台组件加载完成 User->>Frontend: 6️⃣ 用户选择WeChat Pay支付 Frontend->>+SDK: 7️⃣ 触发支付事件 alt PC端支付流程 SDK->>+WeChat: 8️⃣a 请求生成支付二维码 WeChat-->>-SDK: 返回支付二维码 SDK-->>Frontend: 展示支付二维码 Frontend-->>User: 向用户展示二维码 User->>User: 使用手机扫描二维码 User->>WeChat: 在手机微信中确认支付 else 手机端支付流程 SDK->>+WeChat: 8️⃣b 请求拉起微信App支付 WeChat-->>-SDK: 返回拉起参数 SDK-->>Frontend: 传递拉起参数 Frontend-->>User: 调起微信App User->>WeChat: 在微信App中确认支付 end WeChat->>PP: 支付结果通知 PP->>PP: 9️⃣ 处理支付 Note right of PP: • 验证支付信息
• 风控检查
• 支付路由处理 alt ✅ 支付成功 PP-->>SDK: 🎉 支付成功 SDK->>SDK: 显示成功状态 SDK-->>Frontend: 支付成功回调 Frontend-->>User: 展示支付成功信息 Note over Frontend: 商户自定义逻辑
支付完成处理 PP->>Merchant: 🔟 异步通知支付结果 Note right of Merchant: 订单状态更新
业务逻辑处理 else ❌ 支付失败 PP-->>SDK: ❌ 支付失败 SDK->>SDK: 显示错误状态 SDK-->>Frontend: 支付失败回调 Frontend-->>User: 展示支付失败信息 Note right of Frontend: 错误处理
用户提示 end Note over User, WeChat: 🎯 WeChat Pay内嵌收银台流程完成 ``` ## 集成导航 ### Step1 请求收银台预下单 在API收银台预下单的响应中，您可以获取`accessToken` ### Step2 集成SDK组件 接入文档:内嵌SDK（预下单） --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/reconciliation/settlementCycle/index.md description: >- 结算周期和对账单定义了PingPongCheckout的结算规则及对账方式。支持T+(N)、指定日期和周结三种结算模式，具体周期依合同而定。对账单按结算周期分为每日、每周或每月生成，数据区间对应不同结算类型，确保准确反映交易状态。 --- # 结算周期 ## 结算周期规则 目前有如下的两种可配置的结算周期规则： 1. T+(N) 【自交易发生日后+N日结算】 2. 指定日期 【如每月的26日】 3. 周结 【如每周五】 ::: note 提示 具体结算周期以合同为准 ::: ## 对账单 | 结算周期 | 对账单类型 | 建议取数据时间 | 数据区间 | 说明 | |---------|-----------|--------------|---------|------| | CYCLE (D+N) | 依赖对账单 | 每日 | \[T, T+1) | T日的交易在T+N日结算，需等待对账 | | WEEKLY | 依赖对账单 | 每周指定日+1 | \[T-7, T) | 本周指定日结算前7天的订单，T为当前日期 | | MONTHLY | 依赖对账单 | 每月指定日+1 | \[上月指定日, 本月指定日) | 本月指定日结算前一个月的订单 | ::: note 提示 上述表格中的时间UTC+0时间,如果在当前数据区间没有已结算的交易，账单文件不会生成 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/reconciliation/settlementFilePath/index.md description: >- 对账文件在SFTP的路径规则用于指导商户在SFTP服务器上查找账单文件。每个商户的账单文件存放在以`clientId\登录名`命名的目录下，每天、每周、每月分别以`YYYYMMDD`、`YYYYMMDD-YYYYMMDD`、`YYYYMM`格式生成新的子目录存放相应周期的账单压缩文件。 --- # 对账文件在SFTP的路径规则 SFTP服务器存在多个账单文件，您需要根据下列的规则找到您的账单文件。 ## SFTP地址 ::: code-tabs @tab 测试环境 ```http test-ppsftp.pingpongx.com:22222 ``` @tab 生产环境 ```http ppsftp.pingpongx.com:22222 ``` ::: ## 文件路径约定 每个商户的账单文件都将归集到以约定的规则命名文件夹下，定时每天以 `YYYYMMDD` 命名新增文件夹。文件夹内的zip文件为商户的账单文件。 ### 特定商户目录 ::: warning 提示 使用给定的用户名登录后会自动进入 约定的clientId\登录名目录中clientId这一层 ::: 在找到您的账单压缩文件前，您首先需要找到自己的目录所在 在SFTP上使用特定的文件路径标识指定商户存放账单的文件夹，规则为`clientId\登录名`。这部分 `path` 是固定的 ::: theorem 示例： `clientId`=`2023052907161543393`,`登录名`=`worldready`的商户存放的文件目录如下： `2023052907161543393/worldready` ::: ### 日账单目录 `2023-10-25`这一天的账单 `path`： ::: tip 示例 1. 商户的目录 2023052907161543393/worldready 2. 根据 YYYYMMDD目录命名规则，`20231025`是这一天账单目录 ::: ### 周账单目录 `20231016-20231022` 这一周的账单 `path`： ::: tip 示例 1. 商户的目录 2023052907161543393/worldready 2. 根据 YYYYMMDD-YYYYMMDD目录命名规则，`20231016-20231022`是这一周账单目录 ::: ### 月账单目录 `202309` 这一月的账单 `path`： ::: tip 示例 1. 商户的目录 2023052907161543393/worldready 2. 根据 YYYYMM目录命名规则，`202309`是这一月账单目录 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/reconciliation/settlementFileSheet/index.md description: >- 对账单sheet说明文档介绍了PingPongCheckout的账单模板及各sheet用途，包括结算报告、交易流水、退款、拒付费用等关键数据，帮助商户进行财务核对与管理。 --- # 对账单sheet说明 ## 账单模板 获取 PingPongCheckout 账单模板 ## 对账单sheet | sheet | 说明 | |:------------------|:-----------------| | Settlement Report | 结算报告，总览当前账期数据 | | Purchase | 已交易结算流水数据和交易费用数据 | | Refund | 退款和退款费用流水数据 | | Chargeback | 拒付费用数据 | | Reserve | 循环保证金 | | Deposit | 固定保证金 | | Withdrawal | 提现明细 | | Other Fee | 其他费用 | | Adjustment | 调账明细 | ## 对账单字段明细 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/reconciliation/transactionStatementDownload/index.md description: >- SFTP对账服务用于下载交易报表，所有报告将上传至SFTP服务器并以zip格式提供。申请前需提交商户服务器IP、RSA公钥及ClientId至指定邮箱。PingPongCheckout会将IP加入白名单，公钥配置于SFTP服务中，并用ClientId生成对账单。 --- # SFTP服务申请 PingPongCheckout 提供SFTP对账服务，所有报告将会上传到 SFTP务器中，您可以通过访问SFTP 服务器中的特定目录下载对账报告。通过 SFTP 服务器所下载对账报告为zip 压缩文件。 在使用对账服务前，您需要提交以下申请材料，申请SFTP访问权限。 ## SFTP服务申请 请将`申请材料` 通过邮件发送到 `acq-tech-mc@pingpongx.com`并抄送 `acq-ts@pingpongx.com`。 ### 申请材料 1. 商户服务器IP; * PingPongCheckout 将会把商户服务器 `IP` 加入 `IP 白名单`,未加入白名单的 `IP` 不可访问 PingPongCheckout SFTP 服务 2. 商户RSA公钥; * PingPongCheckout 将会把商户 RSA 公钥加入 SFTP 服务，之后商户可以凭此公钥对应的私钥访问 `SFTP` 服务。 3. 商户ClientId; * PingPongCheckout 将会把商户 ClientId 加入 SFTP对账单生成服务，以便于生成数据。 ## 商户RSA公钥获取 ### 从服务器上导出RSA公钥 如果您知道服务器公钥文件所在，可以尝试导出公钥，使用`cat /path/to/public_key.pub`命令可以查看公钥内容，例如： ```bash cat .ssh/id_rsa.pub ``` ### 生成秘钥 如果您不清楚公钥文件所在路径，可以生成一对RSA秘钥。 ```bash ssh-keygen -t rsa ``` :::danger 注意 1. 请确保密钥对的私钥（private\_key.pem 或 id\_rsa）存储在安全的位置，并且不能被他人访问。如果您担心私钥的安全性，可以设置一个密码来加密私钥文件。 2. 对账周期：按照合同约定。 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/recurring/recurring/index.md description: >- 订阅支付API支持定期自动扣款功能，适用于需要长期向用户收取费用的场景。提供两种接入模式：Hosted和Non-hosted。关键步骤包括持卡人授权及计划扣款，通过设置`bizType`为`Recurring`标记交易类型，并在计划扣款时使用首次交易的`primaryMerchantTransact --- # 订阅支付 ## 接入前提 需要接入下列其中一种模式，以便于完成支付和授权流程 Hosted Non-hosted ## 交互过程 ### 持卡人授权事件交互流程 ### 计划扣款事件交互流程 ## API清单 ## 服务端接入 ### 持卡人授权 | 字段名称 | 类型 | 必填 | 描述 | |:-----------------------------|:-----------|:----|:------------------------------------| | bizType | String(64) | M | Recurring交易标识，固定值`Recurring` | 在请求下单并支付 时候新增参数`bizType`=`Recurring`，标记当前交易为recurring交易 ### 计划扣款 | 字段名称 | 类型 | 必填 | 描述 | |:-----------------------------|:-----------|:----|:------------------------------------| | primaryMerchantTransactionId | String(64) | M | 首次成功下单时候异步通知中的merchantTransactionId | | bizType | String(64) | M | Recurring交易标识，固定值`Recurring` | 商户服务端请求下单并支付，发起计划扣款 * 新增参数`bizType`=`Recurring`，标记当前交易为recurring交易 * 新增参数`primaryMerchantTransactionId`，值为首次扣款时候的`merchantTransactionId` * 参数`cardInfo`由`primaryMerchantTransactionId`代替，不用传送 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/risk/3ds/index.md' description: >- Dynamic 3D Secure是一种安全协议，用于在线交易验证及防欺诈。适用于支持PingPongCheckout的网站或移动应用，在支付过程中增加额外的安全层。根据风险评估，系统自动决定是否启用3D认证。认证流程包括无需用户交互的Frictionless和需额外验证的Challenge两种方式 --- # Dynamic 3D Secure 3D Secure是一种安全协议，用于验证在线交易并防止电子商务中的欺诈活动。它要求持卡人在完成交易前输入密码或一次性代码，从而为支付过程增加了额外的安全层。 当您的网站或移动应用程序支持3D Secure时，发送支付的请求PingPongCheckout将确定是否通过3D 安全认证支付。 ## 3D Secure 认证流程 ### Frictionless 在Frictionless 流程中，购买者、发行者和卡方案通过使用购物者的设备指纹的被动认证在后台交换所有必要的信息。事务在没有进一步的购物者交互的情况下完成。 ### Challenge 在Challenge 流程中，银行或支付处理机构会自动为持卡人创建一个3D挑战页，购物者需要进行额外的交互。发卡行通过生物特征识别、双因素身份验证，或者基于 SCA 身份验证因素等类似方法确保交易的安全性。 一旦卡片持有人完成了3D挑战页上的身份验证步骤，他们的身份将被验证，并且银行或支付处理机构可以决定是否批准该交易。 ## 默认的3D 安全规则 一般的，PingPongCheckout提供默认的3D 安全规则，PingPongCheckout风控引擎将决定当前交易是否需要启用3DS认证。 | 策略 | 描述 | 3DS 组件集成 | 额外要求 | |:----:|:--------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------:| | 笔笔3D | 3D Secure 始终启用 | | | | 智能决策 | 根据持卡人行为特征智能决策 | Hosted: Non-Hosted: | customer.email | ## 商户自主决策 如果PingPong提供的默认规则不能满足您自定义需求，PingPongCheckout提供了商户自主决策的能力。 您可以根据自己的业务场景，在API中通过`executeThreeD`参数决定是否启用3DS认证。 ::: danger 注意 是否能开通需根据商户风险情况和拒付表现进行评估，需要的话可以联系技术支持开通配置。 ::: | executeThreeD | 收银台支持 | 端到端模式支持 | 描述 | |:--------------|:--------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------|:------------------------------------------------| | Y | | | 强制进行3ds验证，并且使用PingPongCheckout的3ds。 | | depends | | | 是否进行3ds验证交由PingPongCheckout的风控决策决定 | | external | | | 需要进行3ds验证，在商户执行3ds，并把3ds结果交由PingPongCheckout执行。 | ## 3DS集成方案 ### 3DS服务集成 如果您尚未接入3DS服务，可以使用PingPongCheckout提供的3DS服务。PingPongCheckout提供了以下集成方案： | 集成方案 | Hosted是否需要集成 | Non-Hosted是否需要集成 | 风控 | 3DS | 备注 | |:-----------------|:--------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------|:---------------------------------------------------------------------------------|:-----------------------------------------------------------------------------|-----------| | SafePayGuardJs组件 | | | | | 可集成 | | RiskDefense组件 | | | | | 不推荐，方案已移除 | | SecureShieldJs组件 | | | | | 可集成 | | Server To Server | | | | | 可集成 | ### 商户自行上送 3DS 结果 如果您已经接入3DS服务，并且能够自主产生3DS结果，您可以选择商户自行上送3DS结果。 详见 3DS external --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/risk/dispute/index.md' description: >- 争议处理功能在持卡人对付款提出异议并发起拒付时启用。通过Disputes API，可以自动化管理争议流程，包括调单、拒付通知处理及抗辩材料提交等步骤。使用eventCode判断拒付阶段，并根据需要上传或删除相关辩护材料以进行有效抗辩。 --- # dispute 当持卡人对付款提出异议并联系其发卡行发起拒付时，就会发生争议。我们的dispute api可让您自动执行争议处理流程，以便您可以在争议发起后立即做出回应。 ## dispute API 处理流程 ### 调单 调单发生时候，发卡行要求提供有关交易的更多信息。在这个阶段，您的账户中不会提取款项，建议您积极处理。 ### 拒付 使用 Disputes API 时，您需要执行以下操作： * 处理拒付通知。使用eventCode来确定拒付处于哪个阶段。 * 检索拒付信息以了解如何为争议辩护，比如调用查询拒付抗辩材料。 * 如果您想为争议辩护，请继续执行第 3 步。 - 提交材料并进行抗辩 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/risk/disputeNotify/index.md description: >- 拒付通知接入说明提供了商户如何接收并处理拒付相关事件的指南。适用于需要实时了解和响应拒付情况的商户，通过配置技术支持提供的回调地址，接收PingPongCheckOut以HTTP POST方式发送的JSON格式异步通知。关键特性包括支持特定eventCode识别拒付阶段，以及通过返回200 Http --- # 拒付通知接入说明 ## 异步通知概述 * 如需开通拒付通知，可以联系技术支持同学进行配置。 * 每当，拒付相关事件发生时（如调单发生时），PingPongCheckOut 通知服务将会创建一个JSON对象，其中包含事件相关的数据等信息。 * 然后，PingPongCheckOut 通知服务通过 HTTP POST 请求将JSON对象发送到已配置的通知地址中。 商户侧在收到回调通知后，可根据异步通知报文做下一步的业务处理。 ## 接收异步通知 ### 准备一个支持 HTTP POST 的web服务 PingPongCheckOut 通知服务将以 HTTP POST 方式推送 JSON 格式的数据，因此开发者所提供的 Web 服务需要能够接收并解析来自HTTP POST 请求的 JSON 数据并能够返回相应 HTTP 状态码。 ### 技术支持配置回调通知地址 * 通知地址需要提供商户自己系统的真实地址，不能填写接口文档或demo上的示例地址。 * 必须是以https://或http://开头的完整全路径地址，并且确保URL中的域名和IP是外网可以访问的，不能填写localhost、127.0.0.1、192.168.x.x等本地或内网IP。 * 地址不能携带参数。 ### 处理拒付通知 使用eventCode来确定拒付处于哪个阶段。商户在成功收到异步处理结果后，响应 HttpCode 为 200，表示商户已经成功收到异步结果通知，否则，会当作通知失败处理，触发重试机制 重试 3 次，3 次后还是失败则不再继续通知，商户可通过查询接口查询拒付状态。 | eventCode | 描述 | |-----------------------------------------------------------|-------------| | NOTIFICATION\_OF\_PREDISPUTE | 未升级争议 | | REQUEST\_FOR\_INFORMATION | 调单通知 | | NOTIFICATION\_OF\_FRAUD | 欺诈提醒通知 | | NOTIFICATION\_OF\_CHARGEBACK | 拒付通知 | | CHARGEBACK\_RETURN | 拒付驳回通知 | | PREARBITRATION | 预仲裁通知 | | CHARGEBACK\_REVERSED | 拒付撤销通知 | | PREARBITRATION\_WON | 仲裁成功的结果通知 | | PREARBITRATION\_LOST | 仲裁失败的结果通知 | | DISPUTE\_DEFENSE\_PERIOD\_ENDED | 拒付抗辩时间已截止通知 | | ARBITRATION | 进入仲裁阶段通知 | --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/risk/disputesAPI/index.md' description: >- dispute API 用于自动化处理支付争议，支持主动获取调单和拒付明细、查询与上传抗辩材料等功能。适用于在争议发起后迅速响应并管理整个流程，包括提交或放弃申诉。通过该API，商家能够更高效地应对发卡行的调单要求及拒付情况。 --- # 概览 ## dispute API 为了让您快速管理发生的争议，我们提供了dispute api。我们的dispute api可让您自动执行争议处理流程，以便您可以在争议发起后立即做出回应。 * 主动获取调单明细 * 主动获取拒付明细 * 查询拒付抗辩材料 * 上传文件 * 上传拒付材料 * 删除拒付材料 * 提交材料并进行抗辩 * 放弃申诉 ## dispute API 处理流程 ### 拒付流程 调单发生时候，发卡行要求提供有关交易的更多信息。在这个阶段，您的账户中不会提取款项，建议您积极处理。 使用 Disputes API 时，您需要执行以下操作： * 处理拒付通知。使用eventCode来确定拒付处于哪个阶段。 * 检索拒付信息以了解如何为争议辩护，比如调用查询拒付抗辩材料。 * 如果您想为争议辩护，请继续执行第 3 步。 - 提交材料并进行抗辩 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/risk/listManagement/index.md description: >- 名单管理功能支持通过API维护黑名单与白名单，依据邮箱、邮箱域名、卡号、手机号及收货地址等信息维度对用户进行分类。加入黑名单将阻止相关用户的付款请求；而白名单中的用户则可绕过常规风控检查。此外，还提供新增、查询以及批量删除名单条目的接口服务。 --- # 名单管理 PingPongCheckout提供名单库管理API,按照信息维度维护名单库。 * 加入黑名单后，匹配到用户的付款将会被阻断。 * 加入白名单后，匹配到用户的付款将会被跳过风控引擎的规则扫描。 ## 自定义名单的信息维度 * Email-邮箱 * Email\_Domain-邮箱域名 * Card\_No-卡号 * Phone-手机号 * Shipping\_Address-收货地址街道 ## API列表 * 新增黑/白名单 * 分页查询黑/白名单 * 批量删除黑/白名单 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/risk/overview/index.md' description: >- 概述支付和银行业中的'争议'与'拒付'概念及处理流程。适用于商户理解如何应对客户发起的交易质疑，包括调单、拒付通知、预仲裁及正式仲裁等步骤。快速争议解决（RDR）机制亦被介绍，旨在通过自动化手段简化争议解决过程。 --- # 概览 在支付和银行业中，"Disputes"（争议）和"Chargebacks"（拒付）是两个常见的术语，它们虽然有联系，但具体含义和处理流程有所不同。 详见： * Disputes-争议 * Chargebacks-拒付 disputes（争议）一般通过一个默认的工作流解决，还有另一个过程称为快速纠纷解决(Rapid Dispute Resolution)工作流程。这个过程是独立的，不能与默认的收费工作流组合在一起。 ## 默认的工作流 ### 调单 调单(Request For Information RFI）是在持卡人不认可某笔交易时，由持卡人向银行请求更多信息的一种流程。 对于RFI，您应上传能够帮助持卡人识别该笔交易的信息，或支持您立场的证据，证明该笔交易是有效的。 ### 拒付通知 当Disputes（争议）升级到Chargebacks（拒付）时，您将会收到拒付通知，您可以在商户后台收到相关的拒付信息，如果您开通了API，您的服务端将会收到一个拒付异步通知。 与此同时，将会扣除您该笔交易的等额本金。 在您了解了所有信息后，您可以选择： * 放弃申诉 交易金额会强制退回到持卡人账户中 * 进行申诉 为此您需要在规定时间内提供相关证明材料为此次拒付进行辩护，您可以在商户后台提交申诉，或者通过API进行申诉。进入预仲裁程序。 ### 预仲裁 如果您对预仲裁结果不满意，您可以支付仲裁费用（500USD左右，该费用是在拒付金额之上收取的），再次发起申诉，争议将进入正式仲裁阶段。 ### 仲裁 正式仲裁由信用卡组织（如Visa或Mastercard）进行裁决，裁决结果具有最终约束力。 ## RDR 快速争议解决流程（Rapid Dispute Resolution，简称 RDR）是信用卡机构推出的一种简化和加速处理交易争议的机制。RDR的目的是在争议发生初期，通过自动化和预设规则快速解决争议，从而减少商户和持卡人的负担。 如果争议符合RDR的处理标准，系统会根据预设规则自动退款。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/riskManger/overview/index.md description: >- PingPongCheckout的风险管理模块提供全面的解决方案，旨在帮助商家有效识别与控制交易风险。此模块涵盖了从实时监控到智能预警等一系列服务，适用于需要加强在线支付安全性的各类电子商务平台。通过集成先进的风控技术，支持自定义规则设置，确保业务健康稳定发展。 --- # 概览 ## 风险管理 PingPongCheckout提供了一套完整的风险管理解决方案，包含多种服务，帮助您在您的业务中进行风险的管理。 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/riskManger/risk/index.md' description: >- 风控决策模块提供实时欺诈保护，无需额外部署。基于自适应机器学习系统，评估每笔付款风险并预测欺诈可能性。支持Hosted和Non-Hosted两种接入模式，提供riskDefense和SafePayGuardJs两种JS组件。根据综合因素对交易打分，判断高风险、低风险、请求3DS验证或人工审核，并通过 --- # 风控决策 PingPongCheckout提供实时欺诈保护，而且不要求额外的部署。核心是一个自适应机器学习系统，可以实时评估每笔付款的风险水平。它使用与每笔付款关联数据，并利用我们支付网络中的数据来预测付款是否有可能是欺诈性的。 我们的机器学习系统灵活且响应性强，不断学习新的客户购买模式和交易特征，并且在发现付款存在欺诈时会纳入您的反馈。 ## 如何集成风控 * Hosted接入模式： 您无需做任何额外的集成，一切包含在PingPongCheckout提供的`JS-SDK`中。 * Non-Hosted接入模式： 您需要将PingPongCheckout的提供的额外的JS组件集成到您的交易表单中。 ### 风险控制JS组件 PingPongCheckout提供的风险管理两种JS组件，可以帮助您快速集成风控功能。 | 组件 | 风控 | 3DS | 描述 | |:----------------------------------------------------------------------------|:-----------------------------------------------------------------|:---------------------------------------------------------------------|:------------------------------| | riskDefense | | | 同时集成PingPongCheckout的风控和3DS | | SafePayGuardJs | | | 如果您不想集成3DS，可以选择SafePayGuardJs | | ## 风控结果 根据持卡人的综合因素（持卡人的历史交易行为、本次交易操作的行为、3D验证是否通过、IP地址等是否命中欺诈）对交易做出打分，判断结果可能的情况为： * 高风险：交易存在欺诈，将会中断当前交易，并提示交易拒绝（如：`Transaction reject(high risk)`）。 * 低风险：交易将被放行。 * 请求3DS验证：交易可能存在风险，需要持卡人完成3DS认证。 * 人工审核：需要人工审核。 ## 人工审核 对于部分无法自动判断的交易，交易将被挂起,并进入`PROCESSING`。一般来说，审核由PingPongCheckout风控专家进行，人工审核的时间正常不会超过1个自然日。不对商户开放审核权限。对于有风控经验的商户， 可以向PingPongCheckout的商务经理申请放开审核权限，自行审核。 ### 人工审核的结果 审核结果可能的情况为：SUCCESS | 操作 | 交易状态 | 描述 | |:---------:|:-----------------------------------------------------------------:|:----------------------:| | `APPROVE` | SUCCESS | 交易将被放行，并再次通过异步通知回调交易状态 | | `REJECT` | FAILED | 交易将被拒绝，并再次通过异步通知回调交易状态 | --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/riskManger/riskDefense/index.md description: >- riskDefense组件用于集成3DS验证及风控功能，适用于提升支付安全性。初始化时需加载JS并配置环境参数如env、accId等。通过获取generatedData来准备必要的风控信息，并在下单支付时传递browserInfo以完成交易安全检查。 --- # 3DS riskDefense组件集成指南 ## 初始化 ### load JS ::: code-tabs @tab URL ``` https://pay-cdn.pingpongx.com/production-fra/static/riskDefense/pingpongRiskDefense.min.js ``` ::: ### initialize JS ::: danger 沙箱联调请填入`env`=`SANDBOX`, 生产环境请填入`env`=`PRODUCTION`。 ::: ::: code-tabs @tab JavaScript ```js const pp = new PingPongRiskDefense({ env: 'SANDBOX'|'PRODUCTION', accId: string, clientId: string, requestId: string, merchantUserId: string, merchantTransactionId: string }) ``` ::: | 属性 | 类型 | 必填 | 描述 | |-----------------------|--------|-----|---------------------------------------| | env | string | M | 当前调用服务环境SANDBOXPRODUCTION | | accId | string | M | PingPong店铺号 | | requestId | string | C | 端到端接入时候传送 | | merchantUserId | string | C | 持卡人在商户网站的会员标识 | | merchantTransactionId | string | C | 收银台应传 `merchantTransactionId` | ## 获取3DS 和风控参数 ### 获取generatedData 在向PingPongCheckout发起支付请求前, 执行该步骤获取`generatedData`, 并在支付时将其传递给支付接口。 ::: code-tabs @tab JavaScript ```js const generatedData = pp.getGeneratedData() ``` ::: 返回的generatedData结构如下： ::: code-tabs @tab JavaScript ```js { browserInfo: { acceptHeader: string, colorDepth: number, language: string, screenHeight: number screenWidth: number timeZoneOffset: number userAgent: string javaEnabled: boolean javaScriptEnabled: boolean }, jsGeneratedData: { fingerPrint: string, forterSiteId: string, forterTokenCookie: string | null } } ``` ::: ## 下单并支付接口报文组装 ### 填充browserInfo 请求PingPongCheckout 下单并支付接口。在参数 `browserInfo`中传送`generatedData`里面获取的`broswerInfo`参数。 | 属性 | 类型 | 描述 | |-------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------| | language | string | 购物者浏览器的navigator.language值（如IETF BCP 47中所定义）。 | | screenWidth | int | 持卡人终端屏幕宽度（单位：像素） | | javaEnabled | bool | 持卡人终端是否能够执行Java。 | | javaScriptEnabled | bool | 指示购物者的浏览器是否能够执行JavaScript。如果字段不存在，则假定为默认的`true`值。 | | acceptHeader | string | http响应头信息， 示例值: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, image/apng, \*;q=0.8 | | colorDepth | string | | | screenHeight | int | 持卡人终端屏幕高度（单位：像素） | | jetLag | int | UTC时间和持卡人浏览器本地时间之间的时差，以分钟为单位。 | | userAgent | string | 浏览器用户代理信息 示例值：Mozilla/5.0 (Macintosh; Intel Mac OS X 10\_14\_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.121 Safari/537.36 | ### jsGeneratedData 填充 | 属性 | 类型 | 描述 | |-------------------|--------|------| | fingerPrint | string | 设备指纹 | | forterSiteId | string | 站点标识 | | forterTokenCookie | string | | ### 请求支付 完成上述额外的参数填充之后，还需要填充下单并支付接口必要的业务参数。成功发起支付之后，响应报文中会携带参数 `threeDUnionParams` 请求报文示例： ::: code-tabs @tab JSON ```json { "accId":"2090020315464510103001", "clientId":"2090020315464510103", "signType":"SHA256", "sign":"{{Sign}}", "version":"1.0", "bizContent":{ "captureDelayHours":"0", "amount":"3", "currency":"USD", "merchantTransactionId":"{{merchantTransactionId}}", "payResultUrl":"https://test-acquirerpay.pingpongx.com/qa/result.html", "payCancelUrl":"https://test-acquirerpay.pingpongx.com/qa/result.html", "notificationUrl":"https://test-acquirerpay.pingpongx.com/qa/result.html", "language":"en", "requestId":"{{requestId}}", "tradeCountry":"US", "shopperIP":"222.126.52.23", "paymentMethod":{ "type":"scheme", "cardInfo":{ "expireMonth":"12", "expireYear":"2024", "holderFirstName":"w", "holderLastName":"w", "number":"5200000000001096", "cvv":"103" } }, "customer":{ "firstName":"Jamesbb", "lastName":"LeBronbb", "email":"test@pingpongx.com", "phone":"9157030054" }, "goods":[ { "name":"商品名称mepsking1", "description":"商品描述", "sku":"产品SKU111", "unitPrice":"1000", "number":"1", "imgUrl":"https://xiu.mepsking.top/material/1/16606169805015585.png", "virtualProduct":"Y" } ], "shippingAddress":{ "firstName":"Jamesbb", "lastName":"LeBronbb", "phone":"9157030054", "email":"3ds@pingpongx.com", "street":"3888 Austin Secret Lane", "postcode":"84723", "city":"Circleville", "state":"UT", "country":"US" }, "billingAddress":{ "firstName":"Jamesbb", "lastName":"LeBronbb", "phone":"9157030054", "email":"3ds@pingpongx.com", "street":"3888 Austin Secret Lane", "postcode":"84723", "city":"Circleville", "state":"UT", "country":"US" }, "browserInfo":{ "acceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", "colorDepth":"24", "jetLag":"480", "language":"nl-NL", "javaEnabled":"true", "screenHeight":"723", "screenWidth":"1536", "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.121 Safari/537.36", "windowSize":"05" }, "device":{ "orderTerminal":"02" } } } ``` ::: ## 是否需要3DS验证 ### threeDContinue * `threeDUnionParams.threeDContinue`为`true`时候需要触发3d验证。 * `threeDUnionParams.threeDContinue`为`false`时候将会跳转到商户的支付结果页`shopperResultUrl`。 ## 3DS挑战页 ### 使用JS的trigger方法触发3DS挑战页 将支付接口返回的 `threeDUnionParams` 作为入参调用 `trigger` 函数，风控JS会引导浏览器到3D挑战页，持卡人需要正确的完成3D验证，才能成功交易 ::: code-tabs @tab JavaScript ```js pp.trigger(threeDUnionParams) ``` ::: ### 使用PingPongChekout提供的中间页触发3DS挑战页 从下单并支付接口的响应报文中获取`threeDUnionParams.threeDRedirectUrl`参数，通过GET方式跳转，随后PingPongChekout提供的中间页将会自动重定向到3DS挑战页。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/riskManger/safePayGuardJs/index.md description: >- SafePayGuardJs是支付过程中的风险控制插件，用于预防欺诈、保障资金安全及优化用户体验。适用于需要加强在线交易安全性的场景。初始化时需设定环境参数（SANDBOX或PRODUCTION），并调用getGeneratedData方法获取设备指纹等风控信息，以增强支付请求的安全性。 --- # safePayGuardJs **SafePayGuardJs**是一个用于支付过程中的风险控制插件，包括预防欺诈行为、保护资金安全，提升用户体验。 ## 安装 ```javascript ``` ## 初始化 ### 定义初始化参数 ::: danger 沙箱联调请填入`env`=`SANDBOX`, 生产环境请填入`env`=`PRODUCTION`。 ::: ```javascript const options = { env: 'DEV', // 'SANDBOX'|'PRODUCTION' accId: accId, clientId: clientId, requestId: requestId, merchantUserId: merchantUserId, } ``` ### 初始化 ```javascript SafePayGuardJs.init(options) ``` ## 获取generatedData 在完成初始化后，该插件会自行收集设备指纹和风控所需参数，真正发起支付请求前, 你只需要调用插件提供的 `getGeneratedData` 方法进行获取（以下均称其为 generatedData），并在后续支付中传入。 示例： ```javascript const generatedData = SafePayGuardJs.getGeneratedData() // generatedData: { fingerPrint: string; forterSiteId: string; forterTokenCookie: string | null; riskExtendInfos: [{ channelCode: "1xxxxx0x", metadata: "xxx5xxxd5dxxxxxeaxxxxxxxdxfxx" }] } ``` --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/riskManger/SecureShieldJs/index.md description: >- SecureShieldJs是用于在线支付的安全插件，旨在提高信用卡交易安全性并降低欺诈风险。适用于需要增强支付安全性的网站。支持通过初始化参数配置环境（SANDBOX/PRODUCTION），并提供3DS验证功能，默认开启但可关闭。关键方法包括初始化、触发3DS验证及获取生成的数据，其中`trig --- # SecureShieldJs组件 **SecureShieldJs** 一个用于在线安全支付的插件，旨在提高信用卡交易的安全性，降低欺诈交易的风险。 ## 安装 ::: code-tabs @tab JavaScript ```javascript // window.SecureShieldJs ``` ::: ## 初始化 ### 定义初始化参数 ::: danger 沙箱联调请填入`env`=`SANDBOX`, 生产环境请填入`env`=`PRODUCTION`。 ::: ::: code-tabs @tab JavaScript ```javascript const options = { env: 'SANDBOX', // 'SANDBOX'|'PRODUCTION' accId: accId, clientId: clientId, requestId: requestId, merchantUserId: merchantUserId, merchantTransactionId: merchantTransactionId, } ``` ::: * `requestId`为S2S对接时传入的，pingpong收银台应传`merchantTransactionId`。 ### 完成初始化 ::: code-tabs @tab JavaScript ```javascript const secureShieldJs = SecureShieldJs.init(options, [avoidThreeDs=false]) ``` ::: ::: warning 你可以在 init 时传入第二个参数true来关闭 3Ds功能，关闭后，插件将不进行 3D 信息的采集, 只保留 browser 信息的采集。为保证支付安全性, 需要你自行实现 3D 逻辑。 ::: ## 3DS init 以下方法仅在开启 3Ds功能时生效(默认开启) 在完成插件的初始化后，现在你可以在合适的时机调用 `triggerThreeDsInit`方法来进行 3DS init。 ::: code-tabs @tab JavaScript ```javascript secureShieldJs.triggerThreeDsInit(params) ``` ::: 何时调用？ ### 场景一 为了收集完整正确的卡号，你可以在 卡号 和 卡有效期 input 失焦后调用，插件将自行进行3DS init操作 此时，调用 triggerThreeDsInit 方法需传入 cardInfo 相关参数： | 属性 | 类型 | 必填 | 描述 | |------------------------|------------|-----|------------| | params.cardNumber | String(12) | C | 国际信用卡卡号 | | params.cardExpireMonth | String(32) | C | 有效期-月，2位数字 | | params.cardExpireYear | String(64) | C | 有效期-年，4位数字 | 示例： ::: code-tabs @tab JavaScript ```javascript const cardNumberElement = document.querySelector('#cardNumber'); const expireDateElement = document.querySelector('#expireDate'); const triggerThreeDs = { threeDsParams: { cardNumber: cardNumberElement.value, expireDate: expireDateElement.value }, // 代理函数, 在 3Ds init 前对参数进行校验 proxyThreeDsParams() { const proxyHandle = { get: (target, key) => { // 简单校验: 卡号位数 <= 15 时返回空字符 if (key === 'cardNumber') { return target[key].length <= 15 ? '' : target[key].replace(/\s+/g, '') } // 卡号有效期参数处理: 不满足条件返回空字符, 反之为处理好的参数格式 if (key === 'expireDate') { const expireDate = target[key].replace(/\s+/g, '') if (expireDate.length === 5 && expireDate.indexOf('/') > -1) { const [cardExpireMonth, cardExpireYear] = expireDate.split('/') return { cardExpireMonth, cardExpireYear: `20${cardExpireYear}` } } return '' } return ''; } } return new Proxy(this.threeDsParams, proxyHandle) }, getThreeDsInitParams(threeDsParams) { const { cardNumber, expireDate } = threeDsParams if (!cardNumber) return null; if (typeof expireDate === 'string') return null; const { cardExpireMonth, cardExpireYear } = expireDate return { cardNumber, cardExpireMonth, cardExpireYear } } } const _proxyThreeDsParams = triggerThreeDs.proxyThreeDsParams() const handleBlur = (name) => { const { value } = event.target triggerThreeDs.threeDsParams[name] = value const params = triggerThreeDs.getThreeDsInitParams(_proxyThreeDsParams) // 当校验不通过时, 你不需要调用 triggerThreeDsInit 方法 params && secureShieldJs.triggerThreeDsInit(params).then((data) => {}) } cardNumberElement.addEventListener('blur', handleBlur.bind(this, 'cardNumber'), true) expireDateElement.addEventListener('blur', handleBlur.bind(this, 'expireDate'), true) ``` ::: 以上为原生 Js 实现方式，如果你使用 Vue，可以使用 watchEffect 对卡号、卡有效期进行监听，校验、整合参数完成后调用 3Ds init 方法即可； ### 场景二 当你的支付场景中存在绑卡的场景时，你可以直接传入cardToken来进行 3Ds init | 属性 | 类型 | 必填 | 描述 | |------------------|------------|-----|----------------| | params.cardToken | String(32) | C | 可以用来替代cardInfo | 示例： ::: code-tabs @tab JavaScript ```javascript // 选择某个已绑定的卡时: document.querySelector('selectId').addEventListener('change', (event) => { const { value: card } = event.target const params = { cardToken: card.cardToken } secureShieldJs.triggerThreeDsInit(params) }) ``` ::: ## 获取generatedData 在完成 3Ds init 后，真正发起支付请求前, 需要将 3Ds 参数 和 browserInfo （以下均称其为 generatedData）传递给支付接口。 关闭 3Ds 时，`getGeneratedData` 方法只会返回 browserInfo。 ### 如何获取 * 通过 triggerThreeDsInit： 在进行 3Ds init 时调用了 triggerThreeDsInit，该方法将返回一个Promise，你可以在 Promise Fulfilled 时获取 generatedData。 示例： ::: code-tabs @tab JavaScript ```javascript const threeDsPromise = secureShieldJs.triggerThreeDsInit(params) threeDsPromise.then(jsGeneratedData => { // 可以赋值给外部变量，支付时传递 this.myGeneratedData = jsGeneratedData }) ``` ::: * 调用插件提供的 getGeneratedData 方法（推荐） 示例： ::: code-tabs @tab JavaScript ```javascript const generatedData = secureShieldJs.getGeneratedData() // generatedData: { browserInfo: { acceptHeader: string colorDepth: number language: string screenHeight: number screenWidth: number jetLag: number userAgent: string javaEnabled: boolean javaScriptEnabled: boolean } jsGeneratedData: { channel: string version: string correlationId: string threeDInitTransId: string threeDSecureReferenceId: string } } ``` ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/saas/Shopify/Afterpay/index.md description: >- Afterpay 是一种适用于 Shopify 平台的分期付款解决方案，支持以美元结算。商户需首先确认店铺货币为 USD，然后通过指定链接安装 Afterpay 应用。安装成功后，该支付选项将自动出现在 Shopify 后台的 Payments 部分及结账页面上，方便消费者选择使用。 --- # Afterpay ## Afterpay 支付方式安装步骤 ### Step 1. 币种检查 检查安装条件，币种必须是 **USD**。 币种检查路径：【**Store details**】-->【**store currency**】-->【**USD**】 ### Step 2. 搜索 APP 点击此链接 (
异步通知 Note over Client, Bank: 🎯 Hosted收银台流程完成 ``` :::: steps 1. 步骤 1 客户端提交订单给商户服务端处理 2. 步骤 2 商户服务端请求PingPongCheckout服务端，提交订单信息和其他必要参数 3. 步骤 3 PingPongCheckout服务端响应收银台构建要素 4. 步骤 4 客户端初始化收银台 * Hosted-JS-SDK:初始化SDK * Hosted-Redirect：跳转到PaymentUrl 5. 步骤 5 收银台与PingPongCheckout服务端交互，成功之后将会渲染PingPongCheckout收银台 6. 步骤 6 买家填写卡号和cvv等支付信息，提交支付信息 7. 步骤 7 持卡人确认支付 8. 步骤 8 如果是3D交易，还需要3D验证，否则直接展示交易结果 9. 步骤 9 如何获取异步通知报文详见[异步通知](/pages/d4421e/) 10. 步骤 10 收到异步通知需要响应`http code200`给PingPongCheckout :::: ## 订单状态处理 ::: note 建议 payResultUrl 依据异步通知/订单查询返回的 status 进行处理, 订单状态流程图 ::: ## API清单 ## 服务端接入 持卡人客户端在请求商户服务端下单之后，需要提交必要参数给PingPongCheckout服务端进行下单。 详见 下单接口 ## 客户端接入 服务端请求下单接口响应成功后，可以在客户端渲染Hosted接入模式的收银台页面。 ## 3DS 收银台模式下，商户可以在调用下单接口的时候，通过上送3DS参数executeThreeD来控制是强制进行3DS校验，还是交由PingPongCheckOut的风控决策决定是否要进行3DS校验。 详见 3DS集成指南 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/services/checkout/hosted/sdk/index.md description: >- 通过JS-SDK嵌入PingPongCheckout收银台，适用于需要在网页中集成支付功能的场景。支持自定义主题色和多语言配置。主要参数包括innerJsUrl和token，用于加载和初始化SDK。创建支付时需传入订单对象，并设置mode为sandbox或production。收银台支持48小时内重 --- # Hosted-通过JS-SDK嵌入收银台 ## 渲染收银台 从下单中取到下列关键响应参数 | 参数名称 | 描述 | |:-----------|:--------------| | innerJsUrl | JS-SDK的加载地址 | | token | 初始化SDK时，需要的参数 | ### 引入JS-SDK PingPongCheckout 提供两种方式来引入SDK * 提前引入JS,复制以下代码，通过CDN地址引入PingPongCheckout JS-SDK ```javascript ``` * 在下单完成之后，使用innerJsUrl字段的值引入 #### SDK-config示意图 ::: note 在上图中，您可以对字体样式、间距等进行更细致的配置。然而，如果您只想更改主题色，请使用以下参数： * themeColor：收银台的主题色，将应用于加载动画、字体、按钮、表单聚焦后边框颜色等。 * themeLightColor：收银台的浅色主题色，将应用于部分阴影、浅背景色等。 如果您不传递这些参数，则默认使用 Pingpong 主题色。 ::: #### JS-SDK收银台语种支持 ::: note 在SDK`lang`参数中配置，默认英语 更多语言详见Locale ::: #### 初始化SDK示例代码 客户端点击下单按钮，提交订单之后，从服务端获取订单相关参数（order 对象），在初始化PingPongCheckout JS-SDK之后，传入order对象 到createPayment方法中，开始和PingPongCheckout交互，成功之后将会渲染出PingPongCheckout收银台 ```javascript window.addEventListener('load', loadHandle); function loadHandle() { const conf = { mode: 'sandbox', //sandbox/production (必填参数) lang: 'en', // 语言，不传默认英语 - de德语 en英语 es西班牙语 fr法语 it意大利语 ru俄语 zh中文 jp日语 root: '#payment-wrap', // PingPong收银台在哪个元素上渲染 须为id (必填) manul: false, // 手动模式。 即：支付按钮需要自己渲染，开启后可使用client.actionPayment()方法调用支付 showPrice: true, // 是否展示价格 bill: true, // 是否显示bill located: true, // 是否显示located(默认为true) menu: true, //是否显示支付方式按钮 base: { width: '100%', // 收银台宽度 height: '800px', // 收银台高度 backgroundColor: '#fff', // 收银台整体背景色 // 顶部价格及币种 priceBgColor: '#fff', // 顶部价格区域背景色 priceFontColor: '#1fa0e8', // 顶部价格字体颜色 priceFontSize: '32px', // 顶部价格字体大小 priceMB: '10px', // 顶部价格区域距底部间距 // 引导标题: “How would you like to pay” showHeaderLabel: true, // 是否显示引导标题 headerMB: '24px', // 引导标题距底部间距 headerSize: '20px', // 引导标题字体大小 headerColor: 'rgba(0, 0, 0, 0.85)', // 引导标题字体颜色 headerfontWeight: 700, // 引导标题加粗 // 支付方式 payMethodsWidth: '240px', // 支付方式按钮宽度 payMethodsHeight: '48px', // 支付方式按钮高度 payMethodsColor: 'rgba(0, 0, 0, 0.85)', // 支付方式按钮字体颜色 payMethodsActiveColor: '#1fa0e8', // 支付方式按钮点击后字体颜色 payMethodsFontsize: '14px', // 支付方式按钮字体大小 payMethodsActiveBorderColor: '#1fa0e8', // 支付方式按钮点击后边框颜色 payMethodsActiveBorderShadow: '0 2px 8px 0 rgb(31 160 232 / 20%)', // 支付方式按钮点击后阴影 showIcons: true, // 是否显示卡图标 showHeaderAmount: true, // 是否显示头部支付金额 // 表单相关 formItemMargin: '16px', // 表单距底部间距 formItemBorderColor: 'rgba(0, 0, 0, 0.08)', // 表单边框颜色 formItemFocusColor: '#1fa0e8', // 表单聚焦时提示文案和边框颜色 // 支付按钮 btnSize: '100%', // 按钮宽度百分比或者px btnColor: '#fff', // 按钮字体颜色 btnFontSize: '14px', // 按钮字体大小 btnMarginTop: '10px', // button 距顶部距离 btnMarginBottom: "24px", // button 距底部距离 btnBackgroundColor: '#1fa0e8', // 按钮背景色 btnBorderRadius: '8px', // 按钮圆角 btnBorderColor: '#1fa0e8', // 可单独配置btn边框颜色覆盖btnBorder中设置的颜色 } } let client = new ppPay(conf); // 在这里传入 从接口中获取到的token let token ="EU:Dt10Deb05qeI0HFWg0DU1NPcLE-dxCDiU40wyKBxHw1w1RDULBtXXtI2dsgSX8L7"; //使用此方法将会创建收银台 client.createPayment(token); // manul 模式 使用此方法将不会出现支付按钮，支付时机将会取决于持卡人的调用 // client.actionPayment(callback) } ``` ::: danger 1. 参数mode必须正确填写，开发测试填sandbox，上线之后使用production，上线前请检查参数mode； 2. 收银台不支持禁用cookies。 ::: ### 完成付款 正确如上设置之后，应正常渲染出收银台，正确输入卡号，过期时间和CVV信息，即可完成交易。 沙箱模式下的收银台如下所示 ## 重新支付 收银台若未支付成功，可以手动打开URL再次发起支付，一个收银台URL有效是时长为48小时 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/start/acceptance/index.md' description: >- 验收测试场景文档详细列出了收单验收的关键注意事项，包括沙箱环境特性、幂等性处理要求及信用卡3D验证测试方法。适用于准备上线前的最终测试阶段，确保支付流程安全可靠。 --- # 验收标准 ## 收单验收注意事项 ::: danger 注意 1. 沙箱环境不会校验参数是否已经传送。 2. 请务必完成对于支付场景验收后再进行线上交易。 3. 确认对于订单幂等特性（失败非终态/失败终态）已了解，并且对不同幂等下 processing/failed 的订单有不同的处理方式！ 4. S2S模式下，需要根据对应的业务场景接入对应的风控插件。 5. 信用卡支付需要完成 3D 场景测试，测试参数为订单金额设置 3USD，email为 3ds@pingpongx.com，测试信用卡信息可以咨询对应技术支持人员。\ ::: ## 获取测试报告填写模板 获取PingPongCheckout 商户接入技术测试报告模板 ## 具体验收场景 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/start/limitSandbox/index.md description: >- 沙箱环境为开发者提供了一个安全低门槛的测试平台，支持大部分核心链路和对接逻辑。但请注意，沙箱非100%保真生产环境，存在功能限制，如部分支付方式无法完全测试或仅能模拟成功状态。此外，沙箱与生产环境数据隔离，切勿混淆使用。 --- # 沙箱约束限制说明 ## 沙箱约束限制说明 沙箱环境是 PingPong 为开发者提供的安全低门槛的测试环境。沙箱为开放的产品提供 有限功能范围 的支持，可以覆盖产品的绝大部分核心链路和对接逻辑，便于开发者开发和调试。所以在使用过程中，会存在一些功能限制约束。 * 非100%保真：需意识到沙箱环境并非 100% 与生产环境一致，接口的实际响应逻辑请以生产环境为准，沙箱环境开发调试完成后，仍然需要在生产环境进行测试验收。 * 数据隔离，勿混淆：沙箱环境拥有完全独立的数据体系，沙箱环境下返回的数据（例如订单号）仅限于沙箱环境使用，开发者不可将沙箱环境返回的数据与生产环境中的数据混淆。 * 功能有限：不是所有支付方式都能测试成功场景，比如 Mybank，NeverPay；还有部分支付方式mock调用会跳转渠道挡板页面，比如 Trustly，Bancontact，Boost等，可以模拟成功状态。 ::: note 备注 沙箱模拟环境用于开发者进行接口开发、调试，为保障沙箱环境服务稳定性，请您不要随意进行压力测试及安全攻击。如需，请先联系PP工作人员进行报备申请，否则PP运维及安全团队有权禁用异常应用或IP的请求来保障服务稳定性。 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/start/registerSandbox/index.md description: >- 沙箱准入说明提供了进入PingPong支付系统测试环境的步骤。适用于开发人员在正式上线前进行功能测试和集成调试。流程包括通过指定网站注册账号，选择商户类型并提交信息，以及获取必要的测试参数如accId、clientId和salt。确保所有准备工作完成后，联系技术支持以配置环境。 --- # 沙箱准入说明 ## 沙箱准入说明 1. 网站地址：`https://sandbox-checkout.pingpongx.com/`，未注册过需要点击右上角注册按钮进入注册页面，如下图： 2. 类型选择独立商户或者机构都可以，填写完信息之后，点击"注册"即可。 ::: note 提示 如果获取不到验证码，可以检查一下手机号是否准确，或者可以联系技术支持核实。 ::: 3. 注册完成之后需要提供登录账号给到pp技术支持，技术支持同学配置完成之后，会提供测试所需的 accId，clientId（去除accId后三位），salt参数。至此，前期沙箱环境的准备工作已完成。 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/start/step/index.md' description: >- 准备工作文档介绍了使用PingPongCheckout前的必要步骤，包括获取沙箱账户、确定对接方案、API授权配置及生产环境验证。覆盖了从测试到正式上线的全流程，适用于希望集成支付解决方案的开发者。 --- # 准备工作 在开始开发使用PingPongCheckout产品和解决方案之前，请先熟悉我们的最新文档，包括开发人员指南、API参考、代码示例等。对接过程都是在对接群内进行沟通。 ### 沙箱账户开通 开始对接之前，需要先获取一个沙箱账户用于接口测试，为了方便对接，我们会提供一个公用的沙箱账户进行测试。当然，您这边也可以选择自己登录到PingPong的 沙箱商户后台 注册获取一个新的沙箱账户。 ::: note 备注 如果是商户自己注册的沙箱账户，需要提供账户信息给到PingPong的技术支持做一些配置之后才可以使用。 ::: ### 确定对接方案 在对接之前需要先确定您的对接方案，我们提供了多种方式集成我们的API接口。这些范围从使用预构建的集成，到构建您的收银台界面以完全控制您的结账体验。我们建议您根据您的需求和能力做出选择。比如说Hosted模式，提供了JS SDK渲染收银台和托管付款界面两种模式，如果是Non-Hosted模式则需要先提供PCI证书，并且要求您这边具备独立开发收银台的能力。 ### API授权和配置 沙箱测试完成之后，需要联系PingPong的技术支持进行API授权和配置，在未完成授权之前，生产账号都是不可用的。API授权完成之后，可以登录到商户后台获取accId和秘钥，并替换掉所有沙箱环境的配置。 ### 生产环境对接 在沙箱环境测试完成之后将进入网站资料审查和进入生产前必要的账户配置阶段，通过之后，会发放生产环境参数。 获取到生产环境参数之后，请完成以下事项: ### 生产环境验证 1. 发送截图和商品链接，并通知技术支持，将由客户/技术支持对该商品链接发起真实交易测试，以验证结果； 2. 完成真实交易测试之后，需要商户发起退款，以便于验证退款流程； 3. 完成以上流程，网站对接结束，支付通道正式上线，支付可用。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/accId/index.md description: >- accId是PingPong商户店铺号，作为商户在PingPongCheckout平台上的唯一标识。完成PingPong商户注册后可获取该标识，已注册用户可登录商户后台查看。 --- # accId ## accId的含义 accId是PingPong 商户店铺号,商户店铺在PingPongCheckout的唯一标识 ## accId的获取 需要完成pingPong的商户注册之后才可以获取，可以参考注册流程。 已完成注册的可以直接登陆到商户后台进行获取，获取位置见如下截图： --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/Authorization/index.md description: >- Authorization（预授权）是信用卡支付处理的第一步，用于验证信用卡有效性并暂时冻结账户中一定金额。适用于电子商务、应用内及销售点支付场景。通过API调用实现，关键步骤包括交易发起、发送授权请求至发卡行、处理请求和返回授权响应。预授权有效期通常为7天，过期自动VOID。 --- # Authorization 国际信用卡支付中的`Authorization`（预授权）是一个非常重要的环节，它是信用卡交易处理过程中的第一步。发卡机构(如 Visa 或 Mastercard)验证支付细节并保留资金以便以后获取的过程。 在电子商务、应用内支付和销售点支付中，授权是通过对支付网关进行API调用来实现的。网关和支付处理器随后进行必要的验证和风险检查，并请求相应的卡网络从发行方授权支付到收单方。 当支付已经被授权但尚未被捕获时，商家也可以因某些原因（如高风险的欺诈）决定取消它。 ::: danger 注意 授权只在有限的时间(一般为7天)内有效。如果授权的支付没有被捕获或取消，一旦错过预定的截止日期，它将过期，并且将会自动`VOID`。 ::: ## 预授权的主要目的： * * 验证信用卡：确保信用卡是有效的并且没有被报失或盗。 * 保留资金：暂时冻结账户中的一定金额，以确保未来的支付。 ## 授权过程的主要步骤包括： 1. **交易发起**： * 当持卡人在商家处进行信用卡支付时，商家会收集持卡人的信用卡信息，包括卡号、有效期、CVV等。 2. **发送授权请求**： * 收集到的信用卡信息将通过商家的支付网关发送到支付处理网络。具体表现为请求下单接口或者下单并支付时候`captureDelayHours`的取值： |captureDelayHours| 备注 | |-----------------|----------------------------------| |`0`| 下单之后立即自动capture，无需手动调用CAPTURE-预授权权确认 | |`1`| 手动capture，成功之后还需要调用下CAPTURE-预授权权确认,本地支付不支持 | * 支付处理网络将请求转发给发卡银行进行验证。 3. **发卡行处理请求**： * 发卡银行会检查卡片的有效性、账户余额或信用额度、以及交易的合法性。 * 如果一切正常，发卡银行会批准这笔交易，并返回一个授权码；如果有问题，则会拒绝授权。 4. **授权响应**： * 授权的结果（批准或拒绝）将被发送回支付网关，然后传递给商家。 * 如果授权被批准，商家可以继续进行交易。 ## API列表 * CAPTURE-预授权权确认 * VOID-预授权撤销 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/Capture/index.md description: >- Capture（捕获）指将已授权的资金从购物者账户正式转移到商家账户。默认情况下，支付授权后立即自动完成捕获。许多支付方式支持分开的授权和捕获，允许设置捕获延时、手动捕获或部分捕获，并可取消授权。捕获与取消、退款一起归类为修改支付状态的操作。 --- # Capture Capture（捕获）是指将预留的资金从购物者转移到商家的行为,商家从客户的银行账户中正式扣除（即收取）这笔已授权资金。 默认情况下，支付在授权后立即自动捕获。 许多支付方式支持分开的授权和捕获。这意味着你可以设置捕获延时；手动捕获支付（使用API调用）,执行部分捕获；或取消授权。 捕获、取消和退款一起被称为修改支付，因为它们修改了已授权支付请求的状态。 ## API列表 * CAPTURE-预授权权确认 * VOID-预授权撤销 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/cardHolder/index.md description: >- 持卡人指使用银行发行的卡进行无现金支付的购物者。该术语适用于描述在各类支付场景中，通过银行卡完成交易的个人或企业用户。理解此概念有助于更好地设计和优化支付流程及相关服务。 --- # 持卡人 ## CardHolder 指的是使用银行发行的卡进行无现金支付的购物者 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/CardNetworks/index.md description: >- 支付网络定义了卡片发行与交易处理的标准，确保发卡方和收单方在同一系统内运作。全球主要的支付网络如Visa、Mastercard、American Express及银联等，不仅提供必要的技术支持，还决定了包括互换费在内的各种交易成本。 --- # Card networks (or Card schemes) ## 支付网络 支付网络设定规则并提供发行卡片和处理卡片支付的基础设施。要完成支付，发卡方和收单方必须是同一网络的成员。一些知名的卡网络包括Visa、Mastercard、American Express和银联。 卡组织收取处理支付的费用，并且还规定了互换费的价值，这取决于每笔特定支付的多个因素。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/CardNumber/index.md description: >- CardNumber（PAN）是指支付卡上的唯一号码，用于识别每张卡并在交易中引用。前六位或八位数字构成银行识别号（BIN），帮助识别发卡机构。卡片还可能包含安全码以支持非现场交易的安全性。 --- # CardNumber（PAN） ## 支付卡 每张支付卡（无论是借记卡、信用卡、礼品卡还是类似的卡）都有一个独特的号码与之关联。这个号码通常印在卡上，用于唯一识别这张卡，并在每笔交易中引用。 整个卡号被称为主账号（Primary Account Number，简称PAN），它的前六位或八位数字也被称为银行识别号（Bank Identification Number，简称BIN）。 此外，卡片可能包含一个卡安全码，该安全码与卡号一起可以用于非现场交易（即卡不在场的交易）。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/CardOnFile/index.md description: >- CardOnFile (CoF) 是一种将卡片详情存储以简化回头客结账过程的技术，适用于一键支付、按使用付费服务或不固定时间表的定期支付。若商家符合PCI 1级/2级合规性，则可自行存储卡片信息。 --- # CardOnFile (CoF) ## CoF 当卡片详情被存储以简化回头客的结账过程时，这可以用于一键支付、按使用付费服务或任何不遵循固定时间表的定期支付。 定期发生在固定时间表上的支付被称为订阅。 如果商家符合PCI的1级/2级合规性，他们可以自行存储卡片详情。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/Cards/index.md description: >- Cards是由银行发行的塑料卡，用于实现无现金支付。包括借记卡、信用卡和预付卡，通过卡号、安全码等信息进行交易验证。卡片广泛应用于销售点、电子商务网站及移动应用内支付，并可与电子钱包关联，支持取现和线上支付。 --- # Cards ## Cards 由购物者银行发行的塑料卡，用于在销售点、通过电子商务网站或在移动应用程序内实现无现金支付。卡片可能是借记卡、信用卡或预付卡，通常由卡组织操作。有时卡片可能与电子钱包或其他本地支付方式关联，但最常见的用途是取现或进行无现金支付。 典型的卡片包含一个卡号，用于唯一识别一张卡。它还包含一个安全码，与其他信息（卡片到期日期和持卡人姓名）结合使用，用于验证非现场支付（例如，在电子商务网站或移动应用程序内支付商品或服务时）。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/chargebacks/index.md description: >- Chargebacks（拒付）是发卡行在争议无法通过初步沟通解决后，将交易金额从商户账户中强制扣除并退还给持卡人的正式交易逆转机制。适用于处理持卡人对交易的异议，涉及争议升级、拒付通知、商户回应和仲裁等步骤。拒付时效为持卡人发起调单拒付180天，商户回复90天。 --- # Chargebacks Chargebacks(拒付)是指在争议无法通过初步沟通解决后，发卡行将交易金额从商户账户中强制扣除，并退还给持卡人。拒付是一种正式的交易逆转机制。 ## Chargebacks的类型 ## Chargebacks的发生流程 * 争议升级：如果争议未能解决，争议升级为拒付。 * 拒付通知：发卡行通过Visa或其他支付网络向收单行发出拒付通知。 * 收单行通知商户：收单行接到拒付通知后，会通知商户，并要求商户提供相关证据以回应拒付。 * 商户回应：商户需要在规定的时间内提供证据，证明交易的合法性和有效性。 * 仲裁：如果商户提供的证据足够强有力，拒付可能会被驳回；否则，拒付成立，商户需承担退款责任。如果双方无法达成一致，争议可能会进入仲裁程序，由支付网络做出最终决定。 ## Chargebacks的步骤 ## Disputes和Chargebacks主要区别 * 阶段： * 争议是拒付的前期阶段，持卡人对交易提出异议。 * 拒付是争议未解决后，发卡行采取的进一步行动，正式逆转交易。 * 处理流程： * 争议处理通常涉及初步的沟通和协商，试图在不进行正式逆转的情况下解决问题。 * 拒付处理更加正式，涉及交易金额的逆转，并且需要遵循支付网络的规定和流程。 * 影响： * 争议阶段的处理相对灵活，可以通过沟通解决，影响较小。 * 拒付对商户的影响较大，不仅涉及资金的逆转，还可能影响商户的信誉和未来的交易处理。 ## 拒付时效 * 持卡人发起调单拒付时效：180天 * 商户收到调单拒付的回复失效：90天 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/clientId/index.md description: >- clientId是PingPong商户在PingPongCheckout的唯一标识。完成PingPong商户注册后，可通过登录商户后台并访问账户中心获取该ID，用于识别和管理商户信息。 --- # clientId ## clientId含义 PingPong 商户商户号,商户在PingPongCheckout的唯一标识 ## clientId如何获取？ 需要完成pingPong的商户注册之后才可以获取，可以参考注册流程。 已完成注册的可以直接登陆到商户后台，点击右上角的"账户中心"即可获取，如下图所示： --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/disputes/index.md description: >- 争议是指持卡人对某笔交易提出异议的过程，涉及持卡人、发卡行、收单行和商户之间的沟通与协商。争议处理阶段相对灵活，通过初步沟通解决异议；若未能解决，则可能升级为拒付，导致交易金额逆转并对商户产生较大影响。 --- # Disputes 争议是指持卡人对某笔交易提出异议，认为该交易存在问题。 ## Disputes 流程 * 持卡人提出争议：持卡人联系发卡行，说明对某笔交易的异议。 * 发卡行审核：发卡行审核持卡人的争议请求，决定是否需要进一步处理。 * 与商户沟通：发卡行可能会联系收单行和商户，要求提供交易的相关证据和信息。 * 解决或升级：如果争议能够通过沟通和协商解决，则争议结束；否则，争议可能会升级为拒付（chargeback）。 ## Disputes和Chargebacks主要区别 * 阶段： * 争议是拒付的前期阶段，持卡人对交易提出异议。 * 拒付是争议未解决后，发卡行采取的进一步行动，正式逆转交易。 * 处理流程： * 争议处理通常涉及初步的沟通和协商，试图在不进行正式逆转的情况下解决问题。 * 拒付处理更加正式，涉及交易金额的逆转，并且需要遵循支付网络的规定和流程。 * 影响： * 争议阶段的处理相对灵活，可以通过沟通解决，影响较小。 * 拒付对商户的影响较大，不仅涉及资金的逆转，还可能影响商户的信誉和未来的交易处理。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/FailureFinalState/index.md description: >- 失败终态是一种交易状态流转模式，在此模式下，支付失败后订单状态为终态，无法再次支付，需更换订单号重新发起。适用于需要严格控制重复支付的场景。主要状态包括SUCCESS、CLOSED、FAILED、PROCESSING和INIT。 --- # 失败终态 ## 交易状态流转模式 PingPongCheckout提供两种交易幂等模式： * 失败非终态（默认） * 失败终态（对接中需要告知PingPongCheckout配置） ## 失败非终态 `失败非终态`是默认设置，在这个模式下： * `FAILED`状态仍可以继续支付，直到订单超过时效关单为止，您可以不更换订单号发起再次支付。 * 小概率发生重复支付，可以做人工退款处理 | 状态 | 描述 | 状态类型 | |:------------------------------------------------------------------|:-----------------------------------------|:-----| | SUCCESS | 已成功支付，交易成功 | 终态 | | CLOSED | 交易因超期/关单导致的结果 | 终态 | | FAILED | 支付失败，用户可以重新支付 | 中间状态 | | PROCESSING | 中间状态，商户应等待 PingPongCheckout 异步结果再进行业务处理。 | 中间状态 | | INIT | 初始化订单 | 中间状态 | ## 失败终态 `失败终态`需要人工配置，在这个模式下： * `FAILED`状态为终态，支付单状态不会再变更，您需要更换订单号发起再次支付。 * `PROCESSING` 再次发起支付请求，会提示交易重复 | 状态 | 描述 | 状态类型 | |:------------------------------------------------------------------|:-----------------------------------------|:-----| | SUCCESS | 已成功支付，交易成功 | 终态 | | CLOSED | 交易因超期/关单导致的结果 | 终态 | | FAILED | 支付失败，用户可以重新支付 | 终态 | | PROCESSING | 中间状态，商户应等待 PingPongCheckout 异步结果再进行业务处理。 | 中间状态 | | INIT | 初始化订单 | 中间状态 | --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/groupId/index.md description: >- groupId是商户后台网站管理中用于标识群组的唯一编号。在群组管理页面，通过创建或选择已有群组并查看详情，可获取群组名称下的groupId。每个群组可以关联多个accId。 --- # groupId ## groupId的含义 商户后台的网站管理中会有群组的概念，一个群组对应一个GroupId，一个群组下面可以挂多个accId。 ## groupId如何获取 1. 从菜单栏选择【网站管理】-【群组管理】进入群组管理页面; 2. 系统默认会给一个默认的群组,商户也可以点击"创建群组"新建群组; 3. 点击"查看详情"即可查看群组的详细信息以及挂在群组下的网站信息，群组名称下面会显示GroupId，点击复制即可获取； --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/networkToken/index.md description: >- 网络令牌化是Visa、Mastercard等提供的服务，用16位数字替代主账号以增强支付安全性。使用网络令牌可提高授权率、减少购物者摩擦，并通过一次性密码保护每笔交易。即使卡片过期或丢失后重新发行，原有令牌仍有效。目前PingPongCheckout暂不支持直接收集网络令牌，但允许使用已有的令牌进行 --- # NetworkToken ## Network Tokenization Visa、Mastercard 等卡网络提供网络令牌化服务。网络令牌是 16 位主帐号 (PAN) 替代方案。 以下是使用网络标志进行支付的好处： 减少购物者的摩擦和拒绝，因为网络令牌由卡网络维护和自动更新。 与没有网络令牌的付款相比，授权率更高。 更好的支付安全性，因为每笔交易都受到一次性使用密码的保护。 因为网络令牌由卡网络管理，所以对关联卡的任何更新都不需要令牌更新。例如，如果卡过期或购物者丢失了卡然后重新发行，您仍然可以使用相同的令牌进行交易。 PingPongCheckout暂未开放收集Network token的功能，您可以选择自行收集和存储。如果您已经从 Visa、Mastercard 等卡网络收集网络令牌，您可以使用它们在 PingPongCheckout 进行支付。 ## 使用NetworkToken支付前提 需要接入下列其中一种模式: * Hosted * Non-Hosted --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/NotificationOfChargeback/index.md description: >- 拒付通知（Notification of Chargeback, NoC）是发卡银行发起的一种通知，告知商户某笔交易存在争议。NoC可以在信息请求后发起，或直接在交易状态设为已结算或已退款后发起。一旦发起NoC，争议处理流程开始，资金将从商户账户中扣除。适用于全球范围内的银行卡交易，关键步骤包括发起 --- # 拒付通知 拒付通知（Notification of Chargeback，简称 NoC）是指发卡银行（Issuer）发起的一种通知，告知商户某笔交易存在争议。NoC可以在信息请求（Request for Information，RFI）之后发起，也可以跳过RFI步骤，直接在交易状态设为已结算（Settled）或已退款（Refunded）后发起。一旦发起NoC，争议处理流程就正式开始，资金将从您的账户中扣除。 ## 拒付通知的详细流程 1. 发起拒付通知：发卡银行发现某笔交易存在争议，向商户的收单行（Acquirer）发起拒付通知（NoC）。 2. 通知商户：收单银行收到拒付通知后，会通知商户，并提供相关的交易信息和拒付原因。 3. 资金扣除：通常在商户收到拒付通知后的几天内，争议金额会从商户的账户中扣除。 4. 商户响应：商户可以在规定的时间内提交相关的证据和材料，证明交易的合法性和有效性。 5. 银行评估：收单行会将商户提交的材料转交给发卡银行，发卡银行会对这些材料进行评估，决定是否撤销拒付请求。 6. 决定结果：如果发卡银行认定商户提供的证据充分，拒付请求将被撤销，交易金额会重新转回到商户账户。如果发卡银行认定持卡人的争议成立，交易金额将退还给持卡人。 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/PCI/index.md' description: >- PCI 合规导航定义了支付卡行业数据安全标准(PCI DSS)，确保处理持卡人数据的公司维护安全环境。适用于所有接受信用卡或参与支付处理的实体，如商户、银行和服务提供商。获取PCI资质需遵守PCI DSS标准，完成自我评估问卷或外部审计，并进行定期安全扫描。集成方式包括使用PingPongCheck --- # PCI 合规导航 ::: note 提示 根据您的集成情况，PingPongCheckout 可能要求您提交 PCI DSS 文档，然后才能在生产环境中接受信用卡支付。 ::: ## PCI的含义 支付卡行业数据安全标准(PCI DSS)是由支付卡行业安全标准委员会(PCI SSC)创建的一套全球安全标准，目的是确保每个收集、处理、存储或传输持卡人数据的公司维护一个安全的持卡人数据环境。PCI DSS 适用于所有接受信用卡或参与支付处理的实体，如支付处理器、收购方、发行方和服务提供商。 ## PCI的作用 PCI资质主要适用于处理支付卡信息的组织，包括商户、银行、支付服务提供商以及其他涉及支付卡数据的机构。该资质的核心目标是保护持卡人数据的安全，防止数据泄露、盗用和欺诈行为。 PCI DSS 是主要卡组织(Mastercard，Visa，JCB，Diners，和 American Express)所采用的全球标准，它定义了一套技术和操作要求，如果正确实施，可以帮助您保护持卡人数据，减少欺诈，并最大限度地减少恶意攻击导致数据泄露的可能性。遵守这些要求可以帮助您保持购物者的信任。 ## 如何获取PCI资质 获得PCI资质需要通过一系列的安全评估和合规性测试，包括以下方面： 1. 遵守PCI数据安全标准（PCI DSS）：此标准规定了处理支付卡信息所需的安全措施，包括建立和维护安全网络、保护持卡人数据、实施强密码策略、定期监测和测试系统等。 2. 完成自我评估问卷（SAQ）或进行外部审计：根据组织的类型和处理支付卡数据的方式不同，需要完成相应的SAQ或接受独立的外部审计来验证符合PCI DSS的要求。 3. 支付应用程序的安全扫描：对使用支付应用程序的组织需要进行定期的安全扫描，以确保应用程序没有存在已知的安全漏洞。 ## 收银台集成 您可以使用 PingPongCheckout的收银台 或使用PingPongCheckout 的插件，使用 iframe 元素将网页嵌入到您的网站中。 嵌入元素的内容是从你的网页中隔离出来的，持卡人的数据在购物者的浏览器中被加密。您没有访问解密密钥，因此您没有访问您的购物者的持卡人数据。 ## API集成 您可以构建自己的 UI，并且只使用我们的 API。当您想要完全控制支付流程时，通常会使用这种集成。结帐页面由您托管、服务和控制。根据 PCI DSS 的要求，您从购物者的浏览器接收持卡人数据，处理数据，然后通过传输层安全(TLS 1.2)将原始卡数据发送给 PingPongCheckout。 这种集成需要更严格的 PCI DSS 范围，因为您的系统接收、传输以及可能存储和处理持卡人数据ーー使您能够完全控制支付流程和支付数据。一旦您的网站被恶意攻击，网站或您的系统将潜在地能够访问大量的持卡人数据。因此，您必须遵守所有符合条件的 PCI DSS 要求 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/PreArbitration/index.md description: >- 预仲裁是信用卡交易争议处理过程中的关键阶段，旨在通过进一步的证据交换和沟通，在正式仲裁前解决争议。适用于商户对首次拒付结果不满意或发卡银行不认可商户证据的情况。双方可提交额外证据，发卡银行评估后决定是否撤销拒付。若无法达成一致，争议将进入正式仲裁。 --- # 预仲裁 预仲裁（Pre-Arbitration）是信用卡交易争议处理过程中的一个重要阶段，预仲裁的目的是在正式仲裁之前，通过进一步的证据交换和沟通，尝试解决争议。 ## 预仲裁的详细流程 1. 发起预仲裁：当商户对首次拒付的结果不满意，或者发卡银行对商户提供的证据不认可时，商户或发卡银行可以发起预仲裁请求。 2. 提供额外证据：在预仲裁阶段，双方可以提交更多的证据和信息，以支持各自的立场。 3. 银行评估：发卡银行会对商户提供的额外证据进行审核和评估，决定是否接受商户的证据并撤销拒付请求，或者继续支持持卡人的争议。 4. 决定结果：如果发卡银行接受商户的证据，拒付请求将被撤销，交易金额将恢复到商户账户。如果发卡银行仍然支持持卡人的争议，预仲裁请求将被拒绝，交易金额将从商户账户中扣除。 5. 进入正式仲裁：如果预仲裁阶段双方仍无法达成一致，争议将进入正式仲裁阶段。正式仲裁由信用卡组织（如Visa或Mastercard）进行裁决，裁决结果具有最终约束力。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/salt/index.md description: >- salt 作为PingPong商户的密钥，用于验证PingPongCheckout API调用。完成注册后，商户可登录后台，在密钥管理中查看和管理salt。若发现密钥泄漏，可通过刷新功能生成新密钥以确保安全。 --- # salt 获取 ## salt 的用途 salt 是PingPong商户的密钥，并且是PingPongCheckout API调用的凭证，必须妥善保存，谨防泄漏！ ## salt 获取 需要完成pingPong的商户注册之后才可以获取，可以参考注册流程。 已完成注册的可以直接登陆到商户后台，点击 密钥管理 进行查看，具体位置如下截图所示： 注意事项： :::note 注意 如果密钥存在泄漏的情况，可以点击查看密钥之后进行刷新，刷新之后，用新的密钥进行替换即可。 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/Tokenization/index.md description: >- Tokenization 是一种数据保护技术，将敏感信息如信用卡号转换为随机生成的字符串（token），用于增强支付系统的安全性。该技术在用户通过支付网关进行交易时，使用token代替真实卡号处理支付，防止敏感信息泄露。主要优势包括提高安全性、简化合规性、增强客户信任和支持多种支付场景。国际信用卡和 --- # Tokenization ## Tokenization Tokenization 是一种数据保护技术，它将敏感数据（如信用卡号）转换成一个随机生成的字符串，称为“token”（token（令牌））。这些token（令牌）在外观上与原始数据相似，但不包含任何实际的敏感信息。因此，即使token（令牌）被泄露，也不会对原始数据的安全造成威胁。 在支付系统中，token（令牌）化用于增强交易的安全性。当用户通过支付网关进行交易时，他们的支付信息（如信用卡号）会被转换成token（令牌）。这个token（令牌）将被用于处理支付，而不是使用实际的卡号。这样，即使支付系统被黑客攻击，攻击者也无法获取用户的真实支付信息。 token（令牌）化的主要好处包括： * 提高安全性：由于token（令牌）不包含任何真实的敏感信息。 * 简化合规性：使用token（令牌）化可以减少企业在处理敏感支付信息时需要遵守的合规要求，例如PCI DSS（支付卡行业数据安全标准）。 * 增强客户信任：通过保护消费者的支付信息，企业可以增强消费者的信任，从而可能增加消费者的购买意愿和忠诚度。 * 支持多种支付场景：token（令牌）可以用于一次性支付、定期订阅付款或任何其他类型的电子支付，提供灵活性和便利性。 ## 支持情况 Tokenization 在国际信用卡支付/本地支付间有不同的产品形态： * 国际信用卡: CardOnFile * 本地支付: CodeGrant --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/transactionId/index.md description: >- transactionId是用于唯一标识一项交易的字符串或数字，确保在线交易和点对点转账的安全性和正确性。在PingPongCheckOut中，transactionId特指PingPong交易流水号，适用于追踪和管理交易流程。 --- # transactionId ## transactionId参数说明 :::note 备注 transactionId 通常指交易标识符，是用于唯一标识一项交易的字符串或数字。无论是在线交易还是点对点转账，都需要使用 transactionId 来确保交易的安全性和正确性。 ::: transactionId在PingPongCheckOut文档中表示 PingPong交易流水号。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/technicalterm/Void/index.md description: >- Void是指预授权撤销，用于商家决定拒绝已授权但未捕获的支付。适用于检测到高风险欺诈等情况。一旦支付被成功捕获，则无法再通过VOID取消，此时需通过退款流程将款项退还给消费者。 --- # Void 已授权的支付可以被捕获（资金被发送到商家账户）或取消（商家因某些原因决定拒绝支付，如高风险的欺诈）。 请注意，对于已经被捕获的交易，取消支付是不可能的。在这种情况下，商家应该发起退款，将资金返还给购物者。捕获、取消和退款一起被称为修改，因为它们修改了已授权支付请求的状态。 ## API列表 * CAPTURE-预授权权确认 * VOID-预授权撤销 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/threeDS/3ds/index.md' description: >- 3D Secure是一种在线交易验证协议，旨在防止电子商务中的欺诈活动。通过要求持卡人输入密码或一次性代码，为支付过程提供额外安全保障。PingPongCheckout支持三种3ds决策方案：强制执行、风控决策及外部执行。认证流程包括无摩擦和挑战两种模式，前者无需用户进一步交互即可完成认证，后者则需 --- # 3D Secure 认证集成 3D Secure是一种安全协议，用于验证在线交易并防止电子商务中的欺诈活动。它要求持卡人在完成交易前输入密码或一次性代码，从而为支付过程增加了额外的安全层。 ## PingPongCheckout支持的3ds决策方案 | executeThreeD | 收银台支持 | 端到端模式支持 | 描述 | |:--------------|:--------------------------------------------------------------------:|:-----------------------------------------------------------------|:------------------------------------------------| | Y | | | 强制进行3ds验证，并且使用PingPongCheckout的3ds。 | | depends | | | 是否进行3ds验证交由PingPongCheckout的风控决策决定 | | external | | | 需要进行3ds验证，在商户执行3ds，并把3ds结果交由PingPongCheckout执行。 | 根据统一下单接口调用时，参数executeThreeD取值来定： ## 3D Secure 认证流程 ### Frictionless 在Frictionless 流程中，购买者、发行者和卡方案通过使用购物者的设备指纹的被动认证在后台交换所有必要的信息。事务在没有进一步的购物者交互的情况下完成。 ### Challenge 在Challenge 流程中，银行或支付处理机构会自动为持卡人创建一个3D挑战页，购物者需要进行额外的交互。发卡行通过生物特征识别、双因素身份验证，或者基于 SCA 身份验证因素等类似方法确保交易的安全性。 一旦卡片持有人完成了3D挑战页上的身份验证步骤，他们的身份将被验证，并且银行或支付处理机构可以决定是否批准该交易。 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/threeDS/3DSexternal/index.md description: >- 3DS external接口用于商户主动上送3DS验证结果处理流程。适用于需要对持卡人进行额外身份验证的在线支付场景，支持Visa、American Express等主要卡组织。关键参数包括executeThreeD（固定值external）、authenticationValue（发卡行生成的身份 --- # 3DS external ## 商户主动上送3DS结果处理流程 ## 3DS关键入参 | 字段名称 | 类型 | 描述 | |------------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | executeThreeD | String | 主动上送3DS结果填`external` | | authenticationValue | String | 发卡行在客户身份验证后为Visa、American Express、JCB、Diners Club和Discover交易生成的唯一标识符。原始数据以base64为单位。需要将值转换为可读格式。 | | acsTransactionId | String | 由ACS分配的唯一事务标识符，用于标识单个事务。 | | veresEnrolled | String | 注册检查的结果。此字段可以包含以下值之一：- Y: 卡已注册或可注册；您必须进行身份验证。责任转移。- N: 未登记卡；进行授权。责任转移。- U: 无论何种原因，都无法进行身份验证。没有责任转移。 | | specificationVersion | String | 此字段包含用于处理事务的3D Secure版本。例如，1.0.2或2.0.0。 | | directoryServerTransactionId | String | 目录服务器交易ID由万事达目录服务器在认证交易期间生成，并与认证结果一起传递回商家。 | | threeDSServerTransactionId | String | 3DS服务器分配的唯一事务标识符，用于标识单个事务。 | | paresStatus | String | 身份验证检查的原始结果。此字段可以包含以下值之一：- A: 已生成身份验证尝试的证明。- N: 客户身份验证失败或取消。交易被拒绝。- U: 无论何种原因，身份验证都未完成。- Y: 客户已成功通过身份验证。 | | eci | String | 对于验证，仅为Visa、American Express、JCB返回数字电子商务指示符（ECI）Diners Club和Discover交易。身份验证失败时缺少字段。此字段包含以下值之一：- 01: 尝试身份验证（万事达卡）- 02: 认证成功（万事达卡）- 05: 成功的身份验证（Visa，American Express，JCB，Diners Club和Discover）- 06: 尝试身份验证（Visa，American Express，JCB，Diners Club和Discover） | ## 下单并支付接口入参示例 ```json { "clientId": "2018092714313010016", "accId": "2018092714313010016431", "amount": 10, "version": "1.0", "currency": "USD", "merchantTransactionId": "{{merchantTransactionId}}", "paymentType": "SALE", "shopperResultUrl": "https://aa.com", "shopperCancelUrl": "https://aa.com", "signType": "MD5", "threeDSecure": "N", "sign": "{{Sign}}", "requestId": "{{requestId}}", "acquirerType": "PAY", "notificationUrl": "https://test-acquirerpay.pingpongx.com/qa/notify", "threeDSRequestData": { "executeThreeD": "external", "acsTransactionId": "d53e5ae3-6a98-4ae0-be1a-7e7f0e91f392", "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=", "directoryServerTransactionId": "83196474-07ec-43d5-85a0-aafc9e505419", "eci": "02", "paresStatus": "Y", "threeDSServerTransactionId": "59a87425-2e29-484e-94f8-f2bc04649332", "specificationVersion": "2.1.0" }, "payMethodInfo": { "card": { "cvv": "103", "expireMonth": "12", "expireYear": "2025", "holderFirstName": "James", "holderLastName": "LeBron", "number": "5200000000003092" } }, "billing": { "city": "Birmingham", "country": "US", "email": "3ds@pingpongx.com", "firstName": "James", "lastName": "LeBron", "phone": "18301770495", "postcode": "35222", "state": "AL", "street": "1986 Broad Street" }, "shipping": { "city": "Miami", "country": "US", "email": "t_email", "firstName": "Jamesbb", "lastName": "LeBronbb", "phone": "3055787342", "postcode": "33131", "state": "FL", "street": "701 Brickell Avenue, Suite 2700", "lastModifierStreetTime": "20191225162010", "lastModifierPhoneTime": "20191225162010" }, "customer": { "acquisitionChannel": "SEARCH_ENGINE", "customerId": "20191201001", "domain": "pingpongx.com", "email": "3ds@pingpongx.com", "firstName": "James", "firstOrder": "N", "identificationId": "", "identificationType": "ID", "lastName": "LeBron", "lastPayTime": "201905120330", "loginIp": "222.126.52.24", "loginTime": "201912010032", "middleName": "von", "nonMemberOrder": "N", "orderCountry": "US", "orderIp": "222.126.52.23", "orderTime": "20191201001", "payCountry": "US", "payIp": "222.126.52.25", "phone": "18301770495" } } ``` --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/threeDS/api/index.md' description: >- threeDS API 用于收集和提交浏览器相关信息以增强支付安全性。适用于需要进行3D安全验证的在线支付场景，关键参数包括language、screenWidth、javaEnabled等，通过这些信息帮助识别真实用户，减少欺诈风险。 --- # api ## 必要参数收集 在浏览器上收集下列参数 | 属性 | 类型 | 描述 | |-------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------| | language | string | 购物者浏览器的navigator.language值（如IETF BCP 47中所定义）。 | | screenWidth | int | 持卡人终端屏幕宽度（单位：像素） | | javaEnabled | bool | 持卡人终端是否能够执行Java。 | | javaScriptEnabled | bool | 指示购物者的浏览器是否能够执行JavaScript。如果字段不存在，则假定为默认的`true`值。 | | acceptHeader | string | http响应头信息， 示例值: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, image/apng, \*;q=0.8 | | colorDepth | string | | | screenHeight | int | 持卡人终端屏幕高度（单位：像素） | | jetLag | int | UTC时间和持卡人浏览器本地时间之间的时差，以分钟为单位。 | | userAgent | string | 浏览器用户代理信息 示例值：Mozilla/5.0 (Macintosh; Intel Mac OS X 10\_14\_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.121 Safari/537.36 | ## 填充browserInfo 请求PingPongChekout 下单并支付接口。在参数 `browserInfo`中上送以上参数。 请求报文示例： ```json { "accId":"2090020315464510103001", "clientId":"2090020315464510103", "signType":"SHA256", "sign":"{{Sign}}", "version":"1.0", "bizContent":{ "captureDelayHours":"0", "amount":"3", "currency":"USD", "merchantTransactionId":"{{merchantTransactionId}}", "payResultUrl":"https://test-acquirerpay.pingpongx.com/qa/result.html", "payCancelUrl":"https://test-acquirerpay.pingpongx.com/qa/result.html", "notificationUrl":"https://test-acquirerpay.pingpongx.com/qa/result.html", "language":"en", "requestId":"{{requestId}}", "tradeCountry":"US", "shopperIP":"222.126.52.23", "paymentMethod":{ "type":"scheme", "cardInfo":{ "expireMonth":"12", "expireYear":"2024", "holderFirstName":"w", "holderLastName":"w", "number":"5200000000001096", "cvv":"103" } }, "customer":{ "firstName":"Jamesbb", "lastName":"LeBronbb", "email":"test@pingpongx.com", "phone":"9157030054" }, "goods":[ { "name":"商品名称mepsking1", "description":"商品描述", "sku":"产品SKU111", "unitPrice":"1000", "number":"1", "imgUrl":"https://xiu.mepsking.top/material/1/16606169805015585.png", "virtualProduct":"Y" } ], "shippingAddress":{ "firstName":"Jamesbb", "lastName":"LeBronbb", "phone":"9157030054", "email":"3ds@pingpongx.com", "street":"3888 Austin Secret Lane", "postcode":"84723", "city":"Circleville", "state":"UT", "country":"US" }, "billingAddress":{ "firstName":"Jamesbb", "lastName":"LeBronbb", "phone":"9157030054", "email":"3ds@pingpongx.com", "street":"3888 Austin Secret Lane", "postcode":"84723", "city":"Circleville", "state":"UT", "country":"US" }, "browserInfo":{ "acceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", "colorDepth":"24", "jetLag":"480", "language":"nl-NL", "javaEnabled":"true", "screenHeight":"723", "screenWidth":"1536", "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.121 Safari/537.36", "windowSize":"05" }, "device":{ "orderTerminal":"02" } } } ``` ## 是否需要3DS挑战 * `threeDUnionParams.threeDContinue`为`true`时候需要触发3D挑战。 * `threeDUnionParams.threeDContinue`为`false`时候将会跳转到商户的支付结果页`shopperResultUrl`。 ## 重定向到3DS挑战页 从下单并支付接口的响应报文中获取`threeDUnionParams.threeDRedirectUrl`参数，通过GET方式跳转，随后PingPongCheckout提供的中间页将会自动重定向到3DS挑战页。 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/threeDS/avsResult/index.md' description: >- avsResult文档详细描述了AVS验证结果及其应用情况。适用于所有发卡行，根据不同的卡片方案（如Visa、Mastercard、American Express等），提供了具体的响应代码和含义。例如，A表示地址匹配但邮政编码不匹配，N表示地址和邮政编码均不匹配。 --- # avsResult ## AVS 验证结果详细说明 | AVS Result | AVS Raw Response Code | 应用于 | 详细信息 | |------------------------------------------------------|-----------------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Unknown. | - | 所有发卡行 | 没有从发卡银行收到答案。 | | Address matches, but the postal code does not match. | A | 针对不同卡片方案有所不同 | Visa和Mastercard：地址匹配，邮政编码不匹配。American Express：只有地址匹配。 | | Neither postal code nor address match. | N | Visa，Mastercard，Discover，American Express | 地址和邮政编码都不匹配。 | | AVS unavailable. | R, S, U | Visa，Mastercard，Discover，American Express | R：系统不可用或超时。Discover：不适用。S：AVS目前不支持。U：发卡机构/授权平台没有数据。Discover：系统不可用或超时。 | | AVS not supported for this card type. | E | Visa | E：AVS数据无效或此卡类型上不允许AVS。 | | Postal code matches, but the address does not match. | T, W, Z | 针对不同卡片方案有所不同 | T：仅限Discover：对于美国地址，九位数的邮政编码匹配但地址不匹配。W：仅限Mastercard：对于美国地址，九位数邮政编码匹配但地址不匹配；对于美国以外的地址，邮政编码匹配但地址不匹配。Z：Visa：对于美国地址，五位或九位邮政编码匹配但地址不匹配。Z：Mastercard和Discover：对于美国地址，五位邮政编码匹配但地址不匹配。Z：American Express：只有邮政编码匹配。 | | Both postal code and address match. | D, F, M, X, Y | 针对不同卡片方案有所不同 | D：仅限Visa：街道地址和邮政编码匹配。F：仅限Visa：街道地址和邮政编码匹配。适用于英国。M：仅限Visa：街道地址和邮政编码匹配。X：Visa和American Express：不适用。万事达卡：对于美国地址，所有邮政编码数字都匹配；对于美国以外的地址，邮政编码和地址匹配。Discover：对于美国地址，九位数的邮政编码和地址匹配。Y：对于Visa：对于美国地址，五位或九位邮政编码匹配。对于Mastercard：对于美国地址，五位邮政编码和地址匹配。对于Discover：只有地址匹配。对于American Express：邮政编码和地址匹配。 | | Address matches, postal code not checked. | B | Visa | 街道地址匹配。邮政编码未验证，因为格式不兼容。（收单行同时发送了街道地址和邮政编码。） | | Postal code matches, address not checked. | P | Visa | 邮政编码匹配。街道地址未经验证，因为格式不兼容。（收单行同时发送了街道地址和邮政编码。） | | Neither postal code nor address were checked. | C, G, I | Visa | C：由于格式不兼容，街道地址和邮政 | --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/threeDS/depends3D/index.md' description: >- depends3D接口用于PingPongCheckout的3DS决策流程，适用于端到端接入方式。关键参数`executeThreeD`需设置为`depends`以启用3DS验证。收银台JS-SDK已内置3D Secure功能，无需额外集成。 --- # depends3D ## 3DS 决策流程 ## 3DS关键入参 | 字段名称 | 类型 | 描述 | |---------------|--------|------------------------------------| | executeThreeD | String | 由PingPongCheckout进行3ds决策填`depends` | ## PingPongCheckout支持的3DS接入方案 > 下列方案仅适用端到端接入方式。收银台JS-SDK内部已经自动集成 3D Secure，无需再次接入。 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/threeDS/Force3D/index.md' description: >- Force3D 用于在支付过程中强制执行3DS认证。适用于需要增强交易安全性的场景，特别是在端到端接入方式下。关键参数`executeThreeD`设置为`Y`时，将触发强制3DS验证流程。PingPongCheckout的收银台JS-SDK已内置3D Secure功能，无需额外集成。 --- # Force3D ## 3DS 决策流程 ## 3DS关键入参 | 字段名称 | 类型 | 描述 | |---------------|--------|---------------| | executeThreeD | String | 强制进行3DS认证填`Y` | ## PingPongCheckout支持的3DS接入方案 > 下列方案仅适用端到端接入方式。收银台JS-SDK内部已经自动集成 3D Secure，无需再次接入。 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/threeDS/riskJs/index.md' description: >- riskJs组件用于集成3D Secure验证，适用于需要增强在线支付安全性的场景。主要功能包括初始化设置与收集卡信息进行3D init。关键参数有env、accId、clientId等，支持通过cardInfo或cardToken传递卡信息。该组件能够自动生成并返回jsGeneratedData以 --- # 3D Secure-riskJS组件集成指南 ## 引入riskJs组件 ```js ``` ## 初始化 ### 构造方法 ```js window.PingPongRiskControl(options, callback) ``` | 属性 | 类型 | 必填 | 描述 | |:-----------------------|:-----------|:----|:-------------------| | options.env | String(12) | M | 沙箱-sandbox 生产-prod | | options.accId | String(32) | M | PingPong商户号 | | options.clientId | String(32) | M | PingPong店铺号 | | options.merchantUserId | String(64) | M | 商户网站唯一标识 | | options.requestId | String(64) | M | 订单关联唯一标识 | | callback(this) | Function | O | 回调函数 | ### 调用示例 ```javascript //初始化参数 let options = { env: env, // 沙箱-sandbox 生产-prod accId: accId, clientId: clientId, merchantUserId: merchantUserId, requestId: requestId } const client = new window.PingPongRiskControl(options, callback) ``` ### 调用 installLight\_S2S ```js client.installLight_S2S() ``` 至此，riskJs组件初始化部分已经完成。 ## 收集卡信息进行3D init * 为了收集完整正确的卡号，该方法可在 卡号 和 卡有效期 input 失焦后进行触发，调用后插件将自行进行3DS初始化操作。 * 初始化完成之后，插件将jsGeneratedData注入回调函数-callback。 * 需要定时等待获取到jsGeneratedData提交订单，超时未获未获取到jsGeneratedData可以先提交订单，但当前交易若决策为需要3DS验证，则无法进行3DS challenge流程。 ### 构造方法 ```js client.complexInit(options, callback) ``` ### 3D init入参 | 属性 | 类型 | 必填 | 描述 | |:-----------------------|:-----------|:----|:----------------| | options.accId | String(64) | M | PingPong 商户店铺编号 | | options.merchantUserId | String(64) | M | 商户网站会员唯一标识 | | options.requestId | String(64) | M | 订单关联唯一标识 | | callback(this) | Function | O | 回调函数 | > cardInfo和cardToken，二者必须传送其中一项。 #### cardInfo | 属性 | 类型 | 必填 | 描述 | |:------------------------|:-----------|:----|:-----------| | options.cardNumber | String(12) | C | 国际信用卡卡号 | | options.cardExpireMonth | String(32) | C | 有效期-月，2位数字 | | options.cardExpireYear | String(64) | C | 有效期-年，4位数字 | #### cardToken | 属性 | 类型 | 必填 | 描述 | |:------------------|:-----------|:----|:---------------| | options.cardToken | String(32) | C | 可以用来替代cardInfo | ### 调用示例 ```javascript let initOptions = { cardNumber: cardNumber, // 卡号: 插件会自己判断当前卡号长度是否 >= 15 cardToken: cardToken, cardExpireMonth: cardExpireMonth, cardExpireYear: cardExpireYear, // 2022 || 22 cardBrand: cardBrand, accId: accId, merchantUserId: merchantUserId, requestId: requestId } client.complexInit(initOptions, callback) function callback(jsGeneratedData){ // 自动注入jsGeneratedData } ``` ### jsGeneratedData 的属性 | 属性 | 备注 | |:------------------------|:----| | threeDInitTransId || | threeDSecureReferenceId || | channel || | correlationId || | fingerPrint || | forterSiteId || | forterTokenCookie || | threeDSServerTransID || | version || ## 统一下单报文组装 在下单并支付API中，上送下列参数： * jsGeneratedData （执行3DS流程的必要条件） * browserInfo （可选，建议上送，可以提高交易成功率） ## 3DS 验证处理 ### 如何处理 * 商户在调用接口-下单并支付之后，根据响应的交易状态与 `threeDContinue` 处理标识判断是否需要3DS验证处理。 * 如果支付状态 `status` 为 `PROCESSING`并且`threeDContinue` 为 `true`，商户前端需要执行风控JS提供的`complexTrigger`函数。 * 将接口返回 的 `threeDUnionParams` 作为入参调用 `complexTrigger` 函数，风控JS会引导浏览器到3D挑战页，持卡人需要正确的完成3D验证，才能成功交易。 ### complexTrigger ```js client.complexTrigger(threeDUnionParams, callback) ``` | 属性 | 必填 | 备注 | |:------------------|:----|:-----------------------------------------------------------------------------------------------| | threeDUnionParams | M | 调用PingPongCheckout下单并支付接口后返回的`threeDUnionParams` | | callback | O | 商户可在此处理正常支付流程。若该笔交易进入3D流程，则该回调不会执行，否则执行该回调函数，处理正常支付逻辑 | \`\` --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/cof/bind/index.md description: >- 绑卡获取凭证功能支持用户安全地存储支付信息，适用于需要简化支付流程、提高支付体验的场景。通过将用户的银行卡信息转换为不可逆的令牌，确保敏感数据的安全性。此功能覆盖全球主要市场，支持多种银行卡类型，并提供API接口以方便集成，关键参数包括客户ID、卡片信息等。 --- # 绑卡获取凭证 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/cof/bindList/index.md description: >- 绑卡查询接口提供已绑定银行卡信息的检索服务。适用于需要获取用户已绑定支付方式详情的应用场景，支持通过客户ID查询其名下所有有效卡片列表。返回数据包括但不限于卡片别名、类型及部分脱敏卡号等关键信息，便于进一步处理或展示给用户。 --- # 绑卡查询接口 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/cof/unbind/index.md description: >- 解绑接口用于取消已绑定的支付卡与用户账户之间的关联。适用于需要移除或更新支付方式的场景，支持全球范围内的支付卡操作。通过调用此API，开发者可以实现安全、高效地管理用户的支付卡信息，关键参数包括用户标识符和待解绑卡片的token。 --- # 解绑接口 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/hosted/index.md description: >- 创建cardToken-Hosted模式用于通过安全方式存储信用卡信息，以便未来快速支付。适用于需要简化用户支付流程的场景，如电商网站。关键特性包括在首次支付时允许用户勾选保存卡信息（不含CVV/CVC/CVN），之后系统自动展示历史卡信息以供选择。主要功能涵盖客户端下单、同步响应及从异步通知获取t --- # 创建cardToken-Hosted模式 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/nonHosted/index.md description: >- 创建cardToken-NonHosted模式用于在非托管环境下生成卡令牌。适用于需要提高支付安全性及减少PCI DSS合规负担的场景。主要步骤包括客户端下单上传指定参数以请求创建cardToken，通过API同步响应并从异步通知中获取token。成功支付后可正常获得token，失败则无法获取。 --- # 创建cardToken-NonHosted模式 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/oneClickPayment/bind/index.md description: >- 签约接口用于实现用户银行卡信息的令牌化存储，支持后续快速支付。适用于电商平台、移动应用等场景，提高支付安全性与便捷性。主要功能包括生成和管理卡片令牌，关键参数有商户ID、用户ID及卡信息。 --- # 签约接口 > --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/oneClickPayment/bindList/index.md description: >- 签约查询接口用于获取用户已绑定的支付卡列表。适用于需要展示或管理用户支付方式的应用场景，支持全球主要地区。通过此API，开发者可以实现一键支付功能，提升用户体验。请求需携带必要的身份验证信息，响应包含卡片类型、部分掩码卡号等关键参数。 --- # 签约查询接口 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/oneClickPayment/unbind/index.md description: >- 解约接口用于解除已绑定的支付卡,适用于用户不再使用某张卡片进行快速支付或需要更换支付方式时。此接口属于令牌化模块,通过提供必要的参数如token_id等,可安全地取消卡片与账户之间的关联,确保用户信息安全的同时简化了管理流程。 --- # 解约接口 --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tokenization/unbind/index.md description: >- Token 解绑功能允许商户取消已绑定的支付令牌，使该令牌失效但不影响之前交易的后续操作如退款。通过POST请求调用，需提供clientId、accId等必要参数及待解绑的token信息。支持沙箱和生产环境部署。 --- # Token 解绑 * token 解绑成功后，该 token 将不能再被使用。 * 之前使用该 token 进行交 易的后续交易(退款、预授权完成、预授权撤销)不受影响。 ## 请求地址 ::: code-tabs @tab 🧪 沙箱环境 ```http https://sandbox-acquirer-payment.pingpongx.com/v4/tokenization/unbind ``` @tab 🏭 生产环境 ```http https://acquirer-payment.pingpongx.com/v4/tokenization/unbind ``` ::: ## 请求参数 | 参数字段 | 参数类型 | 参数属性 | 参数说明 | |:-----------|:-------------|:-----|:---------------------------------------------------------------------------------------------| | clientId | String(64) | M | PingPong商户号 | | accId | String(64) | M | PingPong商户店铺编号 | | version | String(10) | M | 当前固定为1.0，后续随接口变动可能有调整 | | signType | String(32) | M | 签名规约，支持 MD5、SHA256，具体⻅本文签名规约一栏 | | sign | String(128) | M | 签名，具体⻅本文签名规约一栏，所有参数均参与签名 | | bizContent | String | M | 请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递 ，格式：JSON字符串 | ### 请求参数 | 参数字段 | 参数类型 | 参数属性 | 参数说明 | |:---------------|:-----------|:-----|:-------------| | token | String(20) | M | 持卡人绑定的 Token | | merchantUserId | String(64) | M | 商户网站的持卡人 ID | ## 响应参数 ### 返回参数 | 参数字段 | 参数类型 | 参数属性 | 参数说明 | |:-------|:-------|:-----|:--------------------------------------------------------| | status | String | M | 解绑状态SUCCESS-解绑成功FAILED-解绑失败 | --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tools/api/index.md' description: >- Non-hosted 调试工具专为API调试设计，适用于开发阶段。支持接收 bizContent 参数作为 JSON 对象或字符串，确保开发者遵循文档规范传递参数，以验证请求和响应的正确性。 --- # Non-hosted 调试工具 ::: warning 为了方便您的调试，本调试工具接受 bizContent 参数格式为 json 对象（我们会进行转化）或者 Json 字符串，开发过程中请务必严格参照文档传值 ::: --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tools/redirect/index.md' description: >- Hosted-Redirect 调试工具用于简化支付流程的调试。支持接受 bizContent 参数为 JSON 对象或 JSON 字符串，自动进行格式转换。适用于开发阶段，确保参数传递准确无误。请严格参照文档传值以保证调试过程顺利。 --- # Hosted-Redirect 调试工具 ::: warning 为了方便您的调试，本调试工具接受 bizContent 参数格式为 json 对象（我们会进行转化）或者 Json 字符串，开发过程中请务必严格参照文档传值 ::: --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tools/RiskDefense/index.md' description: >- RiskDefense 调试工具用于测试和验证风控插件的功能。适用于开发人员在集成风控系统时进行调试，确保规则配置正确且响应符合预期。支持模拟多种交易场景，帮助识别潜在风险并优化风控策略。 --- # RiskDefense 调试工具 --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tools/sdk/index.md' description: >- JS-SDK 调试工具用于简化 PingPongCheckout API 的调试过程。支持接受 bizContent 参数格式为 JSON 对象或 JSON 字符串，便于开发者在开发过程中根据文档要求进行测试和验证，确保参数传递的准确性。 --- # JS-SDK 调试工具 ::: warning 为了方便您的调试，本调试工具接受 bizContent 参数格式为 json 对象（我们会进行转化）或者 Json 字符串，开发过程中请务必严格参照文档传值 ::: --- --- url: 'https://acquirer-api-docs-v4.pingpongx.com/notes/zh/tools/sign/index.md' description: >- 签名工具用于生成符合PingPongCheckout v4签名规约的签名。适用于所有需要升级至v4版本的开发者，确保所有参数均参与签名过程。遵循新的签名规则可保障请求的安全性和完整性。 --- # 签名工具 ::: warning 注意 v4 签名规约 中要求所有的参数均参与签名，如果之前对接的是v2或者v3版本要升级到v4，需要按照新的签名规则进行对接 ::: --- --- url: >- https://acquirer-api-docs-v4.pingpongx.com/zh/notes/paymentMethods/ApplePay/merchantCertificateConfiguration/index.md description: >- 文档介绍了如何为网站配置Apple Pay商户证书，以实现非托管方式的Apple Pay Web集成。适用于希望通过Safari浏览器提供Apple Pay支付选项的全球在线商家。内容涵盖从注册苹果开发者账号到完成域名验证的全过程，包括申请证书、创建商家标识符及与PingPongPay交换证书信息等 --- # Apple Pay 商户证书配置 ## 概述 Apple Pay 的网页集成允许用户在网页上通过 Safari 浏览器直接使用 Apple Pay 完成支付。为了在你的网站上实现 Apple Pay，你需要进行一些配置和开发工作，包括生成必要的秘钥、创建支付请求、处理支付授权等。下面是一个基本的步骤指南， 说明了Non-hosted方式集成**Apple Pay Web** 的流程。与Apple Pay Hosted方式相比，Non-hosted方式需要开发者自行实现与Apple Pay UI的交互流程。 ## 1.注册Apple开发者账号 首先，你需要拥有一个有效的苹果开发者账号，并且加入 Apple Developer Program。这是使用 Apple Pay Web API 的先决条件。 ## 2.申请证书 请将`申请材料`发送给邮箱acq-tech@pingpongx.com，并抄送到acq-ts@pingpongx.com 1. 商户名称 2. 商户 AccId 3. 商户 ClientId PingPong 收单团队收到申请邮件，完成所需的配置后，会将证书以邮件附件的形式回复商户。 ## 3.在Apple开发者平台上创建一个商家标识 在 Apple 开发者平台上创建商家标识符（Merchant ID）是集成 Apple Pay 的关键步骤之一。商家标识符用于标识您的业务，并确保支付过程的安全。以下是创建 Merchant ID 的详细步骤。如果您已有商家标识符，可以跳过这个步骤。 ### 登录 Apple 开发者账号 1. 打开 [Apple Developer](https://developer.apple.com/) 平台。 2. 登录您的 Apple 开发者账户。 3. 进入 Apple Developer Center。 4. 在 Apple Developer 选择“Identifiers”。 ### 输入商户标识符基本信息 1. 输入一个描述性的名称，这将帮助您在项目中标识不同的商家标识。例如：“My Online Store Payment”。 2. 输入 Merchant ID 的标识符，通常以 merchant. 开头，例如 merchant.com.example.onlinestore。这个标识符需要是唯一的，并且通常与您的域名相关联以保持一致性。 至此，您已经成功创建了商家标识符。 ## 4.为商户标识符添加证书 1. 回到商户表示列表，点击当前创建的商户标识符，进入详情页面。 2. 在详情页点击 **Apple Pay Payment Processing Certificate** 下的Create Certificate。 3. 点击 **chooseFile** 4. 上传前面步骤邮件附件中的 **certSigningRequest**类型文件 ## 5.下载您的证书 1. 点击 **Download** 下载证书。 2. 下载完成之后，您可以得到一个`.cer`类型的文件 ## 6.商户域名验证 ::: note 提示 域名验证仅限于 Apple Pay Web 的集成方式。如果Native SDK 集成方式，则不需要进行域名验证。 ::: 1. 进入商户标识列表，点击当前创建的商户标识符，进入详情页面。 2. 在详情页将页面往下滚动 3. 点击 **Add Domain** 4. 填写您的域名 5. 点击**下载**按钮,您将得到一个`apple-developer-merchantid-domain-association.txt`文件，内容是Apple预先生成的一个字符串，稍后Apple将会请求您的服务器获取内容进行验证。 6. 将您的文件上传到您的服务器，放入Apple指定的位置。 ::: note 提示 * 如图所示，域名验证文件放在Web服务的根目录下`.well-known`的目录中。 * 文件名必须为`apple-developer-merchantid-domain-association.txt`。 * 域名验证文件内容必须与Apple预先生成的字符串一致。 * 您可以在l浏览器中访问`https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association.txt`，如果返回内容一致，则表示验证成功。 ::: 7. 如果在浏览器中验证成功，可以点击**Verify**进行验证。 ## 7.与PingPongPay交换证书信息 请将以下信息发送给邮箱`acq-tech@pingpongx.com`，并抄送到`acq-ts@pingpongx.com` * `.cer`文件 * 您已验证通过的domain 另外，`.certSigningRequest`文件请您自行留存，后续可能会使用