PingPong Element SDK Integration Guide

About 1475 wordsAbout 5 min

2025-01-05

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

Name:mode

Required

string

Business mode

payment(payment) or codeGrant(bind wallet)

Name:env

Required

string

Runtime environment

sandbox(sandbox) or production(production)

Name:amount

Required

string

Transaction amount

For cashier display

Name:currency

Required

string

Transaction currency

Name:accId

Required

string

Merchant account ID

Name:locale

Required

string

Interface language

en, zh-CN, etc.

Name:region

Optional

string

Default:fra

Region

sg or fra

Name:sdkAccessToken

Required

string

SDK access credential

Name:merchantResultUrl

Required

string

Redirect URL after payment completion

Name:createOrder

Optional

Function

Order creation function

Required when mode is payment

Name:goodsName

Optional

string

Product name

Required for ApplePay/signing

Name:goodsDesc

Optional

string

Product description

Required for ApplePay/signing

Name:recurringInfoDTO

Optional

Object

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:

Name:buttonType

Optional

string

Button type. Options: buy, subscribe

Name:buttonColor

Optional

string

Button color. Options: black, white

Name:isChallengeIframe

Optional

boolean

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

Name:style

Optional

object

Button style configuration

Name:payDiscount

Optional

object

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:

Name:mode

Required

string

payment or codeGrant

Name:env

Required

string

sandbox or production

Name:amount

Required

string

Transaction amount

Name:currency

Required

string

Transaction currency

Name:accId

Required

string

Merchant account ID

Name:locale

Required

string

Interface language

Name:region

Optional

string

Default:fra

sg or fra

Name:sdkAccessToken

Required

string

SDK access credential

Name:merchantResultUrl

Required

string

Payment completion redirect URL

Name:createOrder

Optional

Function

Required when mode is payment

Name:goodsName

Optional

string

Required for ApplePay/signing

Name:goodsDesc

Optional

string

Required for ApplePay/signing

Name:recurringInfoDTO

Optional

Object

Required for ApplePay signing

PingPongSDK.createElement()

Create payment element instance.

Parameters:

Name:type

Required

string

applePayButton, googlePayButton, paypalButton

Name:options

Required

object

Element configuration parameters

Returns: Promise<PingPongElement>

element.on()

Supported events:

Name:ready

Optional

Event

Element initialization complete

Name:success

Optional

Event

Payment success

Name:error

Optional

Event

Payment failure

Name:cancel

Optional

Event

User cancel

element.off()

Remove event listener.

element.mount()

Mount payment element to DOM.

Parameters:

Name:selector

Required

string

CSS selector

element.unmount()

Unmount element from DOM, release resources.

No-Code Integration

Developer Integration

PingPong Checkout

Embedded Checkout

Embedded SDK

API Only

PingPong Element SDK Integration Guide

SDK Integration Process

Architecture Design

Core Modules

Payment Modes

Integration Process

1. Obtain sdkAccessToken

2. Import Element SDK

3. Initialize SDK

Parameter Description

Initialization Example

4. Create Payment Elements

4.1 Apple Pay Button

4.2 Google Pay Button

4.3 PayPal Button

5. Event Listening

6. Mount and Unmount

API Reference

PingPongSDK.init()

PingPongSDK.createElement()

element.on()

element.off()

element.mount()

element.unmount()