---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/onlinePayment/developer/endpoint/index.md
description: 说明在线支付、终端收款和商户后台的沙箱及生产 API 域名，并给出 FRA、SG、US 站点选择规则。
---
# API 端点地址

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

## 站点架构概览

PingPongCheckout 提供三类站点服务：

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

## 站点分布

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

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

## 一、线上收单 API 域名

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

### 沙箱环境

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

```text:line-numbers title="🧪 沙箱环境 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 用于前端页面集成收银台组件。

#### 沙箱环境

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

#### 生产环境

| 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 接入指南](/notes/zh/integrate/sdk-v4-preview/)            |
| **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 接入指南](/notes/zh/integrate/sdk-v4-2/)      |
| **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 架构设计](/notes/zh/integrate/sdk-elements/) |

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

### 使用说明

::: tip 站点选择原则
商户应根据**主体注册地**选择对应站点：
- **欧洲注册商户**：使用 FRA 站点
- **亚太注册商户**：优先使用 FRA 站点，如果申请使用 SG 站点，请联系技术支持
- **北美注册商户**：使用 US 站点
- **其他地区注册商户**：使用 FRA 站点
:::

### 集成示例

#### API 集成示例

```javascript:line-numbers title="config/api-endpoints.js"
// [!code highlight] 根据商户所在地区配置 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'
};

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

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

#### JS-SDK 集成示例

```javascript:line-numbers title="sdk/dynamic-loader.js"
// [!code highlight] 根据后端选择的域名配置 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'
};

// [!code highlight] 动态加载对应站点的 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);

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

#### 完整集成示例

```javascript:line-numbers title="src/env.js"
// [!code highlight] 配置类 - 统一管理 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];
  }
}

// [!code highlight] 使用示例
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 机、支付终端等设备集成。

### 沙箱环境

```text:line-numbers title="🧪 沙箱环境 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` | 北美地区注册商户    | 请联系技术支持 |

### 使用说明

::: tip 终端支付
- 请联系技术支持选择合适的站点和获取接入信息
:::

### 集成示例

```javascript:line-numbers title="src/instore-config.js"
// [!code highlight] 线下收单 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'
};

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

## 三、商户后台地址

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

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

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

## 四、API 版本说明

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

### API 路径结构

```text:line-numbers title="🔗 API 路径格式"
{base_url}/v4/{module}/{endpoint}
```

**示例：**

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

## 五、接入流程

### 在线支付

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

::: steps

1. **选择站点**

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

   - 欧洲注册商户 → FRA 站点
   - 亚太注册商户 → FRA 站点
   - 北美注册商户 → US 站点
   - 其他地区注册商户 → FRA 站点

2. **获取凭证**

   在对应站点的商户后台申请 API 凭证：

   - **Merchant ID**（商户号）
   - **API Key**（API 密钥）
   - **Secret Key**（签名密钥）

3. **配置域名**

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

   ```javascript:line-numbers title="config/merchant.js"
   // 配置示例
   const config = {
     baseURL: 'https://acquirer-payment.pingpongx.com',  // [!code focus]
     merchantId: 'YOUR_MERCHANT_ID',  // [!code focus]
     apiKey: 'YOUR_API_KEY',  // [!code focus]
     secretKey: 'YOUR_SECRET_KEY'  // [!code focus]
   };
   ```

4. **沙箱测试**

   首先在沙箱环境进行集成测试：

   - 使用沙箱域名：`https://sandbox-acquirer-payment.pingpongx.com`
   - 使用测试卡号验证支付流程
   - 验证异步通知回调功能
   - 测试订单查询、退款等操作

5. **生产上线**

   测试通过后，切换到生产环境：

   - 更换为生产环境域名
   - 使用生产环境凭证
   - 开始处理真实交易

:::

### 终端支付

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