Add the Adyen POS Mobile SDK for iOS

To enable accepting payments through the Adyen POS Mobile SDK, take the following steps:

1. Add the Adyen POS Mobile SDK for iOS to the Xcode project that contains your iOS POS app.
2. Add code to establish a session.
3. Add code to enable transactions through the Adyen POS Mobile SDK.

Add the SDK using Swift Package Manager

You can add the Adyen POS Mobile SDK for iOS to your POS app using a Swift Package Manager remote package. We send you a secret access token that allows you to download the SDK from a remote server. After downloading the SDK, you add it as a package dependency to your Xcode project.

1. Reach out to your Adyen contact to get your access token.

   Do not share this token in any publicly accessible code or area where unauthorized users can find it.

2. Save your access token in a .netrc file:

   1. Check if you already have a .netrc file in your your home directory. If you do not have it, create a plain text file with that name in your home directory (~/.netrc).

   2. Add the following content to your .netrc file, where password is the access token you received from your Adyen contact.

      machine api.github.com
      login adyen
      password YOUR_SECRET_ACCESS_TOKEN

   3. Make sure that the .netrc file has the following file system permission: 0600.

3. Add the POS Mobile SDK as a package dependency to your Xcode project:

   1. In your Xcode project or workspace, go to File > Add Package Dependencies.

   2. Enter the URL https://github.com/Adyen/adyen-pos-mobile-ios and select your preferred Dependency Rule.

   3. Select Add Package. Once the SDK is loaded:

      • add AdyenPOSLIVE to your app target that connects to the Adyen Live environment.
      • add AdyenPOSTEST to your app target that connects to the Adyen Test environment.

        It is not possible to use TEST and LIVE environments from a single app target. Each app target must connect to a specific environment.

   4. Select Add Package.

4. In your code, add import AdyenPOS, or for Objective-C compatibility add #import "ADYPOS/ADYPOS.h".

Establish a session

The Adyen POS Mobile SDK has to communicate in a secure way with the Adyen payments platform. To enable this, you must integrate a server-to-server POST /checkout/possdk/v68/sessions request to create a session. Your POS app needs to call your backend to trigger this request and get the session data.

The SDK uses the session data from the response to authenticate with our payments platform. Because the session expires after some time, the SDK checks regularly if it needs to establish a new session.

API credential

To authenticate your /checkout/possdk/v68/sessions requests, you need an API credential. This API credential must have an API key and a client key, and the following role:

• Checkout webservice role. This role is assigned by default when the API key is created.

Going live

When going live, you need to change the endpoint as well as your API key:

• To access the live endpoint, generate an API key from your live Customer Area.

• The live endpoint URL contains a prefix which is unique to your company account, for example:

  https://{PREFIX}-checkout-live.adyenpayments.com/checkout/possdk/v68/sessions

  Get your {PREFIX} from your live Customer Area under Developers > API URLs > Prefix.

Make a /sessions request

To let your backend establish a session:

1. From your backend, make a POST /checkout/possdk/v68/sessions request, specifying:

   Parameter	Required	Description
   merchantAccount		The unique identifier of your merchant account.
   setupToken		The setup token provided by the Adyen POS Mobile SDK through the PaymentServiceDelegate.register(with:) callback of PaymentServiceDelegate.
   store		The unique identifier of the store that you want to process payments for.

2. When you receive the response:

   • Check that you get a 201 Created HTTP status code.
   • Return the sdkData to your POS app.
   • If you create the Terminal API request on your backend, save the installationId and use this as the POIID in the MessageHeader of the payment request.

Enable transactions

To enable the payments functionality of the Adyen POS Mobile SDK, add code to your iOS POS app:

1. Implement the PaymentServiceDelegate protocol. Below is an example of how you could do that.

   struct SessionsResponse: Decodable {
       let sdkData: String
   }
   
   class MyPaymentServiceDelegate: PaymentServiceDelegate {
       internal func register(
           with setupToken: String
       ) async throws -> String {
           /// Make a call to your backend to trigger a `/checkout/possdk/v68/sessions` request, specifying the `setupToken` provided by the SDK.
           let request = URLRequest(url: URL(string: "{ADDRESS_OF_YOUR_BACKEND_API}")!)
           let (data, _) = try await URLSession.shared.data(for: request)
           let response = try JSONDecoder().decode(SessionsResponse.self, from: data)
           return response.sdkData
       }
   }

   The actual structure of the SessionsResponse depends on your backend implementation.

2. Create an instance of PaymentService with the PaymentService(delegate:) initializer and pass the delegate object. Make sure that you keep a strong reference to the payment service instance so that it is retained for the duration of the transaction. Also make sure your delegate is strongly referenced, because the PaymentService keeps a weak reference to the delegate.

   let paymentService = PaymentService(delegate: myPaymentServiceDelegate)

3. Make sure that the PaymentServiceDelegate can provide new sdkData at any time.
   If there is no session or the session has expired, the delegate is called using the PaymentServiceDelegate.register(with:) callback. Using the provided setupToken you need to get the sdkData through your backend and return it. For instructions, see Establish a session.

4. Optional. Verify that the callback works, by calling the warm-up function.

   The warm-up function checks for a session and any configuration changes, and prepares the proximity reader on the iPhone.

   try await paymentService.warmUp()

Objective-C compatibility

If your POS app requires the Adyen POS Mobile SDK for iOS to be compatible with Objective-C, link:

• the ADYPOSTEST package product to your app target instead of AdyenPOSTEST.
• the ADYPOSLIVE package product to your app target instead of AdyenPOSLIVE.

  It is not possible to use TEST and LIVE environments from a single app target. Each app target must connect to a specific environment.

The integration process is the same. The only difference is that the public symbols are prefixed with ADY. For example, PaymentService is called ADYPaymentService.

Next steps