--- url: >- https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/integrate/sdk-elements/index.md description: >- PingPong Element SDK supports diverse payment scenarios such as order placement and payment, wallet binding. Adopting a new architecture design, it provides unified API interfaces, flexible event models, and extensible payment components. The integration process includes importing SDK scripts, initialization configuration, creating payment elements, event listening and handling, and provides marketing campaign integration functionality. --- # PingPong Element SDK Integration Guide ## SDK Integration Process ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#E3F2FD', 'primaryTextColor': '#0D47A1', 'primaryBorderColor': '#1976D2', 'lineColor': '#1565C0', 'secondaryColor': '#BBDEFB', 'tertiaryColor': '#90CAF9', 'background': '#F8FBFF', 'mainBkg': '#E3F2FD', 'secondBkg': '#BBDEFB', 'tertiaryBkg': '#90CAF9', 'actorBkg': '#2196F3', 'actorBorder': '#1976D2', 'actorTextColor': '#FFFFFF', 'actorLineColor': '#1565C0', 'signalColor': '#0D47A1', 'signalTextColor': '#0D47A1', 'c0': '#E8F4FD', 'c1': '#D1E7DD', 'c2': '#B3D9FF', 'c3': '#81C784', 'noteBkgColor': '#E1F5FE', 'noteTextColor': '#01579B', 'noteBorderColor': '#0288D1', 'loopTextColor': '#0D47A1', 'activationBkgColor': '#B3E5FC', 'activationBorderColor': '#0277BD' } }}%% sequenceDiagram participant User as 👤 User participant Browser as 🌐 Browser participant Frontend as 💻 Merchant Frontend participant Backend as 🏪 Merchant Backend participant SDK as 📦 Element SDK participant PP as 🔄 PingPong Server Note over User, PP: 🚀 Element SDK Complete Integration Process User->>Browser: 1. Select product Browser->>Frontend: 2. Open payment page Note over Frontend, Backend: 📋 Initialization Phase Frontend->>+Backend: 3. Request initialization sdkAccessToken Backend->>+PP: 4. Request initialization sdkAccessToken PP-->>-Backend: 5. Return initialization sdkAccessToken Backend-->>-Frontend: 6. Return initialization sdkAccessToken Frontend->>+SDK: 7. Initialize SDK with sdkAccessToken Note right of SDK: PingPongSDK.init() SDK->>+PP: 8. Query shop configuration PP-->>-SDK: 9. Return shop configuration SDK-->>-Frontend: 10. SDK initialization complete SDK->>Frontend: 11. Trigger ready event Frontend->>SDK: 12. Create payment element Note right of SDK: createElement() SDK-->>Frontend: 13. Payment element ready Frontend->>Browser: 14. Render payment button in payment page Note over User, PP: 💳 Payment process starts Frontend->>User: 15. Display payment button User->>Frontend: 16. Click payment button Frontend->>+SDK: 17. Trigger payment process SDK->>+Frontend: 18. Call createOrder() activate Frontend Note over Frontend: Validate billing, shipping, coupons Frontend->>+Backend: 19. Send order details Backend->>+PP: 20. Place order (original V4 order interface) PP-->>-Backend: 21. Return transaction token Backend-->>-Frontend: 22. Return transaction token Frontend-->>-SDK: 23. Return token from createOrder deactivate Frontend SDK->>+PP: 24. Request payment (payment info + token) PP->>PP: 25. Process payment Note right of PP: • Risk control check
• Payment routing
• Third-party calls PP-->>-SDK: 26. Payment response alt ❌ Payment failed SDK->>Frontend: 27. Call error(code, msg) activate Frontend Note over Frontend: Handle payment failure logic deactivate Frontend else ✅ Payment success or processing SDK->>Browser: 28. Redirect to payment result page Note right of Browser: merchantResultUrl else 🔒 3DS verification required SDK->>Browser: 29. Redirect to 3DS verification page end Note over User, PP: 🎯 Payment process ends ``` ## 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: :::: code-tabs @tab 🧪 Sandbox Environment ```html ``` @tab 🇪🇺 FRA Production Environment ```html ``` @tab 🇸🇬 SG Production Environment ```html ``` :::: ### 3. Initialize SDK #### Parameter Description ::::: field-group :::: field name="mode" type="string" required Business mode `payment`(payment) or `codeGrant`(bind wallet) :::: :::: field name="env" type="string" required Runtime environment `sandbox`(sandbox) or `production`(production) :::: :::: field name="amount" type="string" required Transaction amount For cashier display :::: :::: field name="currency" type="string" required Transaction currency :::: :::: field name="accId" type="string" required Merchant account ID :::: :::: field name="locale" type="string" required Interface language `en`, `zh-CN`, etc. :::: :::: field name="region" type="string" optional default="fra" Region `sg` or `fra` :::: :::: field name="sdkAccessToken" type="string" required SDK access credential :::: :::: field name="merchantResultUrl" type="string" required Redirect URL after payment completion :::: :::: field name="createOrder" type="Function" optional Order creation function Required when mode is `payment` :::: :::: field name="goodsName" type="string" optional Product name Required for ApplePay/signing :::: :::: field name="goodsDesc" type="string" optional Product description Required for ApplePay/signing :::: :::: field name="recurringInfoDTO" type="Object" optional Recurring configuration, required for ApplePay signing :::: ::::: #### Initialization Example ```javascript:line-numbers title="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 ```javascript:line-numbers title="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 ```javascript:line-numbers title="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:** ::::: field-group :::: field name="buttonType" type="string" optional Button type. Options: `buy`, `subscribe` :::: :::: field name="buttonColor" type="string" optional Button color. Options: `black`, `white` :::: :::: field name="isChallengeIframe" type="boolean" optional Whether to display the 3DS Challenge page in an iframe. When set to `true`, the Challenge flow is rendered in an iframe. :::: :::: field name="style" type="object" optional Button style configuration :::: :::: field name="payDiscount" type="object" optional Marketing campaign configuration :::: ::::: #### 4.3 PayPal Button ```javascript:line-numbers title="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: ```javascript:line-numbers title="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 ```javascript:line-numbers title="src/lifecycle.js" // Mount to specified container applePay.mount('#apple-pay-container'); // Unmount element applePay.unmount(); ``` ## API Reference ### PingPongSDK.init() Initialize SDK configuration. **Parameters:** ::::: field-group :::: field name="mode" type="string" required `payment` or `codeGrant` :::: :::: field name="env" type="string" required `sandbox` or `production` :::: :::: field name="amount" type="string" required Transaction amount :::: :::: field name="currency" type="string" required Transaction currency :::: :::: field name="accId" type="string" required Merchant account ID :::: :::: field name="locale" type="string" required Interface language :::: :::: field name="region" type="string" optional default="fra" `sg` or `fra` :::: :::: field name="sdkAccessToken" type="string" required SDK access credential :::: :::: field name="merchantResultUrl" type="string" required Payment completion redirect URL :::: :::: field name="createOrder" type="Function" optional Required when mode is `payment` :::: :::: field name="goodsName" type="string" optional Required for ApplePay/signing :::: :::: field name="goodsDesc" type="string" optional Required for ApplePay/signing :::: :::: field name="recurringInfoDTO" type="Object" optional Required for ApplePay signing :::: ::::: ### PingPongSDK.createElement() Create payment element instance. **Parameters:** ::::: field-group :::: field name="type" type="string" required `applePayButton`, `googlePayButton`, `paypalButton` :::: :::: field name="options" type="object" required Element configuration parameters :::: ::::: **Returns:** Promise\ ### element.on() Register event listener. **Supported events:** ::::: field-group :::: field name="ready" type="Event" Element initialization complete :::: :::: field name="success" type="Event" Payment success :::: :::: field name="error" type="Event" Payment failure :::: :::: field name="cancel" type="Event" User cancel :::: ::::: ### element.off() Remove event listener. ### element.mount() Mount payment element to DOM. **Parameters:** ::::: field-group :::: field name="selector" type="string" required CSS selector :::: ::::: ### element.unmount() Unmount element from DOM, release resources.