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:
TerminalAPIKit for iOS is available through Swift Package Manager.
To install the kit:
https://github.com/Adyen/adyen-terminal-api-iosas the repository URL.
For detailed instructions see Adding Package Dependencies to Your App.
The next sections describe how to create a request and how to decode the response.
To create a Terminal API
SaleToPOIRequest for making a payment:
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" )
PaymentTransaction, representing the body of your Terminal API PaymentRequest
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 )
paymentRequestinto an instance of
Message<PaymentRequest>, representing the SaleToPOIRequest to send.
let message = Message(header: header, body: paymentRequest)
messageto JSON. TerminalAPIKit provides a
Coderclass to help with the JSON encoding and decoding.
let jsonData = try Coder.encode(message)
You'll receive a Terminal API response in JSON format from the endpoint that you sent your request to.
To handle the response:
let message = try Coder.decode(Message<PaymentResponse>.self, from: response)
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:
To help you with this, TerminalAPIKit provides helper functions to:
To derive the key used for encrypting and decrypting local communications between the terminal and your POS app:
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.
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.
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)
encryptedMessageto the terminal.
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:
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:
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.
|Last commit: 2 weeks ago|
ISO8601dates without optional milliseconds.