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.
Never share your API Key, only your backend should have access to it.
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 metadata associated with the order to the client session, and generate a clientToken, 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.
The X-Api-Version
specifies the API version information. Earlier, this was supposed to be a date. For example, 2021-10-19
. This has changed post API version v2 which was represented by 2021-09-27
date. Starting API version v2.1, the X-Api-Version
needs to provide the API version as v2.1
. Depending upon the API version specified in the client-session request, your client-session will be processed accordingly with requisite features and options that are available for that version.
See API Reference Changelog for details.
Here is how the client session request to the Primer API should look like:
POST/client-session
12345678910111213
# 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: 2021-10-19' \ --header 'Content-Type: application/json' --data '{ "orderId": "<YOUR_ORDER_ID>", "currencyCode": "GBP", "amount": 1200, "customerId": "<YOUR_CUSTOMER_ID>" "order": { "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:
orderId
currencyCode
amount
order.countryCode
Set up the 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;
- 1Select your project, and then navigate to
Package Dependencies
- 2Click on the + button at the bottom-left of the
Packages
section - 3Paste https://github.com/primer-io/primer-sdk-ios.git into the Search Bar
- 4Press Add Package
- 5Let Xcode download the package and set everything up
Step 2. Initialize the SDK
Import the Primer SDK and set its delegate as shown in the following example:
123456789101112131415
import PrimerSDK class MyViewController: UIViewController { override func viewDidLoad() { super.viewDidLoad() // Initialize the SDK with the default settings. Primer.shared.delegate = self }} extension MyViewController: PrimerDelegate { // ...}
Step 3. Add the Client Token Callback
When showing Universal Checkout, the SDK first asks you to retrieve a client session token by calling clientTokenCallback
on the delegate. Create your client session as described above.
In the meantime, a loading indicator is displayed.
123456789
extension MyViewController: PrimerDelegate { func clientTokenCallback(_ completion: @escaping (String?, Error?) -> Void) { // Request a client session token from your backend requestClientSession(completion: { (clientToken, err) in completion(clientToken, err) }) }}
Step 4. Show Universal Checkout
When ready, display Universal Checkout.
1234567
class MyViewController: UIViewController { func startUniversalCheckout() { Primer.shared.showUniversalCheckout(on: self) } }
Step 5. Handle Callbacks for Creating and Resuming Payments
Handling onTokenizeSuccess
callback
When a customer submits payment data, the credentials are tokenized and you'll receive a payment method token in
onTokenizeSuccess(_:resumeHandler:)
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.
Call the
resumeHandler
'shandle(error:)
to show an error message, orhandleSuccess()
to show a success message.In case you receive a
requiredAction
with a newclientToken
, call theresumeHandler
'shandle(newClientToken:)
function.
Handling onResumeSuccess
callback
The SDK will continue and you'll get notified of the resume result in one of the following delegate functions:
onResumeSuccess(_:resumeHandler:)
oronResumeError(_:)
.If the
onResumeSuccess(_:resumeHandler:)
is called, use theresumeToken
to resume your payment.
12345678910111213141516171819202122232425262728293031323334
extension MyViewController: PrimerDelegate { func onTokenizeSuccess(_ paymentMethodToken: PaymentMethodToken, resumeHandler: ResumeHandlerProtocol) { createPayment(with: paymentMethodToken) { (res, err) in if let err = err { resumeHandler.handle(error: err) } else if let res = res { guard let requiredAction = res["requiredAction"] as? [String: Any], let clientToken = requiredAction["clientToken"] as? String else { resumeHandler.handleSuccess() return } resumeHandler.handle(newClientToken: clientToken) } } } func onResumeSuccess(_ resumeToken: String, resumeHandler: ResumeHandlerProtocol) { // Resume the payment with the resumeToken. resumePayment(with: resumeToken) { (res, err) in if let err = err { resumeHandler.handle(error: err) } else if let res = res { resumeHandler.handleSuccess() } } } func onResumeError(_ error: Error) { // Handle the error }}
Step 6: Handle callback for updating the client session
As the customer interacts with the UI, Universal Checkout fires "client session actions" via onClientSessionActions(:resumeHandler:)
.
Forward these to your server to update the client session with the Client Session Actions endpoint.
A new client token will be provided. Pass it back to the SDK using the resumeHandler
's handle(newClientToken:)
to refresh Universal Checkout and continue the flow.
123456789101112131415
extension MyViewController: PrimerDelegate { func onClientSessionActions(_ actions: [ClientSession.Action], resumeHandler: ResumeHandlerProtocol?) { // Send the client session actions to your backend and update // your client session. requestClientSessionWithActions(actions) { (clientToken, err) in if let err = err { resumeHandler?.handle(error: err) } else if let clientToken = clientToken { resumeHandler?.handle(newClientToken: clientToken) } } } }
123
// ClientSession.Actionvar type: Stringvar params: [String: Any]?
Create a Payment
Once you've received a paymentMethodToken
from Universal Checkout, use it to create a payment.
Payment request POST/payments
1234567891011
curl --location --request \ POST 'https://api.sandbox.primer.io/payments' \ --header 'X-Api-Key: <YOUR_API_KEY>' \ --header 'X-Api-Version: 2021-09-27' \ --header 'X-Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>' \ --data '{ "orderId": "<YOUR_ORDER_ID>", "amount": 800, "currencyCode": "GBP", "paymentMethodToken": "<PAYMENT_METHOD_TOKEN>", }'
- orderId
- your unique order ID
- amount
payment amount
example in currency (USD) with minor units:700
for \$7.00
example in currency (JPY) without minor units:100
for ¥100- currencyCode
ISO 4217 three-letter currency code:
USD
for US dollars- paymentMethodToken
paymentMethodToken
obtained from Universal Checkout or the Payment Methods API
Data passed in the payment request overwrites any data passed in the clientToken
.
See more request options in the API Reference.
Payment response
The payment request is synchronous. It will trigger a Workflow and return a payment object containing, among other things, the payment status. In circumstances where the payment flow is asynchronous, you may receive a status of PENDING
.
12345678910111213
// 2XX response { "id": "slklmjh4", "status": "AUTHORIZED", "orderId": "<YOUR_ORDER_ID>", "currencyCode": "GBP", "amount": 800, "paymentMethodToken": "<PAYMENT_METHOD_TOKEN>" // ... additional attributes for the Payment object // ... see API ref}
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.
PAYMENT.STATUS
event.If you are not yet ready to receive webhooks, you can use https://webhook.site to test your implementation.