Swiftpack.co - Adyen/adyen-terminal-api-ios as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by Adyen.
Adyen/adyen-terminal-api-ios 2.0.0
Adyen Terminal API for iOS
⭐️ 8
🕓 27 weeks ago
iOS macOS
.package(url: "https://github.com/Adyen/adyen-terminal-api-ios.git", from: "2.0.0")

Adyen Terminal API for iOS

TerminalAPIKit for iOS helps with integrating Adyen's Terminal API into your iOS POS app. The kit provides the models to create a Terminal API SaletoPOIRequest, and to decode the received SaletoPOIResponse. For local Terminal API integrations, the kit also helps with protecting local communications.

This package is intended to be used in the following scenarios:

  • when integrating POS Mobile SDK.
  • when integrating client-side with an Adyen terminal using local Terminal API.
  • when integrating server-side with an Adyen terminal using cloud Terminal API.

Install TerminalAPIKit

TerminalAPIKit for iOS is available through Swift Package Manager.

To install the kit:

  1. In your Xcode project, go to File > Swift Packages > Add Package Dependency.
  2. Enter https://github.com/Adyen/adyen-terminal-api-ios as the repository URL.
  3. Specify the version to be at least 1.0.0.

For detailed instructions see Adding Package Dependencies to Your App.

Create Terminal API requests

The next sections describe how to create a request and how to decode the response.

Create a payment request

To create a Terminal API SaleToPOIRequest for making a payment:

  1. Create an instance of MessageHeader, representing the MessageHeader of your Terminal API request.
        let header = MessageHeader(
            protocolVersion: "3.0",
            messageClass: .service,
            messageCategory: .payment,
            messageType: .request,
            serviceIdentifier: "YOUR_SERVICE_IDENTIFIER",
            saleIdentifier: "YOUR_SERVICE_IDENTIFIER",
            poiIdentifier: "YOUR_POI_IDENTIFIER"
  2. Create an instance of PaymentTransaction, representing the body of your Terminal API PaymentRequest
        let saleData = SaleData(
                    transactionIdentifier: "YOUR_TRANSACTION_IDENTIFIER",
                    date: Date()
        let paymentTransaction = PaymentTransaction(
            amounts: Amounts(
                currency: "TRANSACTION_CURRENCY",
                requestedAmount: TRANSACTION_AMOUNT
        let paymentRequest = PaymentRequest(
            saleData: saleData,
            paymentTransaction: paymentTransaction
  3. Combine header and paymentRequest into an instance of Message<PaymentRequest>, representing the SaleToPOIRequest to send.
        let message = Message(header: header, body: paymentRequest)
  4. Encode the message to JSON. TerminalAPIKit provides a Coder class to help with the JSON encoding and decoding.
        let jsonData = try Coder.encode(message)
  5. Send the JSON message to the appropriate endpoint.

Decode the response

You'll receive a Terminal API response in JSON format from the endpoint that you sent your request to.

To handle the response:

  1. Decode from Data as follows:
        let message = try Coder.decode(Message<PaymentResponse>.self, from: response)
  2. After decoding, note the following:

Local Terminal API integration

If your integration uses local communications, you need to protect your integration against man-in-the-middle attacks, eavesdropping, and tampering. To protect communications, you need to:

  • Validate the certificate of the payment terminal, to confirm your POS app is communicating directly with an Adyen-supplied terminal.
  • Encrypt communications. This prevents intruders from reading the messages transmitted between the POS app and the terminal.

To help you with this, TerminalAPIKit provides helper functions to:

Derive the encryption key

To derive the key used for encrypting and decrypting local communications between the terminal and your POS app:

  1. Get the identifier, passphrase, and version of the shared key:
    In the Adyen Customer Area, under Point of sale, go to the terminal settings for your merchant account or store. Select Integrations and under Terminal API go to Encryption key. To see the key identifier, passphrase, and version values, select Decrypted.

  2. Derive the key, making sure to pass the values in string form exactly as they appear in the Customer Area.

    let encryptionKey = try EncryptionKey(
        identifier: "KEY_IDENTIFIER",
        passphrase: "KEY_PASSPHRASE",
        version: KEY_VERSION

Once the key is derived, you are ready to encrypt your local communications.

Encrypt and decrypt communications

  1. Create your request as described above. For example, create a Message<PaymentRequest>.
  2. Encrypt your request.
    let encryptionKey: EncryptionKey = // the key you derived earlier
    let request: Message<PaymentRequest> = // the payment request you created
    let encryptedMessage: Data = try request.encrypt(using: encryptionKey)
  3. Send the encryptedMessage to the terminal.
  4. When you receive the response from the terminal, decrypt the response.
    let key: EncryptionKey = // the key you derived earlier
    let response: Data = // the response you receive from the terminal
    let encryptedMessage: EncryptedMessage = try Coder.decode(EncryptedMessage.self, from: response)
    let decryptedMessage: Message<PaymentResponse> = try decrypt(PaymentResponse.self, using: key)


To use TerminalAPIKit for iOS, you need:

  • iOS 13.0 or later
  • Xcode 13.4 or later
  • Swift 5.6


If you have a feature request, or spotted a bug or a technical problem, create a GitHub issue. For other questions, contact our support team.


We strongly encourage you to join us in contributing to this repository so everyone can benefit from:

  • New features and functionality
  • Resolved bug fixes and issues
  • Any general improvements

Read our contribution guidelines to find out how.


This repository is open source and available under the MIT license. For more information, see the LICENSE file.


Stars: 8
Last commit: 2 weeks ago
Advertisement: IndiePitcher.com - Cold Email Software for Startups

Release Notes

27 weeks ago

Release 2.0.0 brings the following changes:


  • Helper functions for deriving the key used to encrypt the communication when using for local TAPI integration.
  • Documentation regarding local TAPI integration.
  • Support for decoding ISO8601 dates without optional milliseconds.


  • Changed any numeric amount type from Double to Decimal.

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics