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

# iOS Integration Guide

::: tip Prerequisites
Before starting iOS 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 iOS is designed for merchants that want to present PingPong Checkout as a bottom-sheet payment experience inside their own iOS app. Your server creates the payment session through [prePay](/en/notes/checkout/api/reserve/), and the iOS client uses the returned `token` to launch the checkout.

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

## Payment Experience

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

## Environment Requirements

| Item | Requirement |
|------|-------------|
| iOS Version | 15.6+ |

## Import Instructions

### Manual Integration

1. Download the SDK's `.framework` and `PPCashDeskSDKBundle.bundle` resource files
2. Drag both files into your project path

### Dependencies

Ensure the following dependencies are included in your Podfile:

| Dependency | Version | Description |
|------------|---------|-------------|
| AFNetworking | 4.x | Network requests |
| SDWebImage | 5.x | Image loading and caching |
| MJExtension | 3.x | JSON and model conversion |
| MJRefresh | 3.x | Pull-to-refresh and infinite scroll |
| Masonry | 1.x | Auto layout |
| MBProgressHUD | 1.x | Loading indicators |
| Bugly | - | Error monitoring |

## 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: 🚀 iOS Interaction Sequence

    App->>+SDK: 1. initWithToken
    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 |
|------------|-------------|
| PPCDManager | SDK main entry class, singleton pattern |
| PPCDConfig | SDK configuration class |
| PPPaymentRequest | Payment request parameters |
| PPPaymentResult | Payment result callback |

### Environment Configuration

**Environment Enumeration**:

```objc:line-numbers title="PPCDEnvironmentType.h"
typedef NS_ENUM(NSInteger, PPCDEnvironmentType) {
    PPCDEnvironmentTypeRelease = 1,    // Production Europe
    PPCDEnvironmentTypeSandBox = 4,    // Sandbox
    PPCDEnvironmentTypeReleaseUS = 6   // Production US
};
```

| Enumeration Value | Value | Description | API Endpoint |
|-------------------|-------|-------------|--------------|
| PPCDEnvironmentTypeSandBox | 4 | Sandbox Environment | `https://sandbox-acquirer-payment.pingpongx.com` |
| PPCDEnvironmentTypeRelease | 1 | Production Environment - Europe | `https://acquirer-payment.pingpongx.com` |
| PPCDEnvironmentTypeReleaseUS | 6 | Production Environment - US | `https://acquirer-payment-checkout-us.pingpongx.com` |

**Configuration Example**:

```objc:line-numbers title="PPCDConfig Initialization"
PPCDConfig *config = [[PPCDConfig alloc] init];
config.environmentType = PPCDEnvironmentTypeSandBox;    // Sandbox
// config.environmentType = PPCDEnvironmentTypeRelease;    // Production Europe
// config.environmentType = PPCDEnvironmentTypeReleaseUS;  // Production US
```

## Key Integration Steps

### Step 1: Initialize SDK

```objc:line-numbers title="AppDelegate.m"
#import <PPCashDeskSDK/PPCashDeskSDK.h>

// Get SDK instance
PPCDManager *manager = [PPCDManager sharedInstance];

// Configure SDK
PPCDConfig *config = [[PPCDConfig alloc] init];
config.environmentType = PPCDEnvironmentTypeRelease;    // Set network environment
config.shouldStartRecLog = YES;                         // Enable logging
config.cardBinLengthValue = 11;                         // Set card BIN digit length
config.applePayMerchantId = @"";                        // Set ApplePay MerchantId, requires user to apply and configure

manager.config = config;
```

**Configuration Parameters Description**:

| Parameter | Type | Description |
|-----------|------|-------------|
| environmentType | enum | PPCDEnvironmentTypeSandBox / PPCDEnvironmentTypeRelease |
| shouldStartRecLog | BOOL | Enable logging |
| cardBinLengthValue | int | Set card BIN digit length |
| applePayMerchantId | String | Set ApplePay MerchantId, requires user to apply and configure |

### Step 2: Launch Checkout

```objc:line-numbers title="PaymentViewController.m"
[manager initWithToken:@"your_token"
             completed:^(NSString *code) {
    // Payment information submitted successfully. This does NOT indicate payment success.
    // Verify final status via server-side confirmation.
}
             failure:^(NSError *error) {
    // Payment flow failed or was interrupted.
    // Always verify final status via server-side confirmation.
}
             cancel:^{
    // User canceled
}];
```

## Apple Pay Configuration

### Configure Developer Account

1. **Create Merchant Identifier**:
   - Log in to Apple Developer Center, select "Merchant IDs"
   - Enter a unique identifier (format: `merchant.com.{app_name}`)

2. **Generate Payment Processing Certificate**:
   - In Developer Center, select the corresponding merchant identifier, click "Create Certificate"
   - Download CSR file (generated via Xcode or terminal), upload to obtain `.cer` certificate file

3. **Pass Merchant ID**:

```objc:line-numbers title="ApplePay Merchant ID Configuration"
PPCDConfig *config = [[PPCDConfig alloc] init];
config.applePayMerchantId = @"merchant.com.yourapp";
manager.config = config;
```