---
url: >-
https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/integrate/non-hosted-card/index.md
description: 说明国际信用卡 Server-to-Server 接入流程，适用于已具备 PCI 合规并需要高度定制支付页面的商户。
---
PingPong Non-hosted 本地支付是一款专为跨境交易打造的轻量级、高安全后端解决方案。通过标准化的 API 集成，商户可一站式接入全球丰富的本地支付方式（涵盖电子钱包、网银、银行卡等）。我们致力于为您扫除多通道对接的技术壁垒，在保障交易安全合规的前提下，为全球买家提供极致顺滑的支付体验，助力您的出海业务快速落地与规模化扩张。
本文介绍银行卡支付的 Server-to-Server 集成方案。该模式适合对支付流程有高定制化需求的商户。请注意，选择此模式需确保您的业务已通过 PCI 合规认证。
## 方案说明
在该模式下，买家始终在商户页面完成卡信息输入；当交易需要 3DS 验证时，再由商户前端根据同步响应跳转至发卡行挑战页面。该方案更适合希望自定义收银台体验、并具备 PCI-DSS 合规与前端支付链路建设能力的商户。
## 接入前提
1. 商户具备 PCI 资质，并通过 PingPongCheckout 验证。（PCI-DSS 请发送邮件附件到 `acquire-risk@pingpongx.com` 并抄送 `gig-tech-acq@pingpongx.com`）
2. 商户具备自行开发信用卡收银台页面的能力。
3. 商户已具备接入风控与 3DS 组件的前端能力。
:::danger 注意
采用国际信用卡支付（Non-hosted）方案时，商户需要自行保存、处理持卡人的信用卡信息，因此必须具备 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',
'noteBkgColor': '#E1F5FE',
'noteTextColor': '#01579B',
'noteBorderColor': '#0288D1',
'loopTextColor': '#0D47A1',
'activationBkgColor': '#B3E5FC',
'activationBorderColor': '#0277BD'
}
}}%%
sequenceDiagram
participant U as 👤 持卡人
participant Client as 💻 商户客户端
participant SPG as 🛡️ SafePayGuardJs
participant SSJ as 🔐 SecureShieldJs
participant Server as 🏪 商户服务端
participant PP as 🔄 PingPong服务端
participant Issuer as 🏦 发卡行
Note over U, Issuer: 🚀 Non-hosted 卡支付交互流程
Client->>SPG: 1. 初始化 SafePayGuardJs
Client->>SSJ: 2. 初始化 SecureShieldJs
U->>Client: 3. 输入卡号
Client->>SSJ: 4. triggerThreeDsInit（卡号变更/失焦）
SSJ->>PP: 5. 校验并获取风控参数
PP-->>SSJ: 6. 返回部分 jsGeneratedData / browserInfo
U->>Client: 7. 点击支付
Client->>SPG: 8. getGeneratedData()
Client->>SSJ: 9. getGeneratedData()
Client->>+Server: 10. 提交订单 + jsGeneratedData + browserInfo
Server->>+PP: 11. 调用下单并支付接口
PP->>+Issuer: 12. 请求支付处理
Issuer-->>-PP: 13. 返回支付结果
PP-->>-Server: 14. 返回同步响应
Server-->>-Client: 15. 返回 bizContent 结果
alt threeDContinue = false（无需3D）
Client->>U: 16. 展示支付结果
else threeDContinue = true（需要3D）
Client->>U: 17. 跳转 threeDRedirectUrl 进行挑战
Note over U, PP: 挑战完成后重定向至 payResultUrl
end
Note over U, Issuer: 🎯 流程结束
```
流程说明：
1. 商户前端在支付提交前完成风控与 3DS 参数采集。
2. 商户服务端调用 [下单并支付](/notes/zh/checkout/api/uniformly/) 创建国际卡支付订单。
3. PingPongCheckout 返回同步响应后，商户前端根据 `status` 和 `threeDContinue` 决定是否进入 3DS 挑战。
4. 若需要 3DS，商户前端应跳转 `threeDUnionParams.threeDRedirectUrl`；挑战完成后，PingPongCheckout 会将买家带回 `payResultUrl`。
5. 买家回跳至 `payResultUrl` 仅表示前端流程结束，不代表交易成功；最终结果必须以 [支付通知](/notes/zh/notify/payment/notify/) 或 [交易查询](/notes/zh/checkout/api/getOne/) 为准。
## 接口列表
国际信用卡支付（Non-hosted）通常涉及以下接口和通知：
| 阶段 |
类型 |
文档 |
是否必接 |
用途 |
| 支付创建 |
文档 |
Dynamic 3D Secure |
必读 |
完成风控与 3DS 组件接入，收集支付所需风控参数 |
| API |
下单并支付 |
必接 |
提交卡信息、风控参数与订单信息，创建支付订单 |
| 支付结果 |
通知 |
支付通知 |
必接 |
接收最终支付结果并更新商户订单状态 |
| API |
交易查询 |
推荐 |
在通知延迟、未达或需要核验结果时主动确认交易状态 |
| 退款 |
API |
申请退款 |
按需 |
对成功支付的国际卡交易发起退款 |
| 通知 |
退款通知 |
推荐 |
接收退款结果并更新退款状态 |
| API |
退款查询 |
推荐 |
在通知延迟、未达或对账时主动确认退款状态 |
| 预授权请款 / 撤销 |
API |
预授权请款 |
手动请款场景必接 |
对已预授权交易发起请款 |
| API |
预授权撤销 |
手动请款场景必接 |
对已预授权但未请款的交易发起撤销 |
| 通知 |
预授权请款通知 |
手动请款场景推荐 |
接收预授权请款结果 |
| 通知 |
预授权撤销异步通知 |
手动请款场景推荐 |
接收预授权撤销结果 |
## 集成步骤
请按以下步骤完成集成：
1. [准备风控与 3DS 参数并发起支付](#步骤-1-准备风控与-3ds-参数并发起支付)
2. [获取最终支付结果](#步骤-2-获取最终支付结果)
### 步骤 1：准备风控与 3DS 参数并发起支付
在调用 [下单并支付](/notes/zh/checkout/api/uniformly/) 前，商户前端需要先完成 SafePayGuardJs、SecureShieldJs 接入，并采集支付所需的 `browserInfo`、`jsGeneratedData` 等参数；随后由商户服务端调用下单并支付创建支付订单。前端组件初始化、`triggerThreeDsInit` 触发时机以及参数获取方式，请直接参考以下文档：
- [Dynamic 3D Secure](/notes/zh/risk/3ds/)
- [SafePayGuardJs 组件](/notes/zh/riskManger/safePayGuardJs/)
- [SecureShieldJs 组件](/notes/zh/riskManger/SecureShieldJs/)
::: warning 注意
如果您无法在前端页面嵌入相关 JS 组件，请先与商务或风控团队确认是否可评估其他 3DS 接入方案。
:::
支付请求中建议重点关注以下信息：
| 信息 | 说明 |
|:---|:---|
| `paymentMethod.type` | 卡品牌或卡组织，例如 `VISA`、`MasterCard`、`JCB`、`AmericanExpress`、`Discover`、`DinersClub`、`UnionPay`。支持的卡品牌可参考 [国际信用卡](/notes/zh/paymentMethods/InternationalCards/) 页面 |
| `paymentMethod.cardInfo` | 持卡人卡信息，包括卡号、有效期、CVV、持卡人姓名等 |
| `requestId` | 支付请求流水号，建议保持全局唯一 |
| `merchantTransactionId` | 商户订单流水号，用于关联商户订单与支付交易 |
| `merchantUserId` | 商户侧用户唯一标识，用于关联持卡人身份 |
| `goods` | 商品信息，用于补充交易上下文 |
| `browserInfo` | 3DS 组件收集的浏览器信息，支付请求中需要一并上送 |
| `jsGeneratedData` | 风控与 3DS 组件生成的交易安全参数，支付请求中需要一并上送 |
| `notificationUrl` | 用于接收最终支付结果的异步通知地址 |
| `payResultUrl` | 买家完成 3DS 或支付流程后回到商户页面的地址 |
| `device.orderTerminal` | 下单终端。`01` WAP、`02` Web、`04` iOS App、`05` Android App |
有关完整参数的更多信息，请参阅 [下单并支付](/notes/zh/checkout/api/uniformly/)。
支付请求示例（仅展示 `bizContent` 内容）：
```json:line-numbers:collapsed-lines=16
{
"captureDelayHours": "0",
"amount": "10",
"currency": "USD",
"requestId": "PMT-E46D6LAAKB1782628205616",
"merchantTransactionId": "PMT-E46D6LAAKB1782628205616",
"payResultUrl": "https://www.example.com/card/pay-result",
"payCancelUrl": "https://www.example.com/card/pay-cancel",
"notificationUrl": "https://www.example.com/card/pay-notify",
"language": "en",
"shopperIP": "222.126.52.23",
"merchantUserId": "888888888",
"threeDSRequestData": {
"executeThreeD": "Y"
},
"customer": {
"email": "buyer@example.com",
"phone": "19999999999"
},
"goods": [
{
"name": "商品名称mepsking1",
"description": "nndmmdnaido",
"unitPrice": "10",
"number": "1",
"virtualProduct": "Y",
"imgUrl": "https://yourOrderSample/001.png"
}
],
"device": {
"orderTerminal": "02"
},
"paymentMethod": {
"type": "scheme",
"cardInfo": {
"number": "4242424242424242",
"holderFirstName": "zhang",
"holderLastName": "san",
"expireMonth": "09",
"expireYear": "2030",
"cvv": "239"
}
},
"browserInfo": {
"acceptHeader": "content-type=application/x-www-form-urlencoded;accept=*/*;cache-control=no-cache;postman-token=cf489264-5378-4d5d-a86c-72c86a408c03;accept-encoding=gzip, deflate;content-length=588;connection=keep-alive;",
"colorDepth": "32",
"jetLag": "480",
"screenHeight": "1980",
"screenWidth": "1080",
"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"
},
"jsGeneratedData": {
"channel": "CyberSource",
"version": "1.0",
"correlationId": "af43fce6-70a9-4224-8583-bb106a96a12b",
"threeDInitTransId": "0b13e799-b802-4c85-adcc-a8a738ee0381",
"threeDSecureReferenceId": "af43fce6-70a9-4224-8583-bb106a96a12b"
}
}
```
::: warning 注意
`payResultUrl` 只用于买家完成前端流程后的回跳展示，不代表支付成功。涉及订单落账、发货或发放权益时，必须以服务端结果为准。
:::
下单并支付后，商户服务端会先收到同步响应。
同步响应示例（仅展示 `bizContent` 内容）：
```json:line-numbers:collapsed-lines=16
{
"issuerInfo": {},
"transactionTime": "1782702195000",
"requestId": "PMT-9T4IM1SCZ01782702194490",
"merchantTransactionId": "PMT-9T4IM1SCZ01782702194490",
"currency": "USD",
"exchangedAmount": "10",
"payResultUrl": "https://test-acquirerpay.pingpongx.com/qa/result.html",
"exchangedCurrency": "USD",
"threeDSInfo": {
"cavv": "",
"authenticationResult": "C",
"liabilityShift": "N",
"eci": "",
"authentication3DSecure": "e47ec035-fd9a-43f5-9787-36a7bd2216a9",
"specificationVersion": "2.2.0"
},
"amount": "10",
"authenticationInfo": {
"avsResult": "U",
"cvvResult": "Y",
"threeDSecure": "Y"
},
"cardInfo": {
"firstName": "zhang",
"isoCountryA2": "US",
"lastName": "san",
"lastFourDigits": "1112",
"cardLevel": "CLASSIC",
"paymentBrand": "VISA",
"cardType": "DEBIT",
"issuringBank": "VISA PRODUCTION SUPPORT CLIENT BID 1",
"ipCountry": "PH",
"firstSixDigits": "401200",
"isoCountry": "UNITED STATES"
},
"threeDUnionParams": {
"acsUrl": "https://cas.client.cardinaltrusted.com/centinelapi/V2/Cruise/StepUp",
"threeDRedirectUrl": "https://sandbox-acquirer-static.pingpongx.com/payment/threeDs.html?code=eyJhY3NVcmwiOiJodHRwczovL2Nhcy5jbGllbnQuY2FyZGluYWx0cnVzdGVkLmNvbS9jZW50aW5lbGFwaS9WMi9DcnVpc2UvU3RlcFVwIiwiYXV0aEFjY2Vzc1Rva2VuIjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnFkR2tpT2lJeVpXUmlNMlpqWWkwNFkyTTJMVFF5T0RrdFltWm1PUzFtTUdaa05qTmhZMlZoWkRZaUxDSnBZWFFpT2pFM09ESTNNREl4T1Rjc0ltbHpjeUk2SWpWa05XWXlNMlJsWVdaaE9EQmtNVGxrTURrNVl6WTNOQ0lzSW1WNGNDSTZNVGM0TWpjd016azVOeXdpVDNKblZXNXBkRWxrSWpvaU5qSXlPREZoTXpSaE1HTXhaakF6WVRFME5qbGxOV0V3SWl3aVVHRjViRzloWkNJNmV5SkJRMU5WY213aU9pSm9kSFJ3Y3pvdkwyTmhjeTVqYkdsbGJuUXVZMkZ5WkdsdVlXeDBjblZ6ZEdWa0xtTnZiUzl0WlhKamFHRnVkR0ZqY3k5MGFISmxaV1J6TDNZeUwyTnlaWEVpTENKUVlYbHNiMkZrSWpvaVpYbEtkRnBZVG5wWlYyUnNWa2hzZDFwVFNUWkphMDVUV2xoRmFVeERTblJhV0U1NldWZGtiRlp0Vm5sak1teDJZbWxKTmtscVNYVk5hVFIzU1dsM2FXUkhhSGxhVjFaRlZURk9iR051V214amJGSjVXVmMxZWxOVlVXbFBhVXBzVGtSa2JGbDZRWHBPVXpGdFdrUnNhRXhVVVhwYWFsVjBUMVJqTkU1NU1IcE9iVVV6V1cxUmVVMXFSVEpaVkd0cFRFTkthRmt6VGxWamJVWjFZekJzUlVscWIybFBWR040VFhwQk1FMHlXWFJPVjFwb1dXa3dNRmw2VW14TVYwa3lUVlJGZEUxNlVtcE9SRWw0VGxSSk1rNTZWbXhKYVhkcFdUSm9hR0pIZUd4aWJXUnNWakpzZFZwSE9UTlZNbXcyV2xOSk5rbHFRWGxKYmpBaUxDSlVjbUZ1YzJGamRHbHZia2xrSWpvaWIydG5VRXBNZDJGMVJsSkNRWFpPVFVkalp6SWlmU3dpVDJKcVpXTjBhV1o1VUdGNWJHOWhaQ0k2ZEhKMVpTd2lVbVYwZFhKdVZYSnNJam9pYUhSMGNITTZMeTl6WVc1a1ltOTRMV0ZqY1hWcGNtVnlMWEJoZVcxbGJuUXVjR2x1WjNCdmJtZDRMbU52YlM5MGFISmxaVVJUTDBONVltVnlVMjkxY21ObEwzSmxaR2x5WldOMEwyTlFaRTR4ZGs1MU9EWXdlVkEwWkRkdGR6Wm1UR3BIY1dwbE9YTkJNRkJxWDE5UGRHOWFUakoxWjFWcWVVcHJaWHBhWjI0MU1ubDJVVWRuTWs1dlIzQllRMjVmVG5ONE5HaHJYM05wV1hoTGRVVnFSRmhpYkhWWk0xcFVZVXhOUnpOVVRFY3hVeTFRTjJONFpFWmxWVmhHVTNsV1NXSkRUMmR4WkZCTE9XNTVSMHAzY2todVZuaHhhRmd4ZGswelltMTVTM0ZOVVQwOUluMC5aSnU0NGhCTVp4M2xCYV9fcEx6a3U4T3ZFcTdyOUZPNFBGUi1QSTl3WGlVIiwiY2hhbm5lbCI6IkNZQlMifQ==",
"threeDChannel": "CyberSource",
"threeDResult": "{\"ACSUrl\":\"https://cas.client.cardinaltrusted.com/centinelapi/V2/Cruise/StepUp\",\"acsTransId\":\"9713043f-5fab-4c4e-b611-34c42152675e\",\"authAccessToken\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyZWRiM2ZjYi04Y2M2LTQyODktYmZmOS1mMGZkNjNhY2VhZDYiLCJpYXQiOjE3ODI3MDIxOTcsImlzcyI6IjVkNWYyM2RlYWZhODBkMTlkMDk5YzY3NCIsImV4cCI6MTc4MjcwMzk5NywiT3JnVW5pdElkIjoiNjIyODFhMzRhMGMxZjAzYTE0NjllNWEwIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL2Nhcy5jbGllbnQuY2FyZGluYWx0cnVzdGVkLmNvbS9tZXJjaGFudGFjcy90aHJlZWRzL3YyL2NyZXEiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUpsTkRkbFl6QXpOUzFtWkRsaExUUXpaalV0T1RjNE55MHpObUUzWW1ReU1qRTJZVGtpTENKaFkzTlVjbUZ1YzBsRUlqb2lPVGN4TXpBME0yWXROV1poWWkwMFl6UmxMV0kyTVRFdE16UmpOREl4TlRJMk56VmxJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoib2tnUEpMd2F1RlJCQXZOTUdjZzIifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9zYW5kYm94LWFjcXVpcmVyLXBheW1lbnQucGluZ3Bvbmd4LmNvbS90aHJlZURTL0N5YmVyU291cmNlL3JlZGlyZWN0L2NQZE4xdk51ODYweVA0ZDdtdzZmTGpHcWplOXNBMFBqX19PdG9aTjJ1Z1VqeUprZXpaZ241Mnl2UUdnMk5vR3BYQ25fTnN4NGhrX3NpWXhLdUVqRFhibHVZM1pUYUxNRzNUTEcxUy1QN2N4ZEZlVVhGU3lWSWJDT2dxZFBLOW55R0p3ckhuVnhxaFgxdk0zYm15S3FNUT09In0.ZJu44hBMZx3lBa__pLzku8OvEq7r9FO4PFR-PI9wXiU\",\"authenticationTransactionId\":\"okgPJLwauFRBAvNMGcg2\",\"cardEnrolled\":\"Y\",\"channelName\":\"CyberSource\",\"dsTransId\":\"2d5fb588-1734-4bed-b8eb-68df98d96ff8\",\"paReq\":\"eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJlNDdlYzAzNS1mZDlhLTQzZjUtOTc4Ny0zNmE3YmQyMjE2YTkiLCJhY3NUcmFuc0lEIjoiOTcxMzA0M2YtNWZhYi00YzRlLWI2MTEtMzRjNDIxNTI2NzVlIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0\",\"threeDRequestId\":\"0b13e799-b802-4c85-adcc-a8a738ee0381\",\"threeDServerTransactionId\":\"e47ec035-fd9a-43f5-9787-36a7bd2216a9\",\"version\":\"2.2.0\"}",
"threeDContinue": "true"
},
"transactionId": "26062900000150963354",
"threeDContinue": "true",
"paymentMethod": {
"type": "scheme"
},
"captureDelayHours": 0,
"status": "PROCESSING"
}
```
响应关键字段：
| 字段 | 说明 |
|:---|:---|
| `status` | 交易当前状态，可能为 `SUCCESS`、`FAILED` 或 `PROCESSING` |
| `threeDContinue` | 是否需要继续进入 3DS 挑战流程 |
| `threeDUnionParams.threeDRedirectUrl` | 当需要 3DS 挑战时，商户前端应跳转的地址 |
| `transactionId` | PingPong 交易流水号 |
| `requestId` | 支付请求流水号 |
订单的授权结果需根据 `status` 的值进行判断：`SUCCESS` 和 `FAILED` 表示支付终态结果，`PROCESSING` 表示处理中。
下表展示了同步响应中 `status` 字段可能返回的值，请根据指引进行处理：
| `status` | 信息 | 后续操作 |
|:---|:---|:---|
| `SUCCESS` | 授权支付成功。 | 当前无需继续跳转 3DS。请保存 `transactionId`，并继续通过异步通知或交易查询确认最终支付结果。 |
| `FAILED` | 授权支付失败。 | 请提示买家重试或更换卡片。 |
| `PROCESSING` | 交易处理中。 | 如果返回了 `threeDUnionParams.threeDRedirectUrl`，说明需要继续完成 3DS 挑战，商户前端按需跳转至该地址；如果未返回可跳转地址，请继续等待异步通知，或主动调用交易查询确认结果。 |
#### 跳转3DS认证页面（可选）
这是一个可选步骤，仅当同步响应中的 `threeDContinue=true` 时才需要执行。此时说明买家仍需完成 3DS 挑战，同步响应中的 `threeDUnionParams` 字段内容可能如下：
```json:line-numbers:collapsed-lines=3
{
"acsUrl": "https://cas.client.cardinaltrusted.com/centinelapi/V2/Cruise/StepUp",
"threeDRedirectUrl": "https://sandbox-acquirer-static.pingpongx.com/payment/threeDs.html?code=eyJhY3NVcmwiOiJodHRwczovL2Nhcy5jbGllbnQuY2FyZGluYWx0cnVzdGVkLmNvbS9jZW50aW5lbGFwaS9WMi9DcnVpc2UvU3RlcFVwIiwiYXV0aEFjY2Vzc1Rva2VuIjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnFkR2tpT2lJeVpXUmlNMlpqWWkwNFkyTTJMVFF5T0RrdFltWm1PUzFtTUdaa05qTmhZMlZoWkRZaUxDSnBZWFFpT2pFM09ESTNNREl4T1Rjc0ltbHpjeUk2SWpWa05XWXlNMlJsWVdaaE9EQmtNVGxrTURrNVl6WTNOQ0lzSW1WNGNDSTZNVGM0TWpjd016azVOeXdpVDNKblZXNXBkRWxrSWpvaU5qSXlPREZoTXpSaE1HTXhaakF6WVRFME5qbGxOV0V3SWl3aVVHRjViRzloWkNJNmV5SkJRMU5WY213aU9pSm9kSFJ3Y3pvdkwyTmhjeTVqYkdsbGJuUXVZMkZ5WkdsdVlXeDBjblZ6ZEdWa0xtTnZiUzl0WlhKamFHRnVkR0ZqY3k5MGFISmxaV1J6TDNZeUwyTnlaWEVpTENKUVlYbHNiMkZrSWpvaVpYbEtkRnBZVG5wWlYyUnNWa2hzZDFwVFNUWkphMDVUV2xoRmFVeERTblJhV0U1NldWZGtiRlp0Vm5sak1teDJZbWxKTmtscVNYVk5hVFIzU1dsM2FXUkhhSGxhVjFaRlZURk9iR051V214amJGSjVXVmMxZWxOVlVXbFBhVXBzVGtSa2JGbDZRWHBPVXpGdFdrUnNhRXhVVVhwYWFsVjBUMVJqTkU1NU1IcE9iVVV6V1cxUmVVMXFSVEpaVkd0cFRFTkthRmt6VGxWamJVWjFZekJzUlVscWIybFBWR040VFhwQk1FMHlXWFJPVjFwb1dXa3dNRmw2VW14TVYwa3lUVlJGZEUxNlVtcE9SRWw0VGxSSk1rNTZWbXhKYVhkcFdUSm9hR0pIZUd4aWJXUnNWakpzZFZwSE9UTlZNbXcyV2xOSk5rbHFRWGxKYmpBaUxDSlVjbUZ1YzJGamRHbHZia2xrSWpvaWIydG5VRXBNZDJGMVJsSkNRWFpPVFVkalp6SWlmU3dpVDJKcVpXTjBhV1o1VUdGNWJHOWhaQ0k2ZEhKMVpTd2lVbVYwZFhKdVZYSnNJam9pYUhSMGNITTZMeTl6WVc1a1ltOTRMV0ZqY1hWcGNtVnlMWEJoZVcxbGJuUXVjR2x1WjNCdmJtZDRMbU52YlM5MGFISmxaVVJUTDBONVltVnlVMjkxY21ObEwzSmxaR2x5WldOMEwyTlFaRTR4ZGs1MU9EWXdlVkEwWkRkdGR6Wm1UR3BIY1dwbE9YTkJNRkJxWDE5UGRHOWFUakoxWjFWcWVVcHJaWHBhWjI0MU1ubDJVVWRuTWs1dlIzQllRMjVmVG5ONE5HaHJYM05wV1hoTGRVVnFSRmhpYkhWWk0xcFVZVXhOUnpOVVRFY3hVeTFRTjJONFpFWmxWVmhHVTNsV1NXSkRUMmR4WkZCTE9XNTVSMHAzY2todVZuaHhhRmd4ZGswelltMTVTM0ZOVVQwOUluMC5aSnU0NGhCTVp4M2xCYV9fcEx6a3U4T3ZFcTdyOUZPNFBGUi1QSTl3WGlVIiwiY2hhbm5lbCI6IkNZQlMifQ==",
"threeDChannel": "CyberSource",
"threeDResult": "{\"ACSUrl\":\"https://cas.client.cardinaltrusted.com/centinelapi/V2/Cruise/StepUp\",\"acsTransId\":\"9713043f-5fab-4c4e-b611-34c42152675e\",\"authAccessToken\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyZWRiM2ZjYi04Y2M2LTQyODktYmZmOS1mMGZkNjNhY2VhZDYiLCJpYXQiOjE3ODI3MDIxOTcsImlzcyI6IjVkNWYyM2RlYWZhODBkMTlkMDk5YzY3NCIsImV4cCI6MTc4MjcwMzk5NywiT3JnVW5pdElkIjoiNjIyODFhMzRhMGMxZjAzYTE0NjllNWEwIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovL2Nhcy5jbGllbnQuY2FyZGluYWx0cnVzdGVkLmNvbS9tZXJjaGFudGFjcy90aHJlZWRzL3YyL2NyZXEiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUpsTkRkbFl6QXpOUzFtWkRsaExUUXpaalV0T1RjNE55MHpObUUzWW1ReU1qRTJZVGtpTENKaFkzTlVjbUZ1YzBsRUlqb2lPVGN4TXpBME0yWXROV1poWWkwMFl6UmxMV0kyTVRFdE16UmpOREl4TlRJMk56VmxJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoib2tnUEpMd2F1RlJCQXZOTUdjZzIifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9zYW5kYm94LWFjcXVpcmVyLXBheW1lbnQucGluZ3Bvbmd4LmNvbS90aHJlZURTL0N5YmVyU291cmNlL3JlZGlyZWN0L2NQZE4xdk51ODYweVA0ZDdtdzZmTGpHcWplOXNBMFBqX19PdG9aTjJ1Z1VqeUprZXpaZ241Mnl2UUdnMk5vR3BYQ25fTnN4NGhrX3NpWXhLdUVqRFhibHVZM1pUYUxNRzNUTEcxUy1QN2N4ZEZlVVhGU3lWSWJDT2dxZFBLOW55R0p3ckhuVnhxaFgxdk0zYm15S3FNUT09In0.ZJu44hBMZx3lBa__pLzku8OvEq7r9FO4PFR-PI9wXiU\",\"authenticationTransactionId\":\"okgPJLwauFRBAvNMGcg2\",\"cardEnrolled\":\"Y\",\"channelName\":\"CyberSource\",\"dsTransId\":\"2d5fb588-1734-4bed-b8eb-68df98d96ff8\",\"paReq\":\"eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJlNDdlYzAzNS1mZDlhLTQzZjUtOTc4Ny0zNmE3YmQyMjE2YTkiLCJhY3NUcmFuc0lEIjoiOTcxMzA0M2YtNWZhYi00YzRlLWI2MTEtMzRjNDIxNTI2NzVlIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0\",\"threeDRequestId\":\"0b13e799-b802-4c85-adcc-a8a738ee0381\",\"threeDServerTransactionId\":\"e47ec035-fd9a-43f5-9787-36a7bd2216a9\",\"version\":\"2.2.0\"}",
"threeDContinue": "true"
}
```
如果需要进入 3DS 挑战流程，请根据不同终端跳转 `threeDRedirectUrl`：
::: warning 3DS 跳转注意事项
- `threeDRedirectUrl` 是 PingPongCheckout 返回的完整跳转地址。商户前端应直接使用服务端返回的原始值，将其作为不透明链接处理，不要自行拼接额外参数，也不要先 `decode` 再重新 `encode`，以免导致 3DS 页面无法正常打开。
- 不要依赖固定域名、固定路径或静态规则识别 3DS 挑战页，应始终以服务端返回的 `threeDRedirectUrl` 为准。
- 建议在顶层页面打开 3DS 挑战，不要在 `iframe` 中承载挑战页，避免跳转、输入或回跳异常。
- App 端建议优先使用系统浏览器或系统级网页容器；如果必须使用 `WKWebView` 或 `WebView`，请提前完成真机验证，确认跳转、回退、键盘和页面缩放行为正常。
:::
::: tabs
@tab Web
```js
function redirectThreeDOnWeb(threeDRedirectUrl) {
if (!threeDRedirectUrl) return;
window.location.assign(threeDRedirectUrl);
}
```
@tab WAP
```js
function redirectThreeDOnWap(threeDRedirectUrl) {
if (!threeDRedirectUrl) return;
window.location.href = threeDRedirectUrl;
}
```
@tab App (iOS)
建议优先拉起系统默认浏览器打开 3DS 页面：
```objc
// Objective-C 示例：
NSURL *url = [NSURL URLWithString:urlString];
if (url) {
[[UIApplication sharedApplication] openURL:url
options:@{}
completionHandler:^(BOOL success) {
if (!success) {
// 引导买家重试或更换卡片
}
}];
}
// Swift 示例：
guard let url = URL(string: urlString) else { return }
UIApplication.shared.open(url, options: [:]) { success in
if !success {
// 引导买家重试或更换卡片
}
}
```
如果业务上必须在 `WKWebView` 中加载，请直接使用服务端返回的原始地址，确保只编码一次。例如，若链接中已经包含 `%20`，不要再次编码成 `%2520`：
```swift
guard let url = URL(string: threeDRedirectUrl) else { return }
let request = URLRequest(url: url)
webView.load(request)
```
@tab App (Android)
建议优先拉起系统默认浏览器或 Chrome Custom Tabs 打开 3DS 页面：
```java
// Java 示例：
try {
Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(threeDRedirectUrl));
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
startActivity(intent);
} catch (Exception e) {
e.printStackTrace();
}
// Kotlin 示例：
try {
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(threeDRedirectUrl))
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
startActivity(intent)
} catch (e: Exception) {
e.printStackTrace()
}
```
如果业务上必须在 `WebView` 中加载，建议至少开启以下配置，避免部分发卡行 3DS 页面在 Android 手机上以接近 PC 页的尺寸渲染：
```java
WebSettings webSettings = webView.getSettings();
webSettings.setJavaScriptEnabled(true);
webSettings.setLoadWithOverviewMode(true);
webSettings.setUseWideViewPort(true);
webView.loadUrl(threeDRedirectUrl);
```
:::
::: tip 提示
`threeDRedirectUrl` 是 PingPongCheckout 提供的 3DS 中间页地址。买家访问该地址后，页面会自动继续跳转至发卡行 3DS 挑战页；挑战完成后，PingPongCheckout 会将买家带回您在支付请求中设置的 `payResultUrl`。
:::
### 步骤 2：获取最终支付结果
国际卡支付的最终结果，建议优先通过服务端异步通知确认。若异步通知延迟、未达、回调处理异常，或商户在买家回跳后需要立即核验结果，可在支付后操作中主动调用交易查询。交易查询的完整集成方案请参考 [支付后操作 > 查询交易](#查询交易)。
支付通知示例（仅展示 `bizContent` 内容）：
```json:line-numbers:collapsed-lines=16
{
"exchangedCurrency": "USD",
"amount": "10.000000",
"authenticationInfo": {
"avsResult": "Unknown",
"cvvResult": "Y",
"threeDSecure": "Y"
},
"cardInfo": {
"firstName": "zhang",
"isoCountryA2": "US",
"lastName": "san",
"lastFourDigits": "1096",
"cardLevel": "CLASSIC",
"paymentBrand": "Mastercard",
"cardType": "CREDIT",
"issuringBank": "",
"ipCountry": "CN",
"firstSixDigits": "520000",
"isoCountry": "UNITED STATES"
},
"issuerInfo": {
"issuerResultMsg": "Successful approval/completion",
"issuerResultCode": "00"
},
"threeDSecure": "Y",
"transactionTime": "1782794170000",
"transactionId": "26062900000150950001",
"notifyType": "RECHARGE",
"requestId": "PMT-K9X4L2N7QV1782794167312",
"merchantTransactionId": "PMT-K9X4L2N7QV1782794167312",
"paymentMethod": {
"type": "Mastercard"
},
"currency": "USD",
"exchangedAmount": "10.000000",
"captureDelayHours": 0,
"status": "SUCCESS"
}
```
通知关键字段：
| 参数 | 说明 | 处理建议 |
|:---|:---|:---|
| `notifyType` | 通知类型，支付通知固定为 `RECHARGE` | 用于区分通知事件类型 |
| `transactionId` | PingPong 交易流水号 | 保存并用于后续查询、退款、对账 |
| `merchantTransactionId` | 商户网站订单流水号 | 用于定位商户订单 |
| `requestId` | 支付请求流水号 | 用于定位本次支付请求 |
| `amount` / `currency` | 交易金额和币种 | 必须与商户订单金额、币种核对 |
| `status` | 支付结果状态 | 按状态更新商户订单 |
通知中的 `status` 建议按以下方式处理：
| `status` | 处理指引 |
|:---|:---|
| `SUCCESS` | 支付成功，可以进行发货、权益发放或订单完成处理。 |
| `FAILED` | 支付失败，订单保持未支付或失败状态，可允许买家重新支付。 |
| `AUTH_SUCCESS` | 预授权成功，尚未完成最终扣款；如采用手动请款，请按业务流程继续发起请款。 |
| `CANCEL` | 预授权撤销或人工审核拒绝，不可按成功处理。 |
收到通知后，您无需对响应内容进行加签处理。但无论订单支付是否成功，均必须严格按照以下固定格式返回响应。商户服务端应优先返回 HTTP `2xx` 确认已接收。
通知响应示例：
```http
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: 2
OK
```
## 支付后操作
以下内容介绍国际卡支付完成后，如何通过服务端主动查询交易状态，以及如何继续处理预授权请款、预授权撤销、退款和对账。
### 查询交易
当买家从支付页面跳回商户结果页、异步通知延迟、未达、回调处理异常，或商户需要执行补偿任务时，可以调用 [交易查询](/notes/zh/checkout/api/getOne/) 获取交易最新状态。
交易查询请求示例（仅展示 `bizContent` 内容）：
```json
{
"merchantTransactionId": "PMT-WWK4L1L2Q11782466163266"
}
```
交易查询响应示例（仅展示 `bizContent` 内容）：
```json:line-numbers:collapsed-lines=16
{
"threeDSecure": "",
"resultCode": "000000",
"transactionTime": "1782466164000",
"requestId": "PMT-WWK4L1L2Q11782466163266",
"merchantTransactionId": "PMT-WWK4L1L2Q11782466163266",
"currency": "USD",
"exchangedAmount": "10.000000",
"resultMessage": "Transaction succeeded",
"exchangedCurrency": "USD",
"amount": "10.000000",
"authenticationInfo": {
"avsResult": "U",
"cvvResult": "Y",
"threeDSecure": "N"
},
"cardInfo": {
"isoCountryA2": "MY",
"lastFourDigits": "1096",
"cardLevel": "STANDARD",
"paymentBrand": "Mastercard",
"cardType": "CREDIT",
"issuringBank": "PUBLIC BANK BERHAD",
"ipCountry": "CN",
"firstSixDigits": "520000",
"isoCountry": "MALAYSIA"
},
"transactionEndingTime": "1782466168000",
"transactionId": "26062600000050931108",
"token": "919110fb49484e1760b3a206d26909bc4c42d09eef818d113e4b20a83cdc11fb",
"paymentMethod": {
"type": "scheme"
},
"captureDelayHours": 0,
"status": "SUCCESS"
}
```
查询响应关键字段：
| 参数 | 处理方式 |
|:---|:---|
| `resultCode` | `000000` 表示查询请求成功；查询请求成功不等于支付成功 |
| `status` | 商户订单状态应以该字段为准 |
| `transactionId` | 保存为 PingPong 交易流水号，用于后续退款、对账或查询 |
| `amount` / `currency` | 与商户订单金额和币种核对 |
| `transactionEndingTime` | 交易到达终态时间，可用于订单完成时间记录 |
查询状态处理建议：
| `status` | 处理指引 |
|:---|:---|
| `AUTH_SUCCESS` | 预授权成功，尚未完成最终扣款；如采用手动请款，请按业务流程继续发起请款。 |
| `SUCCESS` | 支付成功，可以完成订单，并继续保留交易流水号用于退款、对账或后续查询。 |
| `FAILED` | 支付失败，可提示买家重新支付或更换卡片。 |
| `PROCESSING` | 支付处理中，继续等待异步通知或稍后主动查询确认最终结果。 |
| `CANCEL` | 预授权撤销或人工审核拒绝，不可按成功处理。 |
### 预授权请款
如果原交易启用了手动 Capture，可参考 [预授权请款](/notes/zh/integrate/modify/Capture/) 文档完成后续请款。
### 预授权撤销
如果原交易已完成预授权但尚未请款，可参考 [预授权撤销](/notes/zh/integrate/modify/Void/) 文档停止后续扣款。
### 退款
不同支付方式的退款能力不同，主要包括是否支持退款、退款有效期、是否支持部分退款以及是否支持多次部分退款。请参考 [支付方式](/notes/zh/paymentMethods/overview/) 页面或目标支付方式文档，确认具体退款能力。
支付成功后，如买家申请退款、商户取消已支付订单或需要退回部分或全部款项，您可以调用 [申请退款](/notes/zh/checkout/api/modifications/refund/) 对原交易发起退款。
PingPongCheckout 支持的退款能力如下：
- 支持全额退款，即一次性退回原交易可退金额。
- 支持部分退款，即单次退款金额可小于原交易金额。
- 支持多次部分退款，即同一笔交易可发起多笔退款；累计退款金额需小于等于原交易可退金额。
请参考 [Refund](/notes/zh/integrate/modify/Refund/) 了解退款集成方案。具体发起退款的请求参数、响应字段和处理规则，请参考 [申请退款](/notes/zh/checkout/api/modifications/refund/)；若需要确认退款处理结果，请参考 [退款查询](/notes/zh/checkout/api/getRefund/)。
### 对账
如需了解账单生成规则与结算周期，可参考 [结算周期和对账单](/notes/zh/reconciliation/settlementCycle/)；如需开通账单下载能力，可参阅 [SFTP服务申请](/notes/zh/reconciliation/transactionStatementDownload/)。