Universal Checkout


The first fully dynamic checkout

Universal Checkout is a drop-in UI for web and mobile, with a no-code interface for product and payments teams. Now payments can be a first-class product area in your organization.

uc styling

πŸ›’

Accessible and responsive UX that presents the payment methods you choose, along with 3D Secure 2.0 and convenient checkout modules, fully in-context with no redirects, ever!

πŸŽ›οΈ

Use the Dashboard to activate a custom set of payment methods and checkout modules based on amount, currency, customer location and more.

🎨

Completely customizable, embedded UI for seamless user experience on your site or in your app

πŸ”

PCI Level 1 compliant with a centralized vault for recurring payments and one-click checkout

πŸŽ‰

Low code integration that you won't have to touch when adding new payment methods, processors or other Connections

πŸš€

Fully dynamic checkout driven by Workflows that let you fully automate end-to-end payment flows for the first time

Payment method tokenization

Universal Checkout securely captures payment method data while fully embedded on your site or in your app. By communicating directly with Primer's PCI-L1 tokenization service, Universal Checkout transforms sensitive customer data into a secure uniform string called a payment method token.

You can safely pass this token to your backend to create payments with the Payments API, with no compliance risk.



payment instrument

πŸš€

Our agnostic tokenization service and centralized vault enable you to handle recurring payments, fallbacks and retries across processors without compromising UX. No more PSP-specific tokens β€” now you own your payments data.


So, how does it work?

flow

Whether you're embedding in a website or a mobile app:

  1. 1
    Generate a clientToken on your backend.
  2. 2
    Initialize Universal Checkout with the clientToken to render the UI.
  3. 3
    Universal Checkout will generate a paymentMethodToken when the customer submits their payment data.
  4. 4
    Create a payment using the paymentMethodToken via the Payments API.
  5. 5
    If the response indicates a requiredAction , you'll get a new clientToken.
  6. 6
    Pass the clientToken back to Universal Checkout to render next steps, like 3DS, and get a resumeToken.
  7. 7
    Call POST/payments/{id}/resume with the resumeToken to wrap things up. (If a new requiredAction is returned, you'll have to go back to step 5.)
🚨

Universal Checkout can dynamically handle front-end payment flows constructed in Worklows such as 3D Secure, KYC and more, enabling your payments team to craft new commerce experiences with no additional code.


Manage your checkout with no code

Checkout Builder is a no-code interface in the Dashboard enabling you to simply drag-and-drop payment methods and checkout modules and create conditions that determine when and how they are displayed on Universal Checkout.

checkout builder


Generate a client token to initialize the SDK

The clientToken is a temporary key used to initialize Universal Checkout, and render the checkout options you've configured with the Checkout Builder.

If a payment method or checkout module requires additional information passed in the token request this will be documented in the Connection setup in the Dashboard.

client token

Client token request POST/client-session

123456789101112131415
curl --location --request \ POST 'https://api.sandbox.primer.io/client-token' \ --header 'X-Api-Key: <YOUR_API_KEY>' \  # These fields can be passed in the payment request as well --data '{   "orderId": "<YOUR_ORDER_ID>",    "currencyCode": "GBP",   "amount": 1200,     # a customerId is required to reuse sucessfully authorized payment method data for your customer    # we recommend you always pass this in if you intend to use vaulting    "customerId": "<YOUR_CUSTOMER_ID>"    "metadata": { }, }'
curl
copy

🚨

Data you pass when requesting a clientToken is persisted in the payment request unless explicitly overwritten.

πŸ”“

If your checkout page uses the Content-Security-Policy header, you'll need to add a few things to your whitelist.

Client token response

Check the warnings array for missing data which may be required to display certain payment methods and checkout modules in the Universal Checkout.

123456789101112
{    "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": [        "Apple Pay is missing 'customerDetails.countryCode'"    ]}
JSON
copy

Implement Universal Checkout on front-end

Step 1. Install the SDK

With CocoaPods

The iOS SDK is available with Cocoapods. JustΒ pod initΒ in your project directory and add this to yourΒ Podfile:

123456
target 'MyApp' do  # add this in your Podfile  pod 'PrimerSDK', '~> 1.8.0' # Add this lineend
ruby
copy

With Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into Xcode. Go to File > Swift Packages > Add Package Dependency. In the window that opens, enter https://github.com/primer-io/primer-sdk-ios.git

Step 2. Initialize the SDK

First import the SDK library in a swift file containing theΒ UIViewController that will host the Universal Checkout and its delegate.

1234567891011121314151617181920212223242526272829303132
import PrimerSDKclass MyViewController: UIViewController {    let generalSettings = PrimerSettings(        merchantIdentifier: "general-settings",        customerId: "my-customer",        amount: 100,        currency: .EUR,        countryCode: .fr,        applePayEnabled: false,        klarnaSessionType: .recurringPayment,        klarnaPaymentDescription: nil,        urlScheme: "primer.io://",        urlSchemeIdentifier: "primer",        isFullScreenOnly: false,        hasDisabledSuccessScreen: false,        businessDetails: nil,        directDebitHasNoAmount: false,        orderItems: [],        isInitialLoadingHidden: false    )      override func viewDidLoad() {          super.viewDidLoad()          Primer.shared.delegate = self      }}extension MyViewController: PrimerDelegate {    // ...}
swift
copy

Step 3. Add the client session token callback

When showing the Universal Checkout, the SDK first asks you to retrieve a client session token by calling clientTokenCallback on the delegate.

In the meantime, a loading indicator is displayed.

1234567891011121314151617181920212223
class MyViewController: UIViewController {        // ...}extension MyViewController: PrimerDelegate {      // This function will be called at the beginning of a client session        // You need to retrieve the client session token and pass it in the completion handler.      func clientTokenCallback(_ completion: @escaping (String?, Error?) -> Void) {                // Fetch the client session token from your backend          fetchClientToken() { result in              switch result {                        // Stop the flow if the client session token couldn't been retrieved              case .failure(let error):                                completion(.failure(error))                        // Continue the flow if a client session token has been successfully retrieved              case .success(let clientToken):                                completion(.success(clientToken))              }          }      }}
swift
copy

Step 4. Prepare the Universal Checkout session

Configure the Universal Checkout with data related to the session:

12345678910111213141516171819202122
import PrimerSDKclass MyViewController: UIViewController {    let generalSettings = PrimerSettings(        amount: 100,        currency: .EUR,        countryCode: .fr,        urlScheme: "primer.io://",        urlSchemeIdentifier: "primer",    )      override func viewDidLoad() {          super.viewDidLoad()          Primer.shared.delegate = self        Primer.shared.configure(settings: generalSettings)      }}extension MyViewController: PrimerDelegate {    // ...}
swift
copy

Step 5. Render the Universal Checkout

When ready, display the Universal Checkout.

12345
class MyViewController: UIViewController {        func startUniversalCheckout() {                Primer.shared.showCheckout(self, flow: .default)        }}
swift
copy

checkout

Step 6. Prepare the onTokenizeSuccess callback

When a customer submits payment method data, the credentials are tokenized and you'll receive a payment method token in onTokenizeSuccess

Send the payment method token to your server to create a payment with the Payments API. The checkout stays in a loading state in the meantime.

Return an error in the completion handler to show an error message. Return nil in the completion handler to show a success message.

123456789101112131415161718
extension MyViewController: PrimerDelegate {    //...    // this method will be called when a payment method is tokenized.    func onTokenizeSuccess(_ result: PaymentMethodToken, _ completion: @escaping (Error?) -> Void) {            // Send the payment method token to your server to create a payment            sendPaymentMethodToken(token: result) { error in                    if error == nil {                        // Show an error message                        completion(error)                    } else {                        // Show a success screen                        completion(nil)                    }            }    }}
swift
copy
Β© Primer 2021