The Windcave Tap to Pay SDK allows merchants to integrate Tap to Pay on iPhone functionality into their iOS application to accept contactless payments without the requirement for any additional payment terminal or hardware.
In addition to encapsulating the Proximity Reader API the Tap to Pay SDK handles calls to the Windcave REST API ensuring all the complex items of processing are handled.
This guide will help you get started with your Tap to Pay SDK implementation, please refer to the Windcave Tap to Pay SDK for reference with detailed functions and message explanations.
Prior to implementing the Tap to Pay on iPhone SDK merchants must first ensure the meet the below prerequisites:
The Tap to Pay on iPhone SDK supports iOS version 17+ and available in the below region(s):
Merchants must have an active Windcave account and REST API user with Tap to Pay on iPhone functionality enabled.
Recommended installation instructions can be found on the Windcave Tap to Pay SDK for iOS Github page.
While the SDK removes some of the transaction processing complexities, it must still be setup and configured according to Tap to Pay on iPhone requirements. This includes:
For details on these requirements please refer to the Tap to Pay on iPhone developer documentation.
The entry point to the SDK functionality is the class WindcaveTapToPay, it provides all the necessary functionality to perform Tap to Pay transactions.
In order to provide the smoothest possible experience and avoid unnecessary wait times, Apple recommends preparing the iOS card reader as soon as possible when the app starts or returns to the foreground. This ensures everything is ready once the application is ready to start the transaction.
As such below are few recommendations:
It is safe for applications to call prepare() multiple times throughout the application lifetime. The SDK will automatically check the status of the reader and only perform necessary actions if it is needed. The application must also call prepare() after each transaction to reset the internal state of the SDK to prepare it for the next transaction.
The WindcaveTapToPay object encapsulates the ProximityReader API calls as well as handling communications with the Windcave REST API for transaction processing.
Before using the SDK the application developer must make a decision on the below items:
For further information on these items please refer to the WindcaveTapToPay reference guide.
Once the instance of WindcaveTapToPay object has been constructed and the reader is prepared, the application should call the doTransaction method of WindcaveTapToPay:
The below values should also be provided to the doTransaction method from the application developer:
| Value | Description |
|---|---|
| reference | This is the merchant reference for the transaction. The value is recorded with the transaction at Windcave and can be used by merchants to correlate the transaction with a order/payment. |
| txnType | Specifies the type of transaction to be initiated, possible values are:
|
| amount | The amount to be charged for the transaction.
Please note if the application is attempting to trigger a validate transaction, the amount can be set to "0.00". |
| notificationUrl | Optional webhook URL to pass to the Windcave server. If populated the Windcave server will trigger a FPRN request to this URL. |
| customerEmail | Optional customer email address to pass to the Windcave server. If populated the Windcave server will trigger an email receipt to the provided email address provided once transaction is finished. |
| resultCallback | The callback that will be triggered once the transaction processing has finished. |
The SDK maintains its own internal state that can be inspected. It is available as a status property of the WindcaveTapToPay instance. The SDK state is wrapped into CurrentValueSubject object, which allows the application to subscribe to the SDK state change and act accordingly.
The status subject value is provided in a form of an instance of TapToPayStatus which in turn provides:
| Field | Description |
|---|---|
| status | The enumeration indicating the current status. |
| statusText | The optional text information about the status. |
| transactionResponse | An instance of WindcaveResponse for just finished transaction. This value will only be provided when the status is transactionFinished. |
For more information and a full list of possible status values please refer to the SDK reference guide.
Once the transaction is finished, the SDK will be in the transactionFinished state where the application can access the status.transactionResponse and act accordingly. Once the transaction result has been processed by the application it must call prepare() to return the SDK back into the readyToUse state before attempting to start a new transaction. Attempting to call doTransaction while the SDK is still in transactionFinished state will throw a TapToPayError.notReady error.
While this should not occur often, it is possible that the application will be terminated while the transaction is still being processed (whether due to hardware issue, network issue or an application crash).
In this scenario the application must have recovery measures in place, the SDK can assist with this by providing a few methods:
| Method | Description |
|---|---|
| hasOutstandingTransaction | This method returns true if the SDK is aware of the transaction that has not been finished properly. |
| restoreTransaction | This method restarts the Windcave transaction querying to get the transaction result, it will then trigger a callback and return a response once the final response has been received. |
| getOutstandingTransactionId | Returns Windcave Transaction ID of the outstanding transaction, in case the application developer would like to manually handle the recovery. |
| clearOutstandingTransaction | Clears the ID of the outstanding transaction. |
Prior to using Tap to Pay on iPhone functionality merchants must first accept the Tap to Pay on iPhone terms and conditions. There are two ways this can be done: