API 端点地址

约 2012 字大约 7 分钟

View as Markdown

2025-10-31

本文档说明 PingPongCheckout 提供的各个站点的 API 端点地址配置。根据您的业务场景和集成方式，选择对应的 API 域名进行接入。

站点架构概览

PingPongCheckout 提供三类站点服务：

在线业务：用于在线支付场景，支持收银台和 S2S 模式
- 美国主体使用美国站点（US）
- 欧洲以外地区使用欧洲站点（FRA）
- 使用SG站点前提申请。
终端业务：用于终端支付场景，支持线下支付设备集成
- 请联系技术支持获取终端业务接入信息，确认站点选择。
商户后台：用于商户管理、订单查询、数据统计等后台操作
- 根据站点选择,使用对应的商户后台域名。

站点分布

PingPongCheckout 在全球部署了三个主要站点，商户根据主体注册地选择对应站点：

站点代码	站点名称	地理位置	商户主体注册地	在线支付	POS终端支付
FRA	法兰克福站点	欧洲-德国	欧洲及其他地区注册商户	使用欧洲站点	请咨询技术支持
SG	新加坡站点	亚太-新加坡	亚太地区注册商户	使用欧洲站点	请咨询技术支持
US	美国站点	北美-美国	北美地区注册商户	使用美国站点	请咨询技术支持

一、线上收单 API 域名

线上收单 API 用于在线支付场景，包括收银台模式（Checkout）和服务器对服务器模式（S2S）。

沙箱环境

用于开发和测试阶段，所有站点共用统一的沙箱环境。

🧪 沙箱环境 API
https://sandbox-acquirer-payment.pingpongx.com

生产环境

根据商户主体注册地，选择对应的生产环境域名：

站点	API 域名	商户主体注册地
FRA 站点	`https://acquirer-payment.pingpongx.com`	欧洲及其他地区注册商户
SG 站点	`https://acquirer-payment-checkout-sg.pingpongx.com`	使用前请联系技术支持
US 站点	`https://acquirer-payment-checkout-us.pingpongx.com`	北美地区注册商户

前端资源

JavaScript SDK/onePage SDK 同样遵循分区原则，必须与 API 使用相同的站点。SDK 用于前端页面集成收银台组件。

沙箱环境

🧪 沙箱环境 JS-SDK
<!-- 所有站点共用沙箱环境 -->
<script type="module" src="https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/sandbox/pp-checkout.js"></script>

生产环境

SDK 类型	FRA 站点 CDN 地址	SG 站点 CDN 地址	详细文档
JavaScript SDK	`https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/pp-checkout.js`	`https://pay-cdn.pingpongx.com/production-sg/static/pp-checkout/pp-checkout.js`	SDK 接入指南
onePage SDK	`https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/pp-checkout.js`	`https://pay-cdn.pingpongx.com/production-sg/static/pp-checkout/pp-checkout.js`	onePage 接入指南
SDK Elements	`https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/pp-checkout.js`	`https://pay-cdn.pingpongx.com/production-sg/static/pp-checkout/pp-checkout.js`	Elements 架构设计

CDN 选择原则

前端 SDK 的 CDN 地址必须与后端 API 选择的站点保持一致。

使用说明

站点选择原则

商户应根据主体注册地选择对应站点：

欧洲注册商户：使用 FRA 站点
亚太注册商户：优先使用 FRA 站点，如果申请使用 SG 站点，请联系技术支持
北美注册商户：使用 US 站点
其他地区注册商户：使用 FRA 站点

集成示例

API 集成示例

config/api-endpoints.js
// 根据商户所在地区配置 API 域名
const API_BASE_URLS = {
  sandbox: 'https://sandbox-acquirer-payment.pingpongx.com',
  'prod-fra': 'https://acquirer-payment.pingpongx.com',
  'prod-sg': 'https://acquirer-payment-checkout-sg.pingpongx.com',
  'prod-us': 'https://acquirer-payment-checkout-us.pingpongx.com'
};

// 选择对应的环境
const environment = 'prod-fra'; // 或 'prod-sg', 'prod-us'
const baseURL = API_BASE_URLS[environment];

// API 请求示例
const apiUrl = `${baseURL}/v4/payment/prePay`;

JS-SDK 集成示例

sdk/dynamic-loader.js
// 根据后端选择的域名配置 JS-SDK CDN 地址
const SDK_URLS = {
  sandbox: 'https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/sandbox/pp-checkout.js',
  'prod-fra': 'https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/pp-checkout.js',
  'prod-sg': 'https://pay-cdn.pingpongx.com/production-sg/static/pp-checkout/pp-checkout.js'
};

// 动态加载对应站点的 SDK
const environment = 'prod-fra'; // 根据上述说明选择后端域名，和后端环境匹配
const sdkURL = SDK_URLS[environment];

// 动态创建 script 标签加载 SDK
const script = document.createElement('script');
script.type = 'module';
script.src = sdkURL;
document.head.appendChild(script);

// SDK 加载完成后使用
script.onload = function() {
  // SDK 已加载，可以初始化收银台组件
  const checkout = document.createElement('pp-checkout');
  checkout.setAttribute('locale', 'zh');
  document.body.appendChild(checkout);
};

完整集成示例

src/env.js
// 配置类 - 统一管理 API 和 SDK 配置
class PaymentConfig {
  constructor(region = 'fra', environment = 'production') {
    this.region = region; // 'fra', 'sg', 'us'
    this.environment = environment; // 'production', 'sandbox'
  }

  // 获取 API 基础 URL
  getAPIBaseURL() {
    if (this.environment === 'sandbox') {
      return 'https://sandbox-acquirer-payment.pingpongx.com';
    }

    const urls = {
      'fra': 'https://acquirer-payment.pingpongx.com',
      'sg': 'https://acquirer-payment-checkout-sg.pingpongx.com',
      'us': 'https://acquirer-payment-checkout-us.pingpongx.com'
    };

    return urls[this.region];
  }

  // 获取 JS-SDK URL
  getSDKURL() {
    if (this.environment === 'sandbox') {
      return 'https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/sandbox/pp-checkout.js';
    }

    const urls = {
      'fra': 'https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/pp-checkout.js',
      'sg': 'https://pay-cdn.pingpongx.com/production-sg/static/pp-checkout/pp-checkout.js'
    };

    return urls[this.region];
  }
}

// 使用示例
const config = new PaymentConfig('fra', 'production'); // 
const apiURL = config.getAPIBaseURL();
const sdkURL = config.getSDKURL();

console.log('API URL:', apiURL);
console.log('SDK URL:', sdkURL);

二、线下收单 API 域名

线下收单 API 用于终端支付场景，如线下门店、POS 机、支付终端等设备集成。

沙箱环境

🧪 沙箱环境 API
https://sandbox-acquirer-payment.pingpongx.com

生产环境

站点	API 域名	商户主体注册地	站点选择
FRA 站点	`https://acquirer-payment-instore.pingpongx.com`	欧洲及其他地区注册商户	请联系技术支持
SG 站点	`https://acquirer-payment-instore-sg.pingpongx.com`	亚太地区注册商户	请联系技术支持
US 站点	`https://acquirer-payment-instore-us.pingpongx.com`	北美地区注册商户	请联系技术支持

使用说明

终端支付

请联系技术支持选择合适的站点和获取接入信息

集成示例

src/instore-config.js
// 线下收单 API 域名配置
const INSTORE_API_BASE_URLS = {
  sandbox: 'https://sandbox-acquirer-payment.pingpongx.com',
  'prod-fra': 'https://acquirer-payment-instore.pingpongx.com',
  'prod-sg': 'https://acquirer-payment-instore-sg.pingpongx.com',
  'prod-us': 'https://acquirer-payment-instore-us.pingpongx.com'
};

// 终端设备根据部署地区选择对应域名
const environment = 'prod-fra';
const instoreBaseURL = INSTORE_API_BASE_URLS[environment];

三、商户后台地址

商户后台用于商户管理、订单查询、财务对账、数据报表等后台操作。

站点	商户后台地址	商户主体注册地
FRA 站点	`https://checkout.pingpongx.com`	欧洲及其他地区注册商户
SG 站点	同 FRA 站点	--
US 站点	`https://checkout-us.pingpongx.com`	北美地区注册商户

说明

SG 站点的商户后台与 FRA 站点共用，访问地址为 https://checkout.pingpongx.com
US 站点商户需访问独立的美国后台 https://checkout-us.pingpongx.com
商户后台不涉及 API 集成，仅用于管理和查询操作

四、API 版本说明

当前文档适用于 PingPongCheckout API V4 版本。

API 路径结构

🔗 API 路径格式
{base_url}/v4/{module}/{endpoint}

示例：

预支付接口：/v4/payment/prePay
查询订单：/v4/payment/query
退款接口：/v4/payment/refund
捕获接口：/v4/payment/capture

五、接入流程

在线支付

根据上述规则选择站点和匹配的前端资源。

选择站点
根据商户主体注册地选择对应站点：
- 欧洲注册商户 → FRA 站点
- 亚太注册商户 → FRA 站点
- 北美注册商户 → US 站点
- 其他地区注册商户 → FRA 站点
获取凭证
在对应站点的商户后台申请 API 凭证：
- Merchant ID（商户号）
- API Key（API 密钥）
- Secret Key（签名密钥）

配置域名

在您的系统中配置对应站点的 API 域名

config/merchant.js
// 配置示例
const config = {
  baseURL: 'https://acquirer-payment.pingpongx.com',
  merchantId: 'YOUR_MERCHANT_ID',
  apiKey: 'YOUR_API_KEY',
  secretKey: 'YOUR_SECRET_KEY'
};

沙箱测试
首先在沙箱环境进行集成测试：
- 使用沙箱域名：https://sandbox-acquirer-payment.pingpongx.com
- 使用测试卡号验证支付流程
- 验证异步通知回调功能
- 测试订单查询、退款等操作
生产上线
测试通过后，切换到生产环境：
- 更换为生产环境域名
- 使用生产环境凭证
- 开始处理真实交易

终端支付

请先联系技术支持获取接入信息。

开发指南

最佳实践

沙箱测试资源

API 端点地址

站点架构概览

站点分布

一、线上收单 API 域名

沙箱环境

生产环境

前端资源

沙箱环境

生产环境

使用说明

集成示例

API 集成示例

JS-SDK 集成示例

完整集成示例

二、线下收单 API 域名

沙箱环境

生产环境

使用说明

集成示例

三、商户后台地址

四、API 版本说明

API 路径结构

五、接入流程

在线支付

终端支付