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
Log into your PayPal Developer Dashboard.
Select your app from the My Apps & Credentials page on the Developer Dashboard.
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:
Note: For the easiest installation, we recommend using CocoaPods.
CocoaPods
Add the following to your
Podfile
:pod 'PayPalCheckout'
Run
pod install
orpod update
.
Carthage
Add the following to your
Cartfile
:binary "https://github.com/paypal/paypalcheckout-ios/raw/main/Carthage/PayPalCheckout.json"
Download the binaries using the following command:
carthage update --platform iOS
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:
Integration type | Use case |
---|---|
Client-side integration | If want the simplest integration, continue with the sample code below for a client-side integration. Client-side integrations don't require you to create your own backend infrastructure. |
Server-side integration | Chose a server-side integration if you want more control over your integration. Server-side integrations require you to have your own backend infrastructure. |
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
(Optional) Add the
OnCancel
callback to be notified if the buyer cancels the order.Checkout.setOnCancelCallback { // User has cancelled the payment experience }
(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 }
(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.
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:
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
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.