Follow this guide to start accepting online payments on iOS with Primer using Universal Checkout

Generate a client token

Get an API Key

You require an API Key to talk with our APIs. Head to the developers area to manage your API keys.

Find out more about API Keys in our API Reference

Generate a Client Session

A client session is the starting point for integrating payments at Primer. You can attach all the additional data associated with the order to the client session, and generate a client token, a temporary key used to initialize Universal Checkout.

The information you include in the client session is used in the Dashboard to conditionally route payments with Workflows, and activate payment methods and other features in Universal Checkout, so pass as much information as you can.

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

1234567891011121314151617181920

# Generate a client token with cURLcurl --location --request \  POST 'https://api.sandbox.primer.io/client-session' \  --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": 4999,    "customerId": "<YOUR_CUSTOMER_ID>"    "order": {      "lineItems":  [{        "itemId": "shoes-123",        "amount": 2500,        "quantity": 2      }],      "countryCode": "GB"    }  }'

Example Response

12345678910

{  "clientToken": "<THE_CLIENT_TOKEN>",  "clientTokenExpirationDate": "2021-08-12T16:14:08.578695",  "orderId": "<YOUR_ORDER_ID>",  "currencyCode": "GBP",  "amount": 1200,  "customerId": "<YOUR_CUSTOMER_ID>",  "metadata": {},  "warnings": []}

As a rule of thumb, pass as much information as you can when creating the client session. As a minimum, make sure to pass:

Set up Universal Checkout

Step 1. Install the SDK

With CocoaPods

The iOS SDK is available with Cocoapods. Just add the PrimerSDK pod and run pod install.

123456

target 'MyApp' do  # Other pods...   # Add this to your Podfile  pod 'PrimerSDK' # Add this lineend

For specific versions of the SDK, please refer to the changelog.

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;

Step 2. Initialize the SDK

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

12345678910111213141516171819

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

Step 3. Generate a client token

Make an API call to your backend to fetch a client token. Here is a simple example of how it can be done from your view controller. Once successful store your client token for future use.

12345678

extension MyViewController {     func requestClientToken(data: [String: Any], completion: @escaping (String?, Error?) -> Void) {    Networking.createClientSession(data: data) { (clientToken, err) in      completion(clientToken, err)    }    }}

Step 4. Show Universal Checkout

At this step you should have a client token available. Call the showUniversalCheckout(clientToken:) function (as shown below) to present Universal Checkout.

12345

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

Step 5. Process the Payment Status Webhook

Create a PAYMENT.STATUS Webhook on your Dashboard to be notified of payment status changes on your backend. Use this event as a single source of truth to update your database and to fulfill the order.

12345678

app.post('/webhooks/payment-status', async (req, res) => {    const { eventType, payment } = req.body    const { id, orderId, status } = payment     if (status === 'AUTHORIZED' || status === 'SETTLED') {        // Fullfil the order for the Payment / Client Session labelled with `orderId`    }})

Step 6. Customize Universal Checkout

Head to our Customization guide to learn more about the styling options.

Take a look at our Advanced guides to adapt Universal Checkout to your needs.

Step 7. Prepare 3DS

3DS is supported out of the box by Universal Checkout

To improve 3DS success rates, it is recommended to pass the following elements in the Client Session:

Learn more about how to configure 3DS!

Did It Work?

If everything went well, you should be able to see the payment you just created on your dashboard under the Payments menu.