English

简体中文

English

简体中文

Appearance

OnePage Checkout

About 3635 wordsAbout 12 min

View as Markdown

2025-03-07

What is OnePage Checkout?

OnePage Checkout is a modern e-commerce checkout model that consolidates the traditional multi-page checkout process (such as: shopping cart → fill in delivery information → select payment method → confirm order) onto a single page. Users can complete all checkout steps within one page without page jumps, greatly simplifying the shopping process.

Design philosophy of this solution

This SDK solution is specially designed to adapt to OnePage Checkout pages. If your e-commerce website has already adopted the one-page checkout model, this solution can seamlessly embed PingPong payment components into your existing checkout page, displaying alongside modules such as address filling and shipping selection, maintaining user experience consistency without requiring reconstruction of your checkout flow.

Main Advantages

Enhanced User Experience

  • Reduces page loading and jumping, improving checkout efficiency
  • Users can view and modify order information in real-time
  • Clean and intuitive interface, reducing cart abandonment rate

Improved Conversion Rate

  • Simplified process means fewer operational steps and potential drop-off points
  • Shorter and more direct path for users to complete purchases
  • Particularly suitable for mobile users with more friendly responsive design

Core Function Modules

Typical one-page checkout usually includes the following modules:

  • Address Information: Delivery address filling and selection
  • Shipping Method: Available shipping options and fees
  • Payment Method: Various payment options (credit card, PayPal, Alipay, etc.)
  • Order Summary: Product list, prices, totals, etc.
  • Coupons/Discount Codes: Input discount information

Implementation Suggestions

  1. Progressive Design: Use collapsible design, expand modules as needed
  2. Form Validation: Real-time validation of user input, reducing errors
  3. Guest Checkout: Allow users to purchase without registration
  4. Save Information: Automatically save address and payment information for logged-in users
  5. Security Authentication: Ensure PCI DSS compliance, display security indicators

Applicable Scenarios

  • Mobile shopping platforms
  • E-commerce websites pursuing high conversion rates
  • Subscription services
  • Digital product sales

SDK Integration Process

Integration Process

1. Get sdkAccessToken API

The merchant backend system obtains the JS-SDK access credential (token) through the Get sdkAccessToken API, which is used for the frontend JS-SDK initialization call.

2. Import Javascript-SDK

Copy the following code to import the PingPongCheckout Javascript-SDK via CDN address

🧪 Sandbox Environment
<script type="module" src="https://payssr-cdn.pingpongx.com/production-fra/acquirer-checkout-onepage/sandbox/pp-checkout.js"></script>

3. Initialize Cashier

Insert the pp-checkout tag into the html body

components/checkout.html
<!-- Insert PingPong Cashier Component -->
<pp-checkout locale="en"></pp-checkout>

Call PingPong.Checkout.create to complete initialization

Parameters

amountRequiredString

Transaction amount

This transaction is only for cashier display. Subsequent amount changes need to call the updateCheckoutHook function to update

currencyRequiredString

Transaction currency

tradeCountryRequiredString

Used to specify the PingPong cashier country

Subsequent country changes need to call the updateCheckoutHook function to update

sdkAccessTokenRequiredString

JS-SDK access credential

originalPayOptionalBoolean

true

Controls whether to use the default PingPong payment button

If set to false, it means not using the built-in payment button. In this case, you need to call the PingPong.Checkout.pay.run() method in the custom payment button click event to trigger the payment process.

isChallengeIframeOptionalBoolean

false

Controls whether to display the 3DS Challenge page in an iframe

When set to true, the Challenge flow is rendered in an iframe.

paymentMethodsOptionalString[]

Specify payment method list, embedded cashier will display according to specified payment methods

The passed payment methods will perform intersection operation with configured payment methods under this accId. The display order of payment methods will be arranged according to the order of the passed array.

useTabModeOptionalBoolean

true

Controls whether to display payment method option box

When set to false, if the merchant only has card payment configuration, the option box will not be displayed and the payment form will be directly shown. Suitable for scenarios to simplify user experience.

goodsOptionalArray

Product list, containing the following sub-fields

goods.descriptionOptionalString

Product description

goods.imgUrlOptionalString

Product image URL

goods.nameRequiredString

Product name

goods.numberRequiredString

Product quantity

goods.skuOptionalString

Product SKU code

goods.unitPriceRequiredString

Product unit price

goods.virtualProductOptionalString

N

Whether it's a virtual product

Y - Virtual product, N - Physical product

bizTypeOptionalString

ApplePay card binding business parameter

Required for ApplePay transactions, fixed value: CodeGrant

recurringInfoDTOOptionalObject

Configure Recurring payment (required for ApplePay transactions), containing the following sub-fields

recurringInfoDTO.recurringPaymentStartDateOptionalDate

First payment date

eg: "2024-06-01 00:00:00"

recurringInfoDTO.recurringPaymentIntervalUnitOptionalString

Type representing calendar units such as year, month, day, hour, etc.

enum: year / month / day / hour / minute, eg: "month"

recurringInfoDTO.recurringPaymentIntervalCountOptionalString

Number of interval units constituting the total payment interval

eg: "6"

recurringInfoDTO.recurringPaymentEndDateOptionalDate

Last payment date

eg: "2024-12-01 00:00:00"

Custom Payment Button (Optional)

src/config/payment.js
// Custom payment button configuration
// When originalPay is false in initialization parameters, custom payment button click event is needed
document.querySelector('#pay').onclick = function () {
    PingPong.Checkout.pay.run() // Manually trigger payment
}

Event Listeners (Optional)

SDK supports listening to ready and error events during initialization, facilitating external state management and error handling.

src/config/payment.js
// Listen to SDK initialization events
// Listen to initialization success event
document.querySelector('pp-checkout').addEventListener('ready', (e) => {
    console.log('SDK initialization successful'); // Initialization success callback
    // You can execute post-initialization logic here
});

// Listen to initialization failure event
document.querySelector('pp-checkout').addEventListener('error', (e) => {
    console.log('SDK initialization failed', e.detail); // Error information
    // You can execute error handling logic here, such as displaying error prompts, retrying, etc.
});

Event Description:

  • ready: Triggered when SDK initialization is successful, indicating cashier is ready
  • error: Triggered when SDK initialization fails, event details contained in e.detail

4. Modify Amount, Country and Products

Before using global variables, please ensure the Javascript-SDK has loaded completely.

updateCheckoutHook (Optional)

updateCheckoutHook is used to update cashier elements.

ts types
src/types/hooks.ts
// updateCheckoutHook type definition
PingPong.Checkout.updateCheckoutHook:
({ amount?: string, tradeCountry?: string, goods?: Goods[] }) => void
Usage Instructions

⚠️ Important: This method uses a partial update mechanism. Only pass in the fields that have changed, no need to pass in other fields.

ScenarioParameterExample Code
Country changestradeCountryPingPong.Checkout.updateCheckoutHook({ tradeCountry: newCountry });
Amount changesamountPingPong.Checkout.updateCheckoutHook({ amount: newAmount });
Goods changesgoodsPingPong.Checkout.updateCheckoutHook({ goods: newGoods });
Correct Examples
src/config/update.js
❌ Incorrect Examples

The following approaches are not recommended - passing unnecessary fields or null values:

src/config/update-error.js
// ❌ Incorrect: No need to pass unchanged fields or null values
PingPong.Checkout.updateCheckoutHook({
    amount: newAmount ? newAmount : null,
    tradeCountry: newCountry ? newCountry : null,
    goods: newGoods ? newGoods : null
});

// ❌ Incorrect: When updating amount only, no need to pass country and goods
PingPong.Checkout.updateCheckoutHook({
    amount: '99.99',
    tradeCountry: 'US',  // Unchanged field, not needed
    goods: []             // Unchanged field, not needed
});

5. Pre-order Verification

beforeCheckoutHook (Optional)

type：

src/types/hooks.ts
// beforeCheckoutHook type definition
(() => void) | (() => Promise<void>)

beforeCheckoutHook is used to set the hook function before initiating payment request.

When you need to execute your own business logic before the user clicks the payment button and initiates the payment request, such as reporting analytics, checking inventory, etc., you can set this hook function.

This function can return a Promise, and subsequent payment processes will wait until the Promise status becomes Fulfilled before continuing execution. If you want to interrupt the payment process when the Promise status is Rejected or the asynchronous result doesn't meet your business conditions, you can throw an exception, and the SDK will interrupt the payment process after capturing the exception.

src/config/payment.js
PingPong.Checkout.beforeCheckoutHook = () => {
    return fetch('/api/requestInventory').then(res => {

        const {inventoryQuantity} = res;

        if (inventoryQuantity < MIN_QUANTITY) {
            throw new Error('Insufficient inventory, transaction needs to be interrupted')
        }
    }).catch((error) => {
        throw new Error('Interface exception, transaction needs to be interrupted')
    })
};
ts types
src/types/hooks.ts
// beforeCheckoutHook return type definition
PingPong.Checkout.beforeCheckoutHook:
(() => string) | (() => Promise<string>)

6. Place Order

After clicking the payment button, call the Place Order API to complete the payment

7. Error Handling

checkoutFailedHook (Optional)

type：

src/types/hooks.ts
// checkoutFailedHook type definition
(() => void) | (() => Promise<void>)

checkoutFailedHook receives the following parameters：

src/types/hooks.ts
// checkoutFailedHook parameter type definition
(code: string, message: string) => void | Promise<void>;

// code: string - Error code
// message: string - Error message

checkoutFailedHook is used to customize error logic

When user payment fails, PingPong will default to showing a popup with the failure reason. If you want to customize the popup UI or text, you can set this hook function.

This function can return a Promise. If returning Promise, subsequent processes will wait until the Promise status becomes Fulfilled before continuing execution

src/config/payment.js
PingPong.Checkout.checkoutFailedHook = (code: string, message: string) => {
    notification.open({
        message: 'Error title',
        description: `${code}: ${message}`
    })
};

Usage Example：

PingPong Checkout Integration Example

examples

onepage

pages

checkout.html

assets

css

checkout.css

js

config

app-config.js

examples/onepage/pages/checkout.html
examples/onepage/assets/css/checkout.css
examples/onepage/js/config/app-config.js
Home page PingPongCheckout
Copyright ©2015-2026 杭州乒乓智能技术有限公司 All Rights Reserved.