SDK integration

Follow these steps to add the PayPal Mobile Checkout SDK to your iOS app

SDKBetaLast updated: November 4th 2022, @ 7:45:08 am

Know before you code

• Complete the steps in Get started to set up your PayPal account, client ID, and sandbox emails for testing.

• Client-side and server-side integrations share many of the same integration steps. Both ways to integrate will be covered in this documentation.

• The PayPal Mobile Checkout SDK uses scopes from the Identity API.

  Note: Before going live, PayPal must review your app to approve the sharing of customer data. The review automatically starts once you select the Log in with PayPal checkbox on your Developer Dashboard (Step 3 of Enable the SDK). The review for sandbox apps typically completes within 2 hours. The review for live apps typically completes within 2 business days, but under certain circumstance, can take up to 10 business days.

Enable the SDK

1. Log into your PayPal Developer Dashboard.

2. Select your app from the My Apps & Credentials page on the Developer Dashboard.

3. Under Sandbox App Setting, select the Log in with PayPal checkbox.

Step result

The SDK is enabled.

Add the SDK to your app

Add the SDK to your app using your preferred installation method:

• CocoaPods
• Carthage
• Swift Package Manager
• GitHub

Note: For the easiest installation, we recommend using CocoaPods.

CocoaPods

1. Add the following to your Podfile:

   pod 'PayPalCheckout'
   

2. Run pod install or pod update.

Carthage

1. Add the following to your Cartfile:

   binary "https://github.com/paypal/paypalcheckout-ios/raw/main/Carthage/PayPalCheckout.json"
   

2. Download the binaries using the following command:

   carthage update --platform iOS
   

3. Link the .framework file from the /Carthage/Build/iOS directory into your specified target:

Note: This embeds PayPalCheckout.

Swift Package Manager

If you're working in the context of another package, you can add the SDK as a dependency in your Package.swift file by:

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(url: "https://github.com/paypal/paypalcheckout-ios.git", from: "0.42.0"),
    ],
    ...
)

If you're adding the SDK into a standalone project, follow Apple's package integration guide, while specifying https://github.com/paypal/paypalcheckout-ios.git as the source Git repository.

GitHub

If you prefer to install the SDK without using a package manager, retrieve the framework and xcframework binaries from the release tags in our GitHub repository.

Step result

The SDK is now in your app.

Configure the SDK

Create an instance of CheckoutConfig, and pass it to the top level Checkout type of the SDK.

Sample code

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: AppDelegateLaunchOpts?
) -> Bool {

    let config = CheckoutConfig(
        clientID: "YOUR_CLIENT_ID",
        environment: .sandbox
    )

    Checkout.set(config: config)

    return true
}

Step result

Your SDK is configured and your app is ready to add payment buttons. Payment buttons display on your app.

Integrate the SDK

You have two options to complete your integration:

We will cover both in the following sections.

Client-Side Integration: Create and capture orders

Sample PayPal Mobile Checkout SDK code for iOS

This sample code creates an order of a single item for $10.00 USD. When the buyer selects Pay Now on a payment sheet, the onApprove callback invokes and the funds are ready for immediate capture.

import PayPalCheckout

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        configurePayPalCheckout()
        addPayPalButtons()
    }

    // MARK: PayPal Checkout

    private func configurePayPalCheckout() {
        Checkout.setCreateOrderCallback { action in
            let amount = PurchaseUnit.Amount(currencyCode: .usd, value: "10.00")
            let purchaseUnit = PurchaseUnit(amount: amount)
            let order = OrderRequest(intent: .capture, purchaseUnits: [purchaseUnit])

            action.create(order: order)
        }
        Checkout.setOnApproveCallback { approval in
            approval.actions.capture { response, error in
                print("Order successfully captured: \(response?.data)")
            }
        }
    }
        
    private func addPayPalButtons() {
        let container = PaymentButtonContainer()
        view.addSubview(container)
        NSLayoutConstraint.activate(
            [
                container.centerYAnchor.constraint(equalTo: view.centerYAnchor),
                container.centerXAnchor.constraint(equalTo: view.centerXAnchor)
            ]
        )
    }
}

Add and modify the code

1. (Optional) Add the OnCancel callback to be notified if the buyer cancels the order.

   Checkout.setOnCancelCallback {
       // User has cancelled the payment experience
   }
   

2. (Optional) Add the OnError callback to be notified if the SDK encounters an error, resulting in the dismissal of the payment sheet.

   Checkout.setOnErrorCallback { error in
       // Handle the error generated by the SDK
   }
   

3. (Optional) Configure the following messages to display to the buyer:

   • Success message when funds capture successfully.
   • Cancellation confirmation when the buyer selects to cancel the order.
   • Error message when the capture is unsuccessful.

4. If you want to use something other than the PayPal payment buttons, you can Programmatically start the SDK.

Note: For more information about creating orders, including additional parameters that can be submitted, view Orders REST API.

Step result

You can now test purchases.

Test and go live

• Use your client ID when adding the PayPal Mobile Checkout SDK to your app.
• Use your sandbox accounts when testing the SDK.
• The SDK may prompt buyers to log in with a one-time passcode sent by SMS to their phone number.
• Sandbox accounts with a confirmed phone number and US as the selected country will always prompt the buyer to log in with a one-time passcode.
• When testing the SDK with sandbox accounts, enter 111111 as the one-time passcode.

Server-Side Integration: Create and capture orders

You can integrate the PayPal Mobile Checkout SDK for iOS with your existing server-side PayPal integration. Server-side integrations offer greater flexibility and control than client-side integrations, enabling you to better ensure compatibility with your other integrations. A server-side integration also enables you to generate your own tokens.

Know before you code

Before integrating, determine which of the following server-side integrations you want to use:

• NVP/SOAP
• REST v1
• REST v2

Note: If you're integrating for the first time, we recommend using the REST v2 server-side integration.

You must complete the first five steps in a Client-side integration.

Launch the payment sheet

Similar to the client-side integration, you can launch the payment sheet by passing a CreateOrder callback into your Checkout.setCreateOrderCallback function. The only difference is that instead of creating an Order, you provide the order ID through the provided set function.

Checkout.setCreateOrderCallback { createOrderAction in
    // Retrieve order ID or EC-token from server-side integration
    createOrderAction.set(orderId: "EC-XXXXXXXXXXXXXXXXX")
}

Ensure the payment sheet launches as soon as the buyer selects the PaymentButton by making your server-side request from within the CreateOrder callback.

Note: The CreateOrder callback invokes from the main thread. Ensure all server-side requests execute from a background thread.

Capture or authorize an order

The iOS SDK supports capturing and authorizing orders created through both client-side or server-side integrations using either PayPal-generated tokens or your own generated tokens.

To capture or authorize through a server-side integration, use the following to register the OnApprove callback through Checkout.setOnApproveCallback:

Checkout.setOnApproveCallback { approval in
    // Optional -- retrieve order details first
    yourAppsCheckoutRepository.getEC(approval.data.orderId);

    // Send the order ID to your own endpoint to capture or authorize the order
    yourAppsCheckoutRepository.captureOrder(approval.data.orderId)
}

Test and go live

Use your client ID when adding the PayPal Mobile Checkout SDK to your app. Use your sandbox accounts when testing the SDK.

Next steps

• Customize payment buttons

See also

• Identity API
• Orders REST API
• Programmatically start the SDK
• Server-side integration
• To view the complete set of generated class references, see PayPal Mobile Checkout iOS SDK.