SDK Integration Process

Architecture Design

Core Modules

Module	Responsibility
PingPongSDK	SDK's only entry point, exposes init / createElement methods
PingPongElement	Base class for all payment buttons, provides .on() / .off() event mechanism

Payment Modes

SDK supports two main modes:

• payment: Order placement and payment mode, suitable for standard payment processes
• codeGrant: Wallet binding mode, currently only supports PayPal standalone signing

Integration Process

1. Obtain sdkAccessToken

The merchant backend system obtains the access credential by calling the get sdkAccessToken interface.

Payment scenario:

• Call /v4/session/init interface to get sdkAccessToken

Signing scenario:

• POST call existing signing interface to get sdkAccessToken and JS URL

2. Import Element SDK

Based on your business environment, choose the appropriate SDK version to import:

🧪 Sandbox Environment

<script type="module" src="https://acquirer-cdn.pingpongx.com/acquirer/components/sdk/sandbox/v1/index.js"></script>

🇪🇺 FRA Production Environment

<script type="module" src="https://acquirer-cdn.pingpongx.com/acquirer/components/sdk/production/v1/index.js"></script>

🇸🇬 SG Production Environment

<script type="module" src="https://acquirer-cdn.pingpongx.com/acquirer/components/sdk/production-sg/v1/index.js"></script>

3. Initialize SDK

Parameter Description

modeRequiredstring

Business mode

payment(payment) or codeGrant(bind wallet)

envRequiredstring

Runtime environment

sandbox(sandbox) or production(production)

amountRequiredstring

Transaction amount

For cashier display

currencyRequiredstring

Transaction currency

accIdRequiredstring

Merchant account ID

localeRequiredstring

Interface language

en, zh-CN, etc.

regionOptionalstring

fra

Region

sg or fra

sdkAccessTokenRequiredstring

SDK access credential

merchantResultUrlRequiredstring

Redirect URL after payment completion

createOrderOptionalFunction

Order creation function

Required when mode is payment

goodsNameOptionalstring

Product name

Required for ApplePay/signing

goodsDescOptionalstring

Product description

Required for ApplePay/signing

recurringInfoDTOOptionalObject

Recurring configuration, required for ApplePay signing

Initialization Example

src/sdk-init.js

await PingPongSDK.init({
  mode: 'payment',      // Business mode: payment or codeGrant
  env: 'sandbox',       // Runtime environment
  amount: '19.99',      // Transaction amount
  currency: 'USD',      // Transaction currency
  accId: 'ACC_123',     // Merchant account ID
  locale: 'en',         // Language setting
  region: 'fra',        // Region: sg or fra
  sdkAccessToken: 'your_sdk_token',  // SDK access token
  merchantResultUrl: 'https://merchant-result.com',  // Payment completion redirect URL

  // Required when mode is payment
  createOrder: async () => {
    // Call merchant backend order interface
    const response = await fetch('/xx/xx', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        xx: 'xx'
      })
    });
    const result = await response.json();
    return result.token;  // Return order token
  },

  // Required for ApplePay signing
  goodsName: 'Product Name',
  goodsDesc: 'Product Description',
  recurringInfoDTO: {
    recurringPaymentStartDate: '2024-06-01 00:00:00',
    recurringPaymentIntervalUnit: 'month',
    recurringPaymentIntervalCount: '6',
    recurringPaymentEndDate: '2024-12-01 00:00:00'
  }
});

4. Create Payment Elements

4.1 Apple Pay Button

src/apple-pay.js

const applePay = await PingPongSDK.createElement('applePayButton', {
  buttonType: 'buy',     // Button type: buy | plain
  buttonColor: 'black',  // Button color: black | white | white-outline
  style: {
    width: '100%',
    height: '40px',
    borderRadius: '4px'
  },
  payDiscount: {         // Marketing campaign configuration (optional)
    activityNo: 'EEE',
    costAmount: '19.99',     // Original amount
    discountAmount: '2.00'   // Discount amount
  }
});

4.2 Google Pay Button

src/google-pay.js

const googlePay = await PingPongSDK.createElement('googlePayButton', {
  buttonType: 'buy',     // Button type: buy | subscribe
  buttonColor: 'black',  // Button color: black | white
  isChallengeIframe: true, // Render the 3DS Challenge page in an iframe
  style: {
    width: '100%',
    height: '40px',
    borderRadius: '4px'
  },
  payDiscount: {
    activityNo: 'EEE',
    costAmount: '19.99',
    discountAmount: '2.00'
  }
});

Google Pay options parameters:

buttonTypeOptionalstring

Button type. Options: buy, subscribe

buttonColorOptionalstring

Button color. Options: black, white

isChallengeIframeOptionalboolean

Whether to display the 3DS Challenge page in an iframe. When set to true, the Challenge flow is rendered in an iframe.

styleOptionalobject

Button style configuration

payDiscountOptionalobject

Marketing campaign configuration

4.3 PayPal Button

src/paypal.js

const paypal = await PingPongSDK.createElement('paypalButton', {
  buttonType: 'buttons',  // buttons | marks | card-fields | funding-eligibility
  style: {
    borderRadius: 4,
    color: 'gold',        // gold | blue | silver | white | black
    height: 40,
    label: 'paypal',      // paypal | checkout | buynow | pay | installment | subscribe | donate
    layout: 'vertical',   // vertical | horizontal
    shape: 'rect'         // rect | pill | sharp
  }
});

// PayPal does not need to listen for completed event
// When payment is complete, SDK will initiate redirect to merchantResultUrl

5. Event Listening

All payment elements support a unified event model:

src/event-listeners.js

// Listen for ready event
applePay.on('ready', () => {
  console.log('Apple Pay rendered');
});

// Listen for success event
applePay.on('success', (event) => {
  console.log('Apple Pay payment complete', event.detail);
  // event.detail contains transactionId and other information
});

// Listen for error event
applePay.on('error', (event) => {
  console.error('Apple Pay error', event.detail);
  // event.detail contains code and message
});

// Listen for cancel event
applePay.on('cancel', () => {
  console.log('Apple Pay user cancelled');
});

6. Mount and Unmount

src/lifecycle.js

// Mount to specified container
applePay.mount('#apple-pay-container');

// Unmount element
applePay.unmount();

API Reference

PingPongSDK.init()

Initialize SDK configuration.

Parameters:

modeRequiredstring

payment or codeGrant

envRequiredstring

sandbox or production

amountRequiredstring

Transaction amount

currencyRequiredstring

Transaction currency

accIdRequiredstring

Merchant account ID

localeRequiredstring

Interface language

regionOptionalstring

fra

sg or fra

sdkAccessTokenRequiredstring

SDK access credential

merchantResultUrlRequiredstring

Payment completion redirect URL

createOrderOptionalFunction

Required when mode is payment

goodsNameOptionalstring

Required for ApplePay/signing

goodsDescOptionalstring

Required for ApplePay/signing

recurringInfoDTOOptionalObject

Required for ApplePay signing

PingPongSDK.createElement()

Create payment element instance.

Parameters:

typeRequiredstring

applePayButton, googlePayButton, paypalButton

optionsRequiredobject

Element configuration parameters

Returns: Promise<PingPongElement>

element.on()

Register event listener.

Supported events:

readyEvent

Element initialization complete

successEvent

Payment success

errorEvent

Payment failure

cancelEvent

User cancel

element.off()

Remove event listener.

element.mount()

Mount payment element to DOM.

Parameters:

selectorRequiredstring

CSS selector

element.unmount()

Unmount element from DOM, release resources.

Previous pageOnePage Checkout

Next pageNative SDK