简体中文

English

简体中文

English

外观

国际信用卡支付（Non-hosted）

约 4817 字大约 16 分钟

View as Markdown

2025-03-07

PingPong Non-hosted 本地支付是一款专为跨境交易打造的轻量级、高安全后端解决方案。通过标准化的 API 集成，商户可一站式接入全球丰富的本地支付方式（涵盖电子钱包、网银、银行卡等）。我们致力于为您扫除多通道对接的技术壁垒，在保障交易安全合规的前提下，为全球买家提供极致顺滑的支付体验，助力您的出海业务快速落地与规模化扩张。

本文介绍银行卡支付的 Server-to-Server 集成方案。该模式适合对支付流程有高定制化需求的商户。请注意，选择此模式需确保您的业务已通过 PCI 合规认证。

支持特性
下单支付（即时扣款）预授权（先冻结后确认）部分请款退款与部分退款记住卡号重新支付CardOnFileRecurring首笔0元 Recurring3DS

方案说明

在该模式下，买家始终在商户页面完成卡信息输入；当交易需要 3DS 验证时，再由商户前端根据同步响应跳转至发卡行挑战页面。该方案更适合希望自定义收银台体验、并具备 PCI-DSS 合规与前端支付链路建设能力的商户。

接入前提

  1. 商户具备 PCI 资质，并通过 PingPongCheckout 验证。（PCI-DSS 请发送邮件附件到 acquire-risk@pingpongx.com 并抄送 gig-tech-acq@pingpongx.com）
  2. 商户具备自行开发信用卡收银台页面的能力。
  3. 商户已具备接入风控与 3DS 组件的前端能力。

注意

采用国际信用卡支付（Non-hosted）方案时，商户需要自行保存、处理持卡人的信用卡信息，因此必须具备 PCI-DSS 认证。

支付流程

流程说明：

  1. 商户前端在支付提交前完成风控与 3DS 参数采集。
  2. 商户服务端调用 下单并支付 创建国际卡支付订单。
  3. PingPongCheckout 返回同步响应后，商户前端根据 status 和 threeDContinue 决定是否进入 3DS 挑战。
  4. 若需要 3DS，商户前端应跳转 threeDUnionParams.threeDRedirectUrl；挑战完成后，PingPongCheckout 会将买家带回 payResultUrl。
  5. 买家回跳至 payResultUrl 仅表示前端流程结束，不代表交易成功；最终结果必须以 支付通知 或 交易查询 为准。

接口列表

国际信用卡支付（Non-hosted）通常涉及以下接口和通知：

阶段类型文档是否必接用途
支付创建文档Dynamic 3D Secure必读完成风控与 3DS 组件接入，收集支付所需风控参数
API下单并支付必接提交卡信息、风控参数与订单信息，创建支付订单
支付结果通知支付通知必接接收最终支付结果并更新商户订单状态
API交易查询推荐在通知延迟、未达或需要核验结果时主动确认交易状态
退款API申请退款按需对成功支付的国际卡交易发起退款
通知退款通知推荐接收退款结果并更新退款状态
API退款查询推荐在通知延迟、未达或对账时主动确认退款状态
预授权请款 / 撤销API预授权请款手动请款场景必接对已预授权交易发起请款
API预授权撤销手动请款场景必接对已预授权但未请款的交易发起撤销
通知预授权请款通知手动请款场景推荐接收预授权请款结果
通知预授权撤销异步通知手动请款场景推荐接收预授权撤销结果

集成步骤

请按以下步骤完成集成：

  1. 准备风控与 3DS 参数并发起支付
  2. 获取最终支付结果

步骤 1：准备风控与 3DS 参数并发起支付

在调用 下单并支付 前，商户前端需要先完成 SafePayGuardJs、SecureShieldJs 接入，并采集支付所需的 browserInfo、jsGeneratedData 等参数；随后由商户服务端调用下单并支付创建支付订单。前端组件初始化、triggerThreeDsInit 触发时机以及参数获取方式，请直接参考以下文档：

注意

如果您无法在前端页面嵌入相关 JS 组件，请先与商务或风控团队确认是否可评估其他 3DS 接入方案。

支付请求中建议重点关注以下信息：

信息说明
paymentMethod.type卡品牌或卡组织，例如 VISA、MasterCard、JCB、AmericanExpress、Discover、DinersClub、UnionPay。支持的卡品牌可参考 国际信用卡 页面
paymentMethod.cardInfo持卡人卡信息，包括卡号、有效期、CVV、持卡人姓名等
requestId支付请求流水号，建议保持全局唯一
merchantTransactionId商户订单流水号，用于关联商户订单与支付交易
merchantUserId商户侧用户唯一标识，用于关联持卡人身份
goods商品信息，用于补充交易上下文
browserInfo3DS 组件收集的浏览器信息，支付请求中需要一并上送
jsGeneratedData风控与 3DS 组件生成的交易安全参数，支付请求中需要一并上送
notificationUrl用于接收最终支付结果的异步通知地址
payResultUrl买家完成 3DS 或支付流程后回到商户页面的地址
device.orderTerminal下单终端。01 WAP、02 Web、04 iOS App、05 Android App

有关完整参数的更多信息，请参阅 下单并支付。

支付请求示例（仅展示 bizContent 内容）：

注意

payResultUrl 只用于买家完成前端流程后的回跳展示，不代表支付成功。涉及订单落账、发货或发放权益时，必须以服务端结果为准。

下单并支付后，商户服务端会先收到同步响应。

同步响应示例（仅展示 bizContent 内容）：

响应关键字段：

字段说明
status交易当前状态，可能为 SUCCESS、FAILED 或 PROCESSING
threeDContinue是否需要继续进入 3DS 挑战流程
threeDUnionParams.threeDRedirectUrl当需要 3DS 挑战时，商户前端应跳转的地址
transactionIdPingPong 交易流水号
requestId支付请求流水号

订单的授权结果需根据 status 的值进行判断：SUCCESS 和 FAILED 表示支付终态结果，PROCESSING 表示处理中。

下表展示了同步响应中 status 字段可能返回的值，请根据指引进行处理：

status信息后续操作
SUCCESS授权支付成功。当前无需继续跳转 3DS。请保存 transactionId，并继续通过异步通知或交易查询确认最终支付结果。
FAILED授权支付失败。请提示买家重试或更换卡片。
PROCESSING交易处理中。如果返回了 threeDUnionParams.threeDRedirectUrl，说明需要继续完成 3DS 挑战，商户前端按需跳转至该地址；如果未返回可跳转地址，请继续等待异步通知，或主动调用交易查询确认结果。

跳转3DS认证页面（可选）

这是一个可选步骤，仅当同步响应中的 threeDContinue=true 时才需要执行。此时说明买家仍需完成 3DS 挑战，同步响应中的 threeDUnionParams 字段内容可能如下：

如果需要进入 3DS 挑战流程，请根据不同终端跳转 threeDRedirectUrl：

3DS 跳转注意事项

  • threeDRedirectUrl 是 PingPongCheckout 返回的完整跳转地址。商户前端应直接使用服务端返回的原始值，将其作为不透明链接处理，不要自行拼接额外参数，也不要先 decode 再重新 encode，以免导致 3DS 页面无法正常打开。
  • 不要依赖固定域名、固定路径或静态规则识别 3DS 挑战页，应始终以服务端返回的 threeDRedirectUrl 为准。
  • 建议在顶层页面打开 3DS 挑战，不要在 iframe 中承载挑战页，避免跳转、输入或回跳异常。
  • App 端建议优先使用系统浏览器或系统级网页容器；如果必须使用 WKWebView 或 WebView，请提前完成真机验证，确认跳转、回退、键盘和页面缩放行为正常。
Web
function redirectThreeDOnWeb(threeDRedirectUrl) {
  if (!threeDRedirectUrl) return;
  window.location.assign(threeDRedirectUrl);
}

提示

threeDRedirectUrl 是 PingPongCheckout 提供的 3DS 中间页地址。买家访问该地址后，页面会自动继续跳转至发卡行 3DS 挑战页；挑战完成后，PingPongCheckout 会将买家带回您在支付请求中设置的 payResultUrl。

步骤 2：获取最终支付结果

国际卡支付的最终结果，建议优先通过服务端异步通知确认。若异步通知延迟、未达、回调处理异常，或商户在买家回跳后需要立即核验结果，可在支付后操作中主动调用交易查询。交易查询的完整集成方案请参考 支付后操作 > 查询交易。

支付通知示例（仅展示 bizContent 内容）：

通知关键字段：

参数说明处理建议
notifyType通知类型，支付通知固定为 RECHARGE用于区分通知事件类型
transactionIdPingPong 交易流水号保存并用于后续查询、退款、对账
merchantTransactionId商户网站订单流水号用于定位商户订单
requestId支付请求流水号用于定位本次支付请求
amount / currency交易金额和币种必须与商户订单金额、币种核对
status支付结果状态按状态更新商户订单

通知中的 status 建议按以下方式处理：

status处理指引
SUCCESS支付成功，可以进行发货、权益发放或订单完成处理。
FAILED支付失败，订单保持未支付或失败状态，可允许买家重新支付。
AUTH_SUCCESS预授权成功，尚未完成最终扣款；如采用手动请款，请按业务流程继续发起请款。
CANCEL预授权撤销或人工审核拒绝，不可按成功处理。

收到通知后，您无需对响应内容进行加签处理。但无论订单支付是否成功，均必须严格按照以下固定格式返回响应。商户服务端应优先返回 HTTP 2xx 确认已接收。

通知响应示例：

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: 2

OK

支付后操作

以下内容介绍国际卡支付完成后，如何通过服务端主动查询交易状态，以及如何继续处理预授权请款、预授权撤销、退款和对账。

查询交易

当买家从支付页面跳回商户结果页、异步通知延迟、未达、回调处理异常，或商户需要执行补偿任务时，可以调用 交易查询 获取交易最新状态。

交易查询请求示例（仅展示 bizContent 内容）：

{
  "merchantTransactionId": "PMT-WWK4L1L2Q11782466163266"
}

交易查询响应示例（仅展示 bizContent 内容）：

查询响应关键字段：

参数处理方式
resultCode000000 表示查询请求成功；查询请求成功不等于支付成功
status商户订单状态应以该字段为准
transactionId保存为 PingPong 交易流水号，用于后续退款、对账或查询
amount / currency与商户订单金额和币种核对
transactionEndingTime交易到达终态时间，可用于订单完成时间记录

查询状态处理建议：

status处理指引
AUTH_SUCCESS预授权成功，尚未完成最终扣款；如采用手动请款，请按业务流程继续发起请款。
SUCCESS支付成功，可以完成订单，并继续保留交易流水号用于退款、对账或后续查询。
FAILED支付失败，可提示买家重新支付或更换卡片。
PROCESSING支付处理中，继续等待异步通知或稍后主动查询确认最终结果。
CANCEL预授权撤销或人工审核拒绝，不可按成功处理。

预授权请款

如果原交易启用了手动 Capture，可参考 预授权请款 文档完成后续请款。

预授权撤销

如果原交易已完成预授权但尚未请款，可参考 预授权撤销 文档停止后续扣款。

退款

不同支付方式的退款能力不同，主要包括是否支持退款、退款有效期、是否支持部分退款以及是否支持多次部分退款。请参考 支付方式 页面或目标支付方式文档，确认具体退款能力。

支付成功后，如买家申请退款、商户取消已支付订单或需要退回部分或全部款项，您可以调用 申请退款 对原交易发起退款。

PingPongCheckout 支持的退款能力如下：

  • 支持全额退款，即一次性退回原交易可退金额。
  • 支持部分退款，即单次退款金额可小于原交易金额。
  • 支持多次部分退款，即同一笔交易可发起多笔退款；累计退款金额需小于等于原交易可退金额。

请参考 Refund 了解退款集成方案。具体发起退款的请求参数、响应字段和处理规则，请参考 申请退款；若需要确认退款处理结果，请参考 退款查询。

对账

如需了解账单生成规则与结算周期，可参考 结算周期和对账单；如需开通账单下载能力，可参阅 SFTP服务申请。

Home page PingPongCheckout
Copyright ©2015-2026 杭州乒乓智能技术有限公司 All Rights Reserved.