The simplest way to integrate Universal Checkout is with our drop-in UI. With just a few lines of code, you can display a fully in-context checkout UI with all your payment methods.

If you're looking for a more customizable way of integrating Universal Checkout, consider integrating Headless Checkout.

Not all payment methods are currently compatible with Drop-in Checkout.

Please refer to this table to learn more about the payment methods available for Drop-in Checkout.

Before you start

Before you start, make sure:

Create a client session

A client session is the starting point for integrating payments at Primer. You can attach any data associated with the order to your client session.

Creating a client session provides you with a client token, a temporary key used to initialize the Universal Checkout.

The information you include in the client session is used in the Dashboard:

  • to conditionally route payments with Workflows
  • to activate payment methods and other features in Universal Checkout

So pass as much information as you can!

Generate an API key

Requests to our API are authenticated using an API key in the X-Api-Key header. Create an API key by visiting the developer page of the Primer Dashboard.

Make sure to set the following scopes for your API Key:

  • client_tokens:write
  • transactions:authorize

Make a client session request

On your server, create a client session with POST/client-session.

Make sure to pass at least the following data:

Your reference for the payment.

Make sure to keep track of orderId - you will later receive updates to the payment via Webhooks. The payment will contain the orderId specified in the client session.
The three-letter currency code in ISO 4217 format.
e.g. use USD for US dollars.
  1. order
The details of the line items of the order.

The body of a successful response contains a clientToken that you will use to initialize the Universal Checkout.

Here is how the client session request to the Primer API should look like:

curl --location --request \ POST '' \ --header 'X-Api-Key: <YOUR_API_KEY>' \ --header 'X-Api-Version: 2.2' \ --header 'Content-Type: application/json' --data '{    "orderId": "<YOUR_ORDER_ID>",    "currencyCode": "GBP",    "amount": 5000,    "order": {      "lineItems": [{        "itemId": "shoes-123",        "amount": 2500,        "quantity": 2      }],      "countryCode": "GB",    } }'
# Here is a (heavily truncated) example response
{  "clientToken": "THE_CHECKOUT_SESSION_TOKEN",  "clientExpirationDate": "2022-03-08T14:00:00Z",  "orderId": "<YOUR_ORDER_ID>",  "currencyCode": "GBP",  "amount": 5000,    "order": {      "lineItems": [{        "itemId": "shoes-123",        "amount": 2500,        "quantity": 2      }],      "countryCode": "GB",    }}

To use new Workflows and all of its exciting features, make sure to pass the following header in your API request:

Legacy-Workflows: false

See this migration guide for more information.

Install the SDK

With CocoaPods

Add the following in your Podfile:

target 'MyApp' do
  # 👇 Add this line  pod 'PrimerSDK'
  # ...

Then run pod install to install PrimerSDK on your workspace.

In case you encounter an error that the bundle needs signing on Xcode 14, add the following post-install script in your podfile.

post_install do |installer|  installer.pods_project.targets.each do |target|    if target.respond_to?(:product_type) and target.product_type == ""      target.build_configurations.each do |config|          config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'      end    end  endend

With Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into Xcode. In order to add PrimerSDK with Swift Package Manager:

  1. 1
    Select your project, and then navigate to Package Dependencies
  2. 2
    Click on the + button at the bottom-left of the Packages section
  3. 3
    Paste into the Search Bar, or search for primer-sdk-ios in the Search Bar.
  4. 4
    Press Add Package
  5. 5
    Let Xcode download the package and set everything up

For more details about SDK versions, please see our changelog.

Initialize Universal Checkout

Import the PrimerSDK and set its delegate as shown in the following example:

import PrimerSDK
class MyViewController: UIViewController, PrimerDelegate {
    override func viewDidLoad() {        super.viewDidLoad()
        // Initialize the SDK with the default settings.        Primer.shared.configure(delegate: self)    }
    func primerDidCompleteCheckoutWithData(_ data: PrimerCheckoutData) {        // Primer checkout completed with data        // do something...    }}

See all the configurations in the SDK Reference.

Show Universal Checkout

At this step you should have a client token available - see Manage Client Sessions for more.

Call the showUniversalCheckout(clientToken:) function (as shown below) to present Universal Checkout.

class MyViewController: UIViewController, PrimerDelegate {
    func startUniversalCheckout() {        Primer.shared.showUniversalCheckout(clientToken: self.clientToken)    }}

You should now be able to see Universal Checkout! The user can now interact with Universal Checkout, and the SDK will create the payment. The payment’s data will be returned on primerDidCompleteCheckoutWithData(_:) configured in the previous step.

When the user interacts with the checkout and clicks to pay, the Universal Checkout:

  • Shows the payment method screen if applicable
  • Tokenizes the payment method for payment
  • Creates the payment
  • Handles any other interactions (e.g. 3DS)

Handle successful payments

Listen to delegate function

Listen to the primerDidCompleteCheckoutWithData(_:) delegate function

This function will notify you of a successful payment.

class MyViewController: UIViewController {
        // ...
    func primerDidCompleteCheckoutWithData(_ data: PrimerCheckoutData) {        // Primer checkout completed with data        // Do something with the data, e.g. show the payment id    }}

Handle webhooks in your dashboard

To receive updates about the status of your payments you’ll need to listen to webhooks. This is particularly useful for updating an order or any other data stored server-side.

Head to the Developers section of the Primer Dashboard to setup and test a webhook for PAYMENT.STATUS event.

If you are not yet ready to receive webhooks, you can use to test your implementation.

Handle failed payments

Any errors, cancelled payment interactions or failed payments will trigger the primerDidFailWithError(_:data:decisionHandler:) delegate function.

class MyViewController: UIViewController, PrimerDelegate {
        // ...
    func primerDidFailWithError(_ error: Error, data: PrimerCheckoutData?, decisionHandler: @escaping ((PrimerErrorDecision) -> Void)) {        // 👇 Call the decision handler to show a failure message        decisionHandler(.fail(withErrorMessage: message))    }}