API Endpoint Addresses

About 1995 wordsAbout 7 min

2025-10-31

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.

🧪 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

🧪 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>

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

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

config/api-endpoints.js
// 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'
};

// 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

sdk/dynamic-loader.js
// 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'
};

// 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);

// 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

src/env.js
// 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];
  }
}

// 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

🧪 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

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

src/instore-config.js
// 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'
};

// 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

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

🔗 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

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
Obtain Credentials
Apply for API credentials in the merchant backend of the corresponding site:
- Merchant ID
- API Key
- Secret Key

Configure Domain

Configure the API domain for the corresponding site in your system

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

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
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

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:

examples/incorrect-configuration.js
// 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:

examples/correct-configuration.js
// 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

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

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

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:

src/env.js
// Recommended configuration management approach
class PaymentConfig {
  constructor(region = 'fra', environment = 'production') {
    this.region = region; // 'fra', 'sg', 'us'
    this.environment = environment; // 'production', 'sandbox'

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

// 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

LLM Documentation Integration

Best Practices

API Endpoint Addresses

Site Architecture Overview

Site Distribution

1. Online Acquiring API Domain

Sandbox Environment

Production Environment

JS-SDK Domain

Sandbox Environment

Production Environment

Usage Instructions

Integration Examples

API Integration Example

JS-SDK Integration Example

Complete Integration Example

2. Offline Acquiring API Domain

Sandbox Environment

Production Environment

Usage Instructions

Integration Examples

3. Merchant Backend Address

4. API Version Information

API Path Structure

5. Integration Process

JS-SDK Partition Information

Partition Rules

Common Error Examples

6. Frequently Asked Questions

Q1: How do I determine which site to use?

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

Q3: Can multiple sites be used simultaneously?

Q4: Is data interoperable between different sites?

Q5: Does switching sites require code modifications?

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