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.
https://sandbox-acquirer-payment.pingpongx.comProduction 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
<!-- 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
// 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
// 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
// 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
https://sandbox-acquirer-payment.pingpongx.comProduction 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
// 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
{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
- Use sandbox domain:
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:
// 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:
// 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:
// 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