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-ios
as the repository URL.1.0.0
.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
)
header
and paymentRequest
into an instance of Message<PaymentRequest>
, representing the SaleToPOIRequest to send.
let message = Message(header: header, body: paymentRequest)
message
to JSON.
TerminalAPIKit provides a Coder
class 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:
Data
as follows:
let message = try Coder.decode(Message<PaymentResponse>.self, from: response)
Message<PaymentResponse>
, representing the Terminal API SaleToPOIResponse.header
and body
properties of the message
represent the MessageHeader and PaymentResponse body.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:
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.
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.
Message<PaymentRequest>
.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)
encryptedMessage
to 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.
link |
Stars: 8 |
Last commit: 2 weeks ago |
ISO8601
dates without optional milliseconds.Double
to Decimal
.Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics