---
url: 'https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/guide/endpoint/index.md'
description: >-
  API endpoint address documentation introduces the online, terminal, and
  merchant backend API access domains provided by PingPongCheckout. Choose the
  corresponding site (FRA, SG, US) based on business scenarios and registration
  location, supporting sandbox and production environments, providing detailed
  API domain configuration and JS-SDK integration instructions.
---
# API Endpoint Addresses

This document explains the API endpoint address configurations for various sites provided by PingPongCheckout. Choose the corresponding API domain for integration based on your business scenario and integration method.

## Site Architecture Overview

PingPongCheckout provides three types of site services:

- **Online Business**: For online payment scenarios, supporting checkout and S2S modes
- **Terminal Business**: For terminal payment scenarios, supporting offline payment device integration
- **Merchant Backend**: For merchant management, order queries, data statistics, and other backend operations

## Site Distribution

PingPongCheckout has deployed three main sites globally, with merchants choosing the corresponding site based on their entity registration location:

| Site Code | Site Name | Location | Merchant Entity Registration Location |
|---------|--------|--------|------------|
| **FRA** | Frankfurt Site | Europe-Germany | European and other region registered merchants |
| **SG** | Singapore Site | Asia-Pacific-Singapore | Asia-Pacific region registered merchants |
| **US** | United States Site | North America-US | North America region registered merchants |

## 1. Online Acquiring API Domain

Online acquiring API is used for online payment scenarios, including checkout mode and server-to-server mode (S2S).

### Sandbox Environment

Used for development and testing phases, all sites share a unified sandbox environment.

```text:line-numbers title="🧪 Sandbox Environment API"
https://sandbox-acquirer-payment.pingpongx.com
```

### Production Environment

Choose the corresponding production environment domain based on merchant entity registration location:

| Site | API Domain | Merchant Entity Registration Location |
|-----|---------|------------|
| **FRA Site** | `https://acquirer-payment.pingpongx.com` | European and other region registered merchants |
| **SG Site** | `https://acquirer-payment-checkout-sg.pingpongx.com` | Asia-Pacific region registered merchants |
| **US Site** | `https://acquirer-payment-checkout-us.pingpongx.com` | North America region registered merchants |

### JS-SDK Domain

JavaScript SDK also follows the partitioning principle and must use the same site as the API. The SDK is used for front-end page integration of checkout components.

#### Sandbox Environment

```html:line-numbers title="🧪 Sandbox Environment JS-SDK"
<!-- All sites share sandbox environment -->
<script type="module" src="https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/sandbox/pp-checkout.js"></script>  // [!code focus]
```

#### Production Environment

| Site | JS-SDK CDN Address | Merchant Entity Registration Location |
|-----|---------------|------------|
| **FRA Site** | `https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/pp-checkout.js` | European and other region registered merchants |
| **SG Site** | `https://pay-cdn.pingpongx.com/production-sg/static/pp-checkout/pp-checkout.js` | Asia-Pacific region registered merchants |

### Usage Instructions

::: tip Site Selection Principle
Merchants should choose the corresponding site based on **entity registration location**:
- **European registered merchants**: Use FRA site
- **Asia-Pacific registered merchants**: Use SG site
- **North American registered merchants**: Use US site
- **Other region registered merchants**: Use FRA site
:::

### Integration Examples

#### API Integration Example

```javascript:line-numbers title="config/api-endpoints.js"
// [!code highlight] Configure API domain based on merchant region
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] Select corresponding environment
const environment = 'prod-fra'; // or 'prod-sg', 'prod-us'
const baseURL = API_BASE_URLS[environment];

// API request example
const apiUrl = `${baseURL}/v4/payment/prePay`;
```

#### JS-SDK Integration Example

```javascript:line-numbers title="sdk/dynamic-loader.js"
// [!code highlight] Configure JS-SDK CDN address based on merchant region
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] Dynamically load SDK for corresponding site
const environment = 'prod-fra'; // Choose based on merchant entity registration location
const sdkURL = SDK_URLS[environment];

// Dynamically create script tag to load SDK
const script = document.createElement('script');
script.type = 'module';
script.src = sdkURL;
document.head.appendChild(script);

// [!code highlight] Use SDK after loading
script.onload = function() {
  // SDK loaded, can initialize checkout component
  const checkout = document.createElement('pp-checkout');
  checkout.setAttribute('locale', 'zh');
  document.body.appendChild(checkout);
};
```

#### Complete Integration Example

```javascript:line-numbers title="src/env.js"
// [!code highlight] Configuration class - Unified management of API and SDK configuration
class PaymentConfig {
  constructor(region = 'fra', environment = 'production') {
    this.region = region; // 'fra', 'sg', 'us'
    this.environment = environment; // 'production', 'sandbox'
  }

  // Get API base 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];
  }

  // Get 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] Usage example
const config = new PaymentConfig('sg', 'production'); // Asia-Pacific region production environment
const apiURL = config.getAPIBaseURL();
const sdkURL = config.getSDKURL();

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

## 2. Offline Acquiring API Domain

Offline acquiring API is used for terminal payment scenarios, such as offline stores, POS machines, payment terminals, and other device integrations.

### Sandbox Environment

```text:line-numbers title="🧪 Sandbox Environment API"
https://sandbox-acquirer-payment.pingpongx.com
```

### Production Environment

| Site | API Domain | Merchant Entity Registration Location |
|-----|---------|------------|
| **FRA Site** | `https://acquirer-payment-instore.pingpongx.com` | European and other region registered merchants |
| **SG Site** | `https://acquirer-payment-instore-sg.pingpongx.com` | Asia-Pacific region registered merchants |
| **US Site** | `https://acquirer-payment-instore-us.pingpongx.com` | North America region registered merchants |

### Usage Instructions

::: tip Offline Acquiring Features
- Optimized specifically for offline payment devices and terminals
- Supports fast response and high concurrent processing
- Provides terminal device management and configuration functions
:::

### Integration Examples

```javascript:line-numbers title="src/instore-config.js"
// [!code highlight] Offline acquiring API domain configuration
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] Terminal devices choose corresponding domain based on deployment region
const environment = 'prod-fra';
const instoreBaseURL = INSTORE_API_BASE_URLS[environment];
```

## 3. Merchant Backend Address

The merchant backend is used for merchant management, order queries, financial reconciliation, data reports, and other backend operations.

| Site | Merchant Backend Address | Merchant Entity Registration Location |
|-----|------------|------------|
| **FRA Site** | `https://checkout.pingpongx.com` | European and other region registered merchants |
| **SG Site** | Same as FRA Site | Asia-Pacific region registered merchants (shared FRA backend) |
| **US Site** | `https://checkout-us.pingpongx.com` | North America region registered merchants |

::: info Notes
- SG site merchant backend is shared with FRA site, access address is `https://checkout.pingpongx.com`
- US site merchants need to access the independent US backend `https://checkout-us.pingpongx.com`
- Merchant backend does not involve API integration, only used for management and query operations
:::

## 4. API Version Information

This document applies to **PingPongCheckout API V4** version.

### API Path Structure

```text:line-numbers title="🔗 API Path Format"
{base_url}/v4/{module}/{endpoint}
```

**Examples:**

- Pre-payment interface: `/v4/payment/prePay`
- Query order: `/v4/payment/query`
- Refund interface: `/v4/payment/refund`
- Capture interface: `/v4/payment/capture`

## 5. Integration Process

::: steps

1. **Select Site**

   Choose the corresponding site based on merchant entity registration location:

   - European registered merchants → FRA site
   - Asia-Pacific registered merchants → SG site
   - North American registered merchants → US site
   - Other region registered merchants → FRA site

2. **Obtain Credentials**

   Apply for API credentials in the merchant backend of the corresponding site:

   - **Merchant ID**
   - **API Key**
   - **Secret Key**

3. **Configure Domain**

   Configure the API domain for the corresponding site in your system

   ```javascript:line-numbers title="config/merchant.js"
   // Configuration example
   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. **Sandbox Testing**

   First perform integration testing in the sandbox environment:

   - Use sandbox domain: `https://sandbox-acquirer-payment.pingpongx.com`
   - Use test card numbers to verify payment process
   - Verify asynchronous notification callback function
   - Test order query, refund operations

5. **Production Launch**

   After testing is passed, switch to production environment:

   - Replace with production environment domain
   - Use production environment credentials
   - Start processing real transactions

:::

### JS-SDK Partition Information

::: tip Important Reminder
JavaScript SDK also follows the partitioning principle, **must use the same site as API**. Incorrect SDK and API combinations will cause functional abnormalities.
:::

#### Partition Rules

- **Sandbox Environment**: All sites share the same SDK address
- **Production Environment**: Each site has an independent SDK CDN address
- **Must be Consistent**: API and SDK must use addresses from the same site

#### Common Error Examples

❌ **Incorrect Practice**:
```javascript:line-numbers title="examples/incorrect-configuration.js"
// [!code highlight] API uses SG site, but SDK uses FRA site
const apiURL = 'https://acquirer-payment-checkout-sg.pingpongx.com';
const sdkURL = 'https://pay-cdn.pingpongx.com/production-fra/static/pp-checkout/pp-checkout.js';
```

✅ **Correct Practice**:
```javascript:line-numbers title="examples/correct-configuration.js"
// [!code highlight] Both API and SDK use SG site
const apiURL = 'https://acquirer-payment-checkout-sg.pingpongx.com';
const sdkURL = 'https://pay-cdn.pingpongx.com/production-sg/static/pp-checkout/pp-checkout.js';
```

## 6. Frequently Asked Questions

### Q1: How do I determine which site to use?

**A:** Site selection is based on merchant entity registration location:
- European region registered merchants → FRA site
- Asia-Pacific region registered merchants → SG site
- North American region registered merchants → US site
- Other region registered merchants → FRA site

::: warning Important Note
Site selection is based on **merchant entity registration location**, not transaction country or consumer location. For example, a merchant registered in Singapore that primarily serves European customers should still use the SG site.
:::

### Q2: Must JS-SDK and API use the same site?

**A:** Yes, **must use the same site**. This is a mandatory partitioning rule:

- API uses FRA site → JS-SDK must use FRA site address
- API uses SG site → JS-SDK must use SG site address
- API uses US site → JS-SDK must use US site address

::: danger Note
If JS-SDK and API use different sites, it will cause:
- Payment request failure
- Order status abnormalities
- Asynchronous notifications cannot be received
- Cross-origin access errors
:::

### Q3: Can multiple sites be used simultaneously?

**A:** Yes. If your business covers merchant entities in multiple regions, you can register separately in different sites. For example:
- Subsidiary registered in Europe uses FRA site
- Subsidiary registered in the US uses US site

Note: FRA and SG site data are interoperable, using the same credentials; US site data is independent and requires separate registration and management.

### Q4: Is data interoperable between different sites?

**A:** Site data interoperability is as follows:

- **FRA Site ↔ SG Site**: Data interoperable
  - Order data and transaction records are shared between two sites
  - Use the same merchant credentials
  - Orders can be queried and managed from either site

- **US Site**: Data independent
  - US site data is not interoperable with FRA/SG sites
  - Requires separate merchant credentials
  - Order and financial data managed independently

- **Sandbox Environment**: Data independent
  - Sandbox environment completely isolated from all production environments
  - Only for development and testing, using test data and test card numbers
  - Sandbox credentials independent from production credentials, cannot be mixed

::: warning Notes
- If business covers both European/Asian and North American regions, separate registration is needed in FRA/SG and US sites
- Orders from US site cannot be queried in FRA/SG site backend, vice versa
- Reconciliation and settlement are also conducted independently
- Sandbox environment test data will not sync to production environment
:::

### Q5: Does switching sites require code modifications?

**A:** Only need to modify API domain and SDK CDN address configurations. API interface paths and parameters remain consistent across all sites. It is recommended to manage through configuration classes or environment variables for easy switching.

### Q6: How to ensure JS-SDK and API use the correct site?

**A:** It is recommended to use unified configuration management:

```javascript:line-numbers title="src/env.js"
// [!code highlight] Recommended configuration management approach
class PaymentConfig {
  constructor(region = 'fra', environment = 'production') {
    this.region = region; // 'fra', 'sg', 'us'
    this.environment = environment; // 'production', 'sandbox'

    // [!code highlight] Validate region parameter
    if (!['fra', 'sg', 'us'].includes(region)) {
      throw new Error(`Invalid region: ${region}. Must be 'fra', 'sg', or 'us'`);
    }
  }

  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];
  }

  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] Usage example - Ensure site consistency
const config = new PaymentConfig('sg', 'production');
console.log('API:', config.getAPIBaseURL());  // SG site API
console.log('SDK:', config.getSDKURL());      // SG site SDK
```