Non-hosted 本地支付

约 3806 字大约 13 分钟

2026-06-11

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

支持特性

下单支付（即时扣款）	预授权（先冻结后确认）	退款与部分退款	重新支付	Token凭证支付	线下扫码支付

支付流程

流程说明：

买家在商户下单页面选择本地支付方式，例如钱包、网银或银行转账。
商户前端将订单信息、支付方式、设备信息提交到商户服务端。
商户服务端调用下单并支付创建支付订单。
PingPongCheckout 返回同步响应；若交易需要买家继续操作，响应中会包含 action。
商户前端根据 action 推进买家继续完成支付。本文以下以跳转类本地支付场景说明接入步骤。
买家完成支付后，PingPongCheckout 通过 notificationUrl 推送支付结果。
如果商户长时间未收到异步通知，应主动调用交易查询确认最终状态。

注意

买家从本地支付页面跳回 payResultUrl，只表示买家回到了商户页面，不代表支付成功。订单落账、发货或发放权益必须以服务端异步通知或交易查询结果为准。

接口列表

Non-hosted 本地支付通常涉及以下接口和通知：

阶段	类型	文档	是否必接	用途
支付创建	API	下单并支付	必接	创建本地支付订单并获取支付推进参数
支付结果	通知	支付通知	必接	接收最终支付结果并更新商户订单状态
支付结果	API	交易查询	推荐	在通知延迟、未达或需要补偿确认时主动核验交易状态
退款	API	申请退款	按需	对成功支付的本地支付交易发起退款
退款	通知	退款通知	推荐	接收退款结果并更新退款状态
退款	API	退款查询	推荐	在通知延迟、未达或对账时主动确认退款状态

集成准备

开始开发前，请确认以下信息已经准备完成。

准备项	说明
账号信息	已获取 `clientId`、`accId`，并确认店铺状态可正常交易
支付方式	已开通本次需要接入的本地支付方式，并确认支持的国家、币种、金额范围和退款能力
签名能力	已根据签名规约完成请求签名，所有请求参数都需要参与签名
验签能力	已能对 PingPongCheckout 返回响应和异步通知中的 `sign` 执行验签
通知地址	已准备公网可访问的 `notificationUrl`，用于接收支付结果异步通知
结果页地址	已准备 `payResultUrl`，用于跳转类支付方式完成后回到商户页面
订单状态处理	已在商户系统内保存 `merchantTransactionId`、`requestId`、`transactionId` 和订单状态，并支持幂等更新

提示

不同本地支付方式可能要求额外字段，例如 customer、goods、billingAddress、shippingAddress 或特定 device.orderTerminal。请以目标支付方式页面和下单并支付参数表为准。

注意

notificationUrl 必须是公网可访问的完整地址，不能填写 localhost、127.0.0.1、内网 IP，也不要在 URL 后携带 query 参数。

集成步骤

请按以下步骤完成集成：

步骤 1：展示可用支付方式
步骤 2：创建支付订单
步骤 3：根据 action 推进支付
步骤 4：获取最终支付结果

步骤 1：展示可用支付方式

在买家下单页面展示本次需要集成的支付方式标识和名称，供买家根据自身需求和偏好选择。支付方式列表页面需要由您的前端自行实现。

展示支付方式时，建议至少基于以下条件过滤：

条件	处理建议
交易国家	使用订单国家或买家结账国家匹配 `tradeCountry`
交易币种	使用支付方式支持的 `currency`，金额精度参考交易币种
支付终端	根据 Web、WAP、App 等场景准备 `device.orderTerminal`
支付方式类型	将买家选择的支付方式写入 `paymentMethod.type`

步骤 2：创建支付订单

调用下单并支付创建支付订单。您需要收集买家的支付方式、订单信息、设备信息、支付金额等，并由商户服务端提交支付请求。

支付请求关键参数：

参数	必填	说明
`captureDelayHours`	M	本地支付固定使用 `0`，表示立即 capture
`amount`	M	交易金额
`currency`	M	ISO 4217 三位交易币种
`merchantTransactionId`	M	商户网站订单流水号，订单唯一标识
`requestId`	M	支付请求流水号，全局唯一
`tradeCountry`	M	交易国家，使用 ISO 3166-1 alpha-2 国家码
`shopperIP`	M	买家下单 IP
`paymentMethod.type`	M	买家选择的本地支付方式
`goods`	M	商品信息，至少包含 `goods[].name`、`goods[].unitPrice`、`goods[].number`、`goods[].imgUrl`
`device.orderTerminal`	M	下单终端。`01` 移动端浏览器（WAP）、`02` PC 端浏览器（WEB）、`04` iOS App、`05` Android App
`notificationUrl`	O	支付结果通知地址，建议传入
`payResultUrl`	C	跳转类支付完成后的商户结果页地址
`merchantUserId`	M	商户侧用户唯一 ID
`customer.email`	C	用户邮箱。实物类商户必传；部分支付方式也可能要求传入，请以具体支付方式要求为准
`customer.phone`	C	用户手机号。部分本地支付方式会要求传入，请以具体支付方式要求为准

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

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

{
  "captureDelayHours": 0,
  "amount": "1000",
  "currency": "THB",
  "merchantTransactionId": "ORDER_202606100001",
  "requestId": "REQ_202606100001",
  "tradeCountry": "TH",
  "shopperIP": "203.0.113.10",
  "merchantUserId": "USER_12345",
  "notificationUrl": "https://www.example.com/checkout/notify",
  "payResultUrl": "https://www.example.com/checkout/result",
  "paymentMethod": {
    "type": "TrueMoney Wallet"
  },
  "customer": {
    "email": "buyer@example.com",
    "phone": "66123456789"
  },
  "goods": [
    {
      "name": "Digital product",
      "description": "Order item",
      "sku": "SKU_001",
      "imgUrl": "https://www.example.com/product/SKU_001.png",
      "unitPrice": "1000",
      "number": "1",
      "virtualProduct": "Y"
    }
  ],
  "device": {
    "orderTerminal": "02"
  }
}

提示

为便于阅读，本文示例将 bizContent 展开为 JSON 对象。实际请求时，请按照下单并支付和签名规约的要求处理 bizContent 和签名。

响应关键字段：

参数	说明
`transactionId`	PingPong 交易流水号
`merchantTransactionId`	商户网站订单流水号
`requestId`	支付请求流水号
`status`	交易状态
`action`	支付推进参数，买家需要继续操作时返回

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

{
  "transactionId": "2026061050010001",
  "merchantTransactionId": "ORDER_202606100001",
  "requestId": "REQ_202606100001",
  "amount": "1000.000000",
  "currency": "THB",
  "status": "PROCESSING",
  "paymentMethod": {
    "type": "TrueMoney Wallet"
  },
  "action": {
    "type": "PAYMENT_REDIRECT_URL",
    "paymentRedirectUrl": "https://sandbox-acquirer-static.pingpongx.com/payment/apm.html?token=example"
  },
  "payResultUrl": "https://www.example.com/checkout/result",
  "transactionTime": "1781080205000",
  "captureDelayHours": 0
}

下单响应中的 status 可能返回以下值，请根据指引进行处理：

`status`	说明	处理指引
`SUCCESS`	同步响应已成功	商户服务端可以更新订单状态，但仍建议接收异步通知或查询结果做最终一致性校验
`FAILED`	支付失败	提示买家更换支付方式或重新发起支付
`PROCESSING`	支付处理中	若响应包含 `action`，继续执行步骤 3；同时等待异步通知或主动查询

步骤 3：根据 action 推进支付

当下单响应的 status 为 PROCESSING 且返回 action 时，前端需要根据 action 推进支付流程。本文以下以 action.type=PAYMENT_REDIRECT_URL 的跳转类支付方式为例说明。

`action.type`	关键字段	前端处理
`PAYMENT_REDIRECT_URL`	`action.paymentRedirectUrl`	将用户重定向到该地址，让用户在对应支付方式页面完成支付

支付推进注意事项

action.paymentRedirectUrl 是 PingPongCheckout 返回的完整支付推进链接。商户前端应直接使用服务端返回的原始值，不要自行拼接额外参数，也不要替换域名或路径。
建议在顶层页面、系统浏览器或系统级网页容器中打开支付推进链接；如果必须在 WKWebView 或 WebView 中承载，请提前完成真机验证。

商户服务端拿到 PingPong 返回的支付推进链接后，将该地址传递给前端，由商户前端跳转至支付方式页面。

以下为商户前端加载支付推进链接的示例代码：

Web

function redirectOnWeb(action) {
  if (action?.type !== 'PAYMENT_REDIRECT_URL') return;
  const paymentWindow = window.open(action.paymentRedirectUrl, '_blank');
  if (!paymentWindow) {
    window.location.assign(action.paymentRedirectUrl);
  }
}

WAP

function redirectOnWap(action) {
  if (action?.type !== 'PAYMENT_REDIRECT_URL') return;
  window.location.href = action.paymentRedirectUrl;
}

App (iOS)

// Objective-C 示例：
NSURL *url = [NSURL URLWithString:paymentRedirectUrl];
if (url) {
    [[UIApplication sharedApplication] openURL:url
                                       options:@{}
                             completionHandler:^(BOOL success) {
        if (!success) {
            // 引导买家重试或更换支付方式
        }
    }];
}

// Swift 示例：
guard let url = URL(string: paymentRedirectUrl) else { return }
UIApplication.shared.open(url, options: [:]) { success in
    if !success {
        // 引导买家重试或更换支付方式
    }
}

App (Android)

// Java 示例：
try {
    Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(paymentRedirectUrl));
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
    startActivity(intent);
} catch (Exception e) {
    e.printStackTrace();
}

// Kotlin 示例：
try {
    val intent = Intent(Intent.ACTION_VIEW, Uri.parse(paymentRedirectUrl))
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    startActivity(intent)
} catch (e: Exception) {
    e.printStackTrace()
}

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

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

如果通过异步通知获取结果，商户服务端应优先返回 HTTP 2xx 确认已接收，再根据通知中的 status 更新订单状态。

支付通知示例：

{
  "accId": "2023042011040310224447",
  "clientId": "2023042011040310224",
  "code": "000000",
  "description": "Transaction succeeded",
  "sign": "{{Sign}}",
  "signType": "SHA256",
  "bizContent": {
    "amount": "1000.000000",
    "currency": "THB",
    "transactionId": "2026061050010001",
    "merchantTransactionId": "ORDER_202606100001",
    "requestId": "REQ_202606100001",
    "notifyType": "RECHARGE",
    "paymentMethod": {
      "type": "TrueMoney Wallet"
    },
    "status": "SUCCESS",
    "transactionTime": "1781080205000",
    "transactionEndingTime": "1781080265000",
    "captureDelayHours": 0
  }
}

通知关键字段：

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

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

`status`	处理指引
`SUCCESS`	支付成功，可以进行发货、权益发放或订单完成处理
`FAILED`	支付失败，订单保持未支付或失败状态，可允许买家重新支付
`CANCEL`	支付取消或风控审核拒绝，订单不可按成功处理
`CLOSED`	订单已关闭，买家不能继续使用该订单支付

收到通知后，您无需对响应内容进行加签处理。但无论订单支付是否成功，均必须严格按照以下固定格式返回响应。

通知响应示例：

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

OK

支付后操作

以下内容介绍在支付流程推进后，如何通过服务端主动查询交易状态、处理退款及对账，帮助您实现稳定可靠的支付管理。

查询交易

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

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

{
  "merchantTransactionId": "ORDER_202606100001",
  "requestId": "REQ_202606100001"
}

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

{
  "transactionId": "2026061050010001",
  "merchantTransactionId": "ORDER_202606100001",
  "requestId": "REQ_202606100001",
  "amount": "1000.000000",
  "currency": "THB",
  "status": "SUCCESS",
  "paymentMethod": {
    "type": "TrueMoney Wallet"
  },
  "transactionTime": "1781080205000",
  "transactionEndingTime": "1781080265000"
}

查询响应关键字段：

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

交易查询状态处理建议：

`status`	处理指引
`SUCCESS`	支付成功，可以完成订单
`FAILED`	支付失败，可允许买家重新支付
`PROCESSING`	支付处理中，继续等待异步通知或稍后查询
`CANCEL`	支付取消或风控审核拒绝，不可按成功处理
`CLOSED`	订单已关闭，买家不能继续使用该订单支付

退款

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

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

PingPongCheckout 支持的退款能力如下：

支持全额退款。
支持部分退款。
支持多次退款，多次退款的总金额需小于等于原交易可退金额。

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

对账

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

无代码接入

开发者接入

PingPong 收银台

Native SDK

合规接入指南

Direct API