Terminal-2 icon

Add the Adyen POS Mobile SDK for iOS

Update your code to integrate the Adyen POS Mobile SDK in your iOS POS app.

Both Tap to Pay on iPhone and the iOS card reader solution use the same 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.

To add Adyen POS Mobile SDK for iOS version 3.5.0 or later, choose the Add the SDK with token from Customer Area tab below.

This flow only works for Adyen POS Mobile SDK for iOS version 3.5.0 or later. For earlier versions, choose the Add SDK with GitHub access token tab.

  1. In your Customer Area create a basic authentication credential with a password:

    1. Go to Developers > API credentials, and select Create new credential.
    2. Under Payments > Credential type select Web service user and then select Create credential.
    3. Under Server settings > Authentication select the Basic auth tab and the select Generate password.
    4. Select the copy icon and store your basic authentication password to a secure location.
    5. Go to Permissions > Roles > POS and select Allow SDK download for POS developers.

      Contact Support Team if you don't see the Allow SDK download for POS developers role.

    6. Select Save changes.

    You can share the basic authentication password with anybody in your team who needs to get the SDK or create multiple passwords for internal use
    Do not share this password in any publicly accessible code or area where unauthorized users can find it.

  2. Save the basic authentication password in a .netrc file:

    1. Check if you already have a .netrc file in 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 login is the API credential username, for example ws@Company.[YourCompanyAccount], and password is the basic authentication password.

    .netrc content for TEST integration
    Expand view
    Copy link to code block
    Copy code
    Copy code
    machine pos-mobile-test.cdn.adyen.com
    login ws@Company.[YourCompanyAccount]
    password YOUR_BASIC_AUTH_PASSWORD

    When going live, you need to generate a new password and change the value for machine to pos-mobile.cdn.adyen.com.

    1. 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-test and select your preferred Dependency Rule.

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

      • 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

Before going live, you need to make changes to your integration. Depending on what type of token you are using, select the tab below that applies to you.

When going live, you need to pull in the live version of the SDK and change the endpoint as well as your API key:

  • To pull in the live version of the SDK:

    • Generate a new basic authorization password and add it to your .netrc file.
    • In your .netrc file, change the value for machine to pos-mobile.cdn.adyen.com.
    • In your Xcode project or workspace, remove the TEST dependency and add the LIVE dependency using the URL https://github.com/Adyen/adyen-pos-mobile-ios.
    • Add AdyenPOSLIVE to your app target that connects to the Adyen Live environment.
  • 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 -white_check_mark- The unique identifier of your merchant account.
    setupToken -white_check_mark- 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.
    /sessions request
    Expand view
    Copy link to code block
    Copy code
    Copy code
    curl https://checkout-test.adyen.com/checkout/possdk/v68/sessions \
    -H 'content-type: application/json' \
    -H 'x-API-key: ADYEN_API_KEY' \
    -X POST \
    -d '{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "setupToken": "SETUP_TOKEN",
    "store": "YOUR_STORE_ID"
    }'
  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.
    /sessions response
    Expand view
    Copy link to code block
    Copy code
    Copy code
    {
    "id": "APP_SESSION_ID",
    "installationId": "INSTALLATION_ID",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "store": "YOUR_STORE_ID",
    "sdkData": "SDK_DATA_BLOB"
    }

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.

    Copy code
    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.

    Copy code
    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.

    Copy code
    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