Product Overview

Product Introduction

PingPong Checkout Native SDK is a native checkout SDK for mobile applications, providing a complete payment solution that supports multiple payment methods including credit/debit card payments, Apple Pay, and Google Pay. This SDK aims to simplify the complexity of payment integration for developers, delivering a unified, secure, and seamless payment experience.

Core Value Proposition:

• One-time integration for global mainstream payment methods
• Bottom-sheet checkout experience without leaving the current page
• PCI DSS compliant, reducing compliance costs
• Intelligent 3D Secure verification balancing security and conversion rates

Bottom-Sheet Checkout Experience

What is bottom-sheet checkout: A checkout interface that slides up from the bottom of the screen, allowing users to complete payment operations while maintaining the context of the current page.

Comparison with Traditional Full-Screen Checkout:

Feature	Bottom-sheet checkout	Traditional Full-Screen Checkout
Context Retention	Preserves original page	Complete redirect
Operation Convenience	Tap to close	Tap to return
User Experience	Lightweight overlay	Page transition
Conversion Rate	15-20% improvement	Relatively lower
Integration Complexity	Low (20 lines of code)	Medium

Design Highlights:

• Dynamic Height: Checkout height automatically adjusts based on payment methods
• Smooth Animations: Fluid slide-in/slide-out transitions

Supported Payment Methods

Payment Method	iOS	Android	Description
Apple Pay	✅	-
Google Pay	-	✅
Credit/Debit Card	✅	✅	Supports Visa, Mastercard, Amex, etc.
3D Secure	✅	✅	Automatic verification flow trigger

Integration Process Overview

Overall Sequence Overview:

1. Create Session: Server-side calls /v4/payment/prePay to create a payment session
2. Retrieve Token: Server extracts the token from bizContent.token in the response
3. Initialize and Launch: Client initializes the SDK and launches the checkout using the token
4. Return Result: SDK notifies payment flow status via callbacks (completed/failure/cancel)

Platform Selection

• For iOS integration, see the iOS Integration Guide
• For Android integration, see the Android Integration Guide

---

Prerequisites

Before starting integration, please complete the following preparations:

1. Open Sandbox Account: See Getting Started - Sandbox Account
2. Obtain API Credentials: Contact technical support for accId, clientId, salt. See API Usage Rules

Security Notice

• Salt must be stored server-side only; never expose to client-side
• Sandbox and production environments use different credentials

---

Quick Start

Overall Integration Flow

Server-Side: Create Payment Session

API Description

Item	Content
Request Method	POST
Sandbox Environment	https://sandbox-acquirer-payment.pingpongx.com/v4/payment/prePay
Production Environment - Europe	https://acquirer-payment.pingpongx.com/v4/payment/prePay
Production Environment - US	https://acquirer-payment-checkout-us.pingpongx.com/v4/payment/prePay
Content-Type	application/json

Note

For complete parameter descriptions, please refer to the Create Payment Session API.

Request Parameters

Common Request Parameters

Common request parameters (accId, clientId, signType, sign, version, bizContent) are described in API Usage Rules.

Signature

Native SDK server-side APIs follow the PingPongCheckout unified signature specification. Supported signature types: MD5 and SHA256 (recommended). For detailed signature algorithm steps and code examples, please refer to Signature Rules.

Business Request Parameters (bizContent)

Parameter	Type	Required	Description
merchantTransactionId	String(64)	M	Merchant order number, globally unique
amount	String(12)	M	Transaction amount
currency	String(3)	M	Transaction currency, ISO 4217
notificationUrl	String(255)	O	Webhook notification URL
goods	Array	M	Product information list
billingAddress	Object	M	Billing address

curl Request Example

curl - Create Payment Session

curl -X POST https://sandbox-acquirer-payment.pingpongx.com/v4/payment/prePay \
  -H "Content-Type: application/json" \
  -d '{
    "accId": "2018092714313010016291",
    "clientId": "2018092714313010016",
    "signType": "SHA256",
    "sign": "28178F3C0B0AF10343F715211B9C7791AB4CF091EB4580505E053318E8F37B85",
    "version": "1.0",
    "bizContent": "{\"merchantTransactionId\":\"ORDER_123456\",\"amount\":\"100.00\",\"currency\":\"USD\",\"goods\":[{\"name\":\"Product A\",\"sku\":\"SKU001\",\"unitPrice\":\"100.00\",\"number\":\"1\"}],\"customer\":{\"firstName\":\"James\",\"lastName\":\"LeBron\",\"email\":\"123456@gmail.com\",\"phone\":\"3055787343\"},\"billingAddress\":{\"street\":\"1986 Broad Street\",\"city\":\"Birmingham\",\"state\":\"AL\",\"country\":\"US\",\"postcode\":\"35222\"}}"
  }'

Response Example

POST /v4/payment/prePay Response

{
  "code": "000000",
  "description": "Transaction succeeded",
  "accId": "2018092714313010016291",
  "clientId": "2018092714313010016",
  "signType": "SHA256",
  "sign": "337DE4525BECC73D56E262E04CCCC210C7BA70C78D48DA3BB128E4FEC6D01561",
  "bizContent": {
    "transactionId": "2023092050004591",
    "merchantTransactionId": "ORDER_123456",
    "token": "EU:vr_YVR8u7rn7C1gG97DOg9_-Y66ubtNtoayJ_wiEEzdCnxCHYIk0pXordJYBjq1g",
    "paymentUrl": "https://sandbox-acquirer-payment-ssr.pingpongx.com/v3/checkout?token=xxx",
    "innerJsUrl": "https://paycdn.pingpongx.com/production/static/sdk/ppPay.min.js?token=xxx",
    "amount": "100.00",
    "currency": "USD"
  }
}

Extracting the Token

Extract the token from the response field bizContent.token and pass it to the SDK for initialization.

Client-Side: Launch Payment

iOS

ViewController.m

#import <PPCashDeskSDK/PPCashDeskSDK.h>

// Configure SDK
PPCDManager *manager = [PPCDManager sharedInstance];
PPCDConfig *config = [[PPCDConfig alloc] init];
config.environmentType = PPCDEnvironmentTypeSandBox; // Sandbox environment
config.shouldStartRecLog = YES;

manager.config = config;

// Initialize and launch the checkout
[manager initWithToken:@"your_token"
             completed:^(NSString *code) {
    // Payment information submitted successfully. This does NOT indicate payment success.
    // Verify final status via server-side confirmation.
    NSLog(@"Payment info submitted: %@", code);
}
             failure:^(NSError *error) {
    // Payment flow failed or was interrupted.
    // Always verify final status via server-side confirmation.
    NSLog(@"Payment flow failed: %@", error.localizedDescription);
}
             cancel:^{
    // User canceled
    NSLog(@"User canceled payment");
}];

Android

PaymentActivity.kt

// 1. Create payment instance
val payment = PPPayment(activity) { result ->
    when (result) {
        is PaymentResult.Completed -> {
            // Payment information submitted successfully. This does NOT indicate payment success.
            // Verify final status via server-side confirmation.
            Log.d("Payment", "Payment info submitted")
        }
        is PaymentResult.Canceled -> {
            // User canceled
            Log.d("Payment", "User canceled")
        }
        is PaymentResult.Failed -> {
            // Payment flow failed or was interrupted.
            // Always verify final status via server-side confirmation.
            Log.e("Payment", "Payment flow failed: ${result.error}")
        }
    }
}

// 2. Configure parameters
val config = PaymentConfig(
    environment = Environment.SANDBOX,  // Test environment
    logEnabled = true,                  // Enable/disable SDK logging
    cardBinLength = true                // Set card BIN digit length
)

// 3. Launch the checkout
payment.presentPayment(
    token = "your_token",
    config = config
)

Verify Payment Result

Dual Verification Mechanism:

1. Client Callback: SDK notifies interaction status via callbacks (completed/failure/cancel), which does not represent the payment result
2. Server Confirmation: Obtain final payment status via Webhook or query interface (used for order status updates)

Important Notice

Client callbacks are for reference only; always rely on server-side query results as the source of truth.

---

Payment Result Handling

Client-side Status Handling

SDK Callback Trigger Timing and Processing Logic:

Scenario	Triggered Callback	Processing Recommendation
User taps pay button, payment interface returns success	iOS: completed Android: Completed	Display processing prompt, long polling server for final payment result
User taps bottom-sheet close button	iOS: cancel Android: Canceled	Return to order page, can prompt user "Payment canceled"
Payment flow failed or was interrupted	iOS: failure Android: Failed	Display error message, prompt user to retry payment

Important Notice

• iOS: completed (Android: Completed) callback only indicates payment information was submitted successfully, NOT payment success
• At this point, payment may still be processing (bank processing / risk control review, etc.)
• Must obtain final payment status via long polling from server

Server-side Status Handling

The merchant server must obtain the final payment result through the following methods:

Method	Description	Priority
Webhook Callback	PingPong actively pushes payment results	Recommended
Active Query	Call query interface to get order status	Fallback

Note

For Webhook asynchronous notification details, see the Async Notification documentation.

Processing Flow:

Notes:

• Webhook and active query results require idempotency control (recommend using transactionId + status)
• Return HTTP 200 after receiving Webhook, otherwise retry will be triggered
• Retry intervals: 5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h

Webhook Notification Payload Example:

Webhook Notification Payload

{
  "clientId": "2023101115545610265",
  "code": "000000",
  "bizContent": {
    "transactionId": "2024050650046448",
    "merchantTransactionId": "PMT-K52GNL5ZY21714991465240",
    "status": "SUCCESS",
    "amount": "100.00",
    "currency": "USD"
  },
  "sign": "...",
  "signType": "SHA256"
}

For Webhook callback receiving methods, retry mechanism, and signature verification requirements, see Async Notification.

Active Query API

Item	Content
Request Method	POST
API Path	/v4/payment/query
Content-Type	application/json

Query Request Parameters (bizContent)

Parameter	Type	Required	Description
transactionId	String	C	PingPong transaction ID
merchantTransactionId	String	C	Merchant order number

Note

At least one must be provided.

Previous pageElements SDK

Next pageiOS Integration Guide