Contents

Adyen/adyen-terminal-api-ios

Adyen Terminal API for iOS

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.

``swift let header = MessageHeader( protocolVersion: "3.0", messageClass: .service, messageCategory: .payment, messageType: .request, serviceIdentifier: "YOUR_SERVICE_IDENTIFIER", saleIdentifier: "YOUR_SERVICE_IDENTIFIER", poiIdentifier: "YOUR_POI_IDENTIFIER" ) ``

  1. Create an instance of PaymentTransaction, representing the body of your Terminal API PaymentRequest

```swift let saleData = SaleData( saleTransactionIdentifier: TransactionIdentifier( transactionIdentifier: "YOUR_TRANSACTION_IDENTIFIER", date: Date() ) )

let paymentTransaction = PaymentTransaction( amounts: Amounts( currency: "TRANSACTION_CURRENCY", requestedAmount: TRANSACTION_AMOUNT ) )

let paymentRequest = PaymentRequest( saleData: saleData, paymentTransaction: paymentTransaction ) ```

  1. Combine header and paymentRequest into an instance of Message<PaymentRequest>, representing the SaleToPOIRequest to send.

``swift let message = Message(header: header, body: paymentRequest) ``

  1. Encode the message to JSON.

TerminalAPIKit provides a Coder class to help with the JSON encoding and decoding. ``swift let jsonData = try Coder.encode(message) ``

  1. 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:

``swift let message = try Coder.decode(Message<PaymentResponse>.self, from: response) ``

  1. After decoding, note the following:

- The message object has a type of Message<PaymentResponse>, representing the Terminal API SaleToPOIResponse. - The header and body properties of the message represent the MessageHeader and PaymentResponse body.

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: <br>

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.

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

``swift 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.

``swift 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) ``

  1. Send the encryptedMessage to the terminal.
  2. When you receive the response from the terminal, decrypt the response.

``swift 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) ``

Requirements

To use TerminalAPIKit for iOS, you need:

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

Support

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.

Contributing

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.

License

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

Package Metadata

Repository: Adyen/adyen-terminal-api-ios

Homepage: https://docs.adyen.com/point-of-sale/terminal-api-fundamentals

Stars: 16

Forks: 10

Open issues: 0

Default branch: develop

Primary language: swift

License: MIT

README: README.md