---
title: Native SDK - Android Integration Guide
permalink: /en/notes/integrate/native-sdk-android/
createTime: '2026/04/03 10:00:00'
description: >-
  Complete guide for integrating PingPong Checkout Native SDK on Android, covering environment requirements, import instructions, SDK configuration, and key integration steps.
---

# Android Integration Guide

::: tip Prerequisites
Before starting Android integration, make sure you have completed the preparation process and server-side integration in the [Embedded SDK overview](/en/notes/integrate/sdk-v4/).
:::

## Integration Summary

Native SDK for Android is designed for merchants that want to present PingPong Checkout as a bottom-sheet payment experience inside their own Android app. Your server creates the payment session through [prePay](/en/notes/checkout/api/reserve/), and the Android client uses the returned `token` to launch the checkout.

For Google Play submission, privacy declarations, and review guidance, refer to [App Submission & Compliance](/en/notes/integrate/app-compliance/overview/).

## Payment Experience

![Android native SDK payment experience](/images/integrate/sdk-experience/android_native_sdk_ui.png)

## Environment Requirements

| Item | Requirement |
|------|-------------|
| Android Gradle Plugin (AGP) | 8.13.2 |
| Java | 17 |
| Android SDK | compileSdk 36, targetSdk 36, minSdk 24 |
| OkHttp | 4.12.0 |
| Gson | 2.11.0 |
| Retrofit | 2.11.0 |

## Import Instructions

### Manual Integration

1. Download the Android SDK AAR file.

   Please contact PingPong technical support to obtain the download URL.

2. Import dependency into Android Studio project.

   Copy the aar file to the module's libs directory, add dependency in module's gradle file:

```groovy:line-numbers title="build.gradle"
dependencies {
    implementation files('libs/payment-android-sdk-1.0.0.aar')
}
```

## Payment Flow

```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',
    'noteBkgColor': '#E1F5FE',
    'noteTextColor': '#01579B',
    'noteBorderColor': '#0288D1',
    'loopTextColor': '#0D47A1',
    'activationBkgColor': '#B3E5FC',
    'activationBorderColor': '#0277BD'
  }
}}%%

sequenceDiagram
    participant App as 💻 Merchant App
    participant SDK as 📱 PingPong Native SDK
    participant Server as 🏪 Merchant Server
    participant PP as 🔄 PingPong Server
    participant Bank as 🏦 Card Issuer/Payment Channel

    Note over App, Bank: 🚀 Android Interaction Sequence

    App->>+SDK: 1. Create PPPayment instance
    SDK->>+PP: 2. Validate Token
    PP-->>-SDK: 3. Return payment method list
    SDK-->>-App: 4. Display bottom-sheet checkout

    Note over App, Bank: 💳 Payment Process

    alt ✅ User completes payment
        App->>SDK: 5. User selects payment method
        SDK->>+PP: 6. Submit payment request
        PP->>+Bank: 7. Route to bank/payment channel for processing
        Bank-->>-PP: 8. Return processing result
        PP-->>-SDK: 9. Return payment information
        SDK-->>App: 10. Callback completed/failure
        App->>+Server: 11. Long polling query for payment result
        Server-->>-App: 12. Return final payment status
    else ❌ User taps close button
        App->>SDK: 13. Tap close
        SDK-->>App: 14. Callback cancel
    end

    Note over App, Bank: 📡 Webhook Notification

    Note over PP, Server: PingPong sends asynchronous notifications via webhook

    Note over App, Bank: 🎯 Flow Ends
```

## SDK Configuration and Key Objects

### Key Objects Description

| Class Name | Description |
|------------|-------------|
| PPPayment | SDK main entry class |
| PaymentConfig | SDK configuration class |
| PaymentResult | Payment result callback (Sealed Class) |
| Environment | Environment enumeration (SANDBOX/ONLINE/ONLINE_US) |

### Environment Configuration

**Environment Enumeration**:

```kotlin:line-numbers title="Environment.kt"
enum class Environment {
    SANDBOX,     // Sandbox environment
    ONLINE,      // Production environment - Europe
    ONLINE_US    // Production environment - US
}
```

| Enumeration Value | Description | API Endpoint |
|-------------------|-------------|--------------|
| SANDBOX | Sandbox Environment | `https://sandbox-acquirer-payment.pingpongx.com` |
| ONLINE | Production Environment - Europe | `https://acquirer-payment.pingpongx.com` |
| ONLINE_US | Production Environment - US | `https://acquirer-payment-checkout-us.pingpongx.com` |

**Cross-Platform Mapping**:

| Android | iOS Equivalent | Description |
|---------|----------------|-------------|
| `SANDBOX` | `PPCDEnvironmentTypeSandBox` | Sandbox environment |
| `ONLINE` | `PPCDEnvironmentTypeRelease` | Production Europe |
| `ONLINE_US` | `PPCDEnvironmentTypeReleaseUS` | Production US |

**Configuration Example**:

```kotlin:line-numbers title="PaymentConfig Initialization"
val config = PaymentConfig(
    environment = Environment.SANDBOX,    // Sandbox
    // environment = Environment.ONLINE,  // Production Europe
    // environment = Environment.ONLINE_US  // Production US
    logEnabled = true,
    cardBinLength = true
)
```

## Key Integration Steps

### Step 1: Initialize SDK

```kotlin:line-numbers title="PaymentConfig.kt"
val config = PaymentConfig(
    environment = Environment.SANDBOX, // Control environment switch
    logEnabled = true, // Enable/disable SDK logging
    cardBinLength = true // Set card BIN digit length
)
```

### Step 2: Launch Checkout

```kotlin:line-numbers title="PaymentActivity.kt"
// 1. Create payment instance
val payment = PPPayment(activity, PaymentResultCallback { result ->
    when (result) {
        is PaymentResult.Completed -> {
            // Payment information submitted successfully. This does NOT indicate payment success.
            // Verify final status via server-side confirmation.
        }
        is PaymentResult.Canceled -> {
            // User canceled
        }
        is PaymentResult.Failed -> {
            // Payment flow failed or was interrupted.
            // Always verify final status via server-side confirmation.
        }
    }
})

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