iOS — SPayLater Widget Installation

This guide walks you through adding the SPayLater Promotional Widget to your iOS app. Once installed, ShopeePayKit automatically shows instalment pricing alongside your product prices — and hides itself silently if no pricing data is available, so your layout is never broken by an empty widget.

What this does

ShopeePayKit adds two native iOS views: a banner for Homepage awareness, and an instalment message view for Category and Product Detail Pages. Both views handle their own data fetching and rendering. If the SDK cannot retrieve pricing data (for example, because the product is ineligible), the view collapses to zero height automatically — no empty space is left behind. Installation is a developer task; the steps below include everything your iOS developer needs.

Before you start

• Access Key — your unique SPayLater plugin key. Get it from your ShopeePay account manager if you don't have one yet.
• Store External ID — your ShopeePay store ID (storeExtId). Same source.
• iOS 12+ target, Xcode 15+ — the SDK supports iOS 12 and later. Your build environment must be Xcode 15 or above.
• An iOS developer — the steps below require someone who can edit your Podfile and Objective-C or Swift source files.
• CocoaPods installed — the third-party dependencies are managed via CocoaPods. Run gem install cocoapods if it is not already installed.

Installation steps

Step 1 — Add the third-party CocoaPods libraries

ShopeePayKit depends on SDWebImage and Masonry. Add both to your Podfile, then run pod install from your project root:

source 'https://cdn.cocoapods.org/'
platform :ios, '12.0'
use_frameworks!

target 'YourMerchantApp' do
  pod 'SDWebImage'
  pod 'Masonry'
end

After pod install completes, open the newly created .xcworkspace file instead of the .xcodeproj file for all future Xcode sessions.

Step 2 — Add the ShopeePayKit files to your project

Two XCFrameworks are provided by your ShopeePay account manager (not public CocoaPods pods). Drag and drop both into your Xcode project navigator:

• ShopeePayKit.xcframework
• SDBProtectFramework.xcframework

In the dialog that appears for each framework:

• Check Copy items if needed.
• Select your app target under Add to targets.

Navigate to Your Target → General → Frameworks, Libraries, and Embedded Content and confirm both XCFrameworks are listed. Set each to Do Not Embed — they are static XCFrameworks and should only be linked, not embedded.

In Build Settings, also confirm:

• Other Linker Flags contains -ObjC
• Framework Search Paths includes the folder containing ShopeePayKit.xcframework

Step 3 — Link the required Apple system frameworks

In Your Target → Build Phases → Link Binary With Libraries, add the following frameworks if they are not already present:

• UIKit.framework
• Foundation.framework
• NetworkExtension.framework
• DeviceCheck.framework
• StoreKit.framework
• libresolv.9.tbd
• libc++.tbd

Step 4 — Initialize the SDK

In your AppDelegate (or the equivalent SwiftUI app entry point), initialize ShopeePayKit inside application:didFinishLaunchingWithOptions:. Replace the placeholder values with your real credentials:

SPLConfiguration *configuration =
  [[SPLConfiguration alloc] initWithAccessKey:@"YOUR_ACCESS_KEY"
                                    storeExtId:@"YOUR_STORE_EXT_ID"
                                       country:SPLCountryID
                                      currency:SPLCurrencyIDR
                                      language:SPLLanguageEN
                                   environment:SPLEnvironmentUAT]; // switch to SPLEnvironmentLive for release
[[ShopeePayLaterKit sharedKit] configureWithConfiguration:configuration];

Update SPLCountryID, SPLCurrencyIDR, and SPLLanguageEN to match your target market. Use SPLEnvironmentLive when building for App Store release.

Step 5 — Place the widget on your pages

ShopeePayKit provides two distinct views depending on the page type:

Homepage — Banner view (awareness messaging, no price required):

SPLBannerView *bannerView = [SPLBannerView new];
[self.view addSubview:bannerView];

Category and Product pages — Instalment message view (pricing messaging, requires product ID and amount):

SPLInstallmentMessageView *messageView = [SPLInstallmentMessageView new];
[self.view addSubview:messageView];
[messageView loadWithProductId:@"product_123" amount:@10000 pageType:SPLPageTypeProduct];

Pass SPLPageTypeCategory for listing pages and SPLPageTypeProduct for Product Detail Pages. The amount should be the product price in the smallest currency unit (e.g. cents).

Configuration

How to verify the installation

1. Build and run your app in SPLEnvironmentUAT mode on a real iOS device or Simulator.
2. Navigate to a page where you placed the widget (Homepage, Category, or Product page).
3. Confirm the "Buy Now, Pay Later with SPayLater" messaging appears at the expected position — typically just below the product price.
4. On a Product page, tap the ⓘ info icon next to the instalment line. A pop-up should appear listing the available instalment plans and monthly amounts.
5. Once everything looks correct in UAT, change the environment to SPLEnvironmentLive and submit your App Store build.

Troubleshooting

FAQ

Does the SDK support Swift?

The SDK's public API is in Objective-C, and it is fully interoperable with Swift. Call ShopeePayKit methods from Swift exactly as you would any Objective-C framework — no bridging header is required for projects that use the .xcframework format.

What happens if the instalment data can't be loaded?

The view collapses to zero height and hides itself. No error message is shown to the customer and no empty widget container is left behind. Your layout is unaffected.

Can I customize the widget's appearance?

No. The widget uses SPayLater's standard visual style and cannot be themed. Custom colors or fonts are not supported — this preserves regulatory-reviewed messaging and a consistent trust signal for customers.

Do I need a separate Access Key for UAT and LIVE?

No. Your Access Key is the same across both environments. The environment is controlled by the environment parameter in SPLConfiguration. Switching between UAT and LIVE is a one-line change and a rebuild.