# Dojo Tap to Pay on iPhone Documentation > Guides for integrating Tap to Pay on iPhone — accepting contactless payments directly on iPhone without additional hardware. API quick reference: - **API base URL**: https://api.dojo.tech - **Environment selection**: Sandbox and production both use `https://api.dojo.tech`; the API key determines which environment receives the request - **Authentication**: `Authorization: Basic ` (literal `Basic ` prefix; do not base64-encode `api_key:`) - **Version header**: `version: 2026-02-27` Tap to Pay on iPhone flows still depend on a backend integration for payment intents, webhooks, and related server-side lifecycle calls. Machine-readable specs: - [Dojo API v3](https://docs.dojo.tech/api/v3/bundled.json) - [Tap to Pay on iPhone API](https://docs.dojo.tech/tap-to-pay-on-iphone/bundled.json) For complete integration, also load: - `llms-payment-intents.txt` — payment lifecycle, refunds, and saved-card flows This file contains all documentation content in a single document following the llmstxt.org standard. ## Tap to Pay Dojo offers SDKs for integrating contactless [NFC-enabled](https://support.google.com/wallet/answer/12200245) tap-to-pay functionality on both [iOS](https://www.apple.com/uk/newsroom/2023/07/apple-introduces-tap-to-pay-on-iphone-in-the-uk/) and [Android](https://pay.google.com/about/pay-in-store/) devices. For detailed information on each platform's SDK, including supported cards, countries, compatibility, and integration steps, please refer to the individual SDK pages linked below: - [Tap to Pay on iPhone SDK](https://docs.dojo.tech/tap-to-pay-on-iphone) - [Tap to Pay Android SDK](https://docs.dojo.tech/tap-to-pay-on-android) ## Connect with the community [![](https://docs.dojo.tech/images/dojo-icons/Headset.svg) **Support** Our support team is always happy to help with any questions you have.](https://support.dojo.tech/hc/en-gb) [![](https://docs.dojo.tech/images/dojo-icons/Message.svg) **Stack Overflow** Find answers to practical questions.](https://stackoverflow.com/tags/dojo.tech) --- ## Tap to Pay on iPhone SDK > Accept contactless payments on your iPhone with Dojo's Tap to Pay on iPhone SDK. ## Overview Dojo's Tap to Pay on iPhone SDK lets you integrate payments in your app on the iPhone seamlessly. ## Supported cards and countries | Card supported | 🇬🇧 | |--------------------|---------| | VISA | ✅ | | Mastercard/Maestro | ✅ | | Discover | ❌ | | Diners Club | ❌ | | American Express | ✅ | ## Compatibility The **Tap to Pay on iPhone SDK** is compatible with: - iPhone XS or later with iOS 16.7 or later. ## Step-by-step guide Integrating the SDK is a 2-step process. 1. Activate device 2. Collect payment ![Activate device](https://docs.dojo.tech/images/tapple/activate-terminal.png) ![Collect payment](https://docs.dojo.tech/images/tapple/collect-payment.png) ## Activate device ### Prerequisites To build the SDK, ensure you have the following: - XCode Version **15.3 (15E204a)** or later. ### Setup In order to activate a terminal on a device, you'll need to integrate Dojo Tap to Pay on iPhone SDK into your app. The SDK is available using SPM. 1. Go to **File > Add Packages...** and in **Repository URL**, add `https://github.com/dojo-engineering/dojo-tap-to-pay-on-iphone-sdk`. 2. Enter the latest version number of the SDK, that is, `0.0.11`. 3. In the [target of your app](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app), add **DojoTapToPayOniPhoneSDK**. 4. Click **Add package**. This installs the SDK. 5. Add the following entitlement to your app: [https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone) ```xml com.apple.developer.proximity-reader.payment.acceptance ``` ## Demo Check out our working [demo app](https://github.com/dojo-engineering/dojo-tap-to-pay-on-iphone-sdk/tree/main/SampleApp) to see an integration of the SDK. ### Configure your app > Learn how to configure your app using the Tap to Pay on iPhone SDK. After you have set up the SDK, you need to configure your app using the following steps: 1. Authenticate your backend by [generating an API key](https://docs.dojo.tech/payments/getting-started). 2. Generate a `secret` key using the POST [/secret](https://docs.dojo.tech/api#tag/Tap-to-Pay-on-iPhone/operation/CreateTerminalSecret) endpoint. ```bash curl --request POST \ --url https://staging-api.dojo.dev/integration-test/tap/apple-terminal/secret \ --header 'Authorization: Basic sk_sandbox_EtKXUrMCHU9Y7NCURtDRI9KEn0yqWDgy4JFUOeg0QNGRihcml31fxJURpfbdlx1D' \ --header 'Version: 2023-12-12' ``` 3. Pass this `secret` key when using the `DojoTapToPayOniPhoneSDK` in your app's `.swift` file. For example: `.activateTerminal(secret: )` > **Note:** During activation process, if your `secret` key expires, generate a new `secret` key and try again. 4. Start activation as follows and you'll be notified by the SDK once your device activation is complete. ```swift let dojoSDK = DojoTapToPayOniPhone(env: .staging) // use .staging or .production let secret: String = "" do { let initialStatus = try await dojoSDK.activateTerminal(secret) guard initialStatus != .operational { return } // proceed when the status is operational let terminalStatus = try await dojoSDK.getTerminalActivationStatus(notifyWhenOperational: true, secret: secret) print(terminalStatus) } catch { print(error) } ``` ### Notifications > **Note:** Using `getTerminalActivationStatus(notifyWhenOperational: Bool, secret: String)` with `notifyWhenOperational: true` will subscribe to and receive ongoing status updates until the SDK is operational. ## Take payments In order to start a payment, do the following: 1. Obtain a `secret` key (the same way as you did for activation flow) and a [payment intent](https://docs.dojo.tech/payments/accept-payments/online-payments/checkout-page/step-by-step-guide#step-1-create-a-payment-intent). 2. Check that your AppleID account is linked with the card reader before starting to take a payment. 3. Pass the `secret` key and `paymentIntentId` to the `DojoTapToPayOniPhoneSDK` object calling `.startPayment(paymentIntentId: String, secret: String)`. You'll be notified by the SDK once the transaction is completed. ```bash let dojoSDK: DojoTapToPayOniPhone = DojoTapToPayOniPhone(env: .staging) let secret: String = "" do { if try await dojoSDK.isAccountLinked(secret) == false { try await dojoSDK.linkAccount(secret) } } catch { print(error) } ``` ```bash let dojoSDK: DojoTapToPayOniPhone = DojoTapToPayOniPhone(env: .staging) let secret: String = "" let paymentIntentId: String = "" do { let terminalStatus = try await dojoSDK.getTerminalActivationStatus(secret: secret) if initialStatus != .operational { // restart activation return } let result = try await dojoSDK.startPayment(paymentIntentId: paymentIntentId, secret: secret) print(result.status) } catch { print(error) } ``` ## API key Use the following API key to generate your secret key and payment intent. **API_KEY**: `sk_sandbox_EtKXUrMCHU9Y7NCURtDRI9KEn0yqWDgy4JFUOeg0QNGRihcml31fxJURpfbdlx1D` ## URLs Use the following URLs to get started. ### Staging API URL `https://staging-api.dojo.dev/integration-test/tap/apple-terminal/secret` ### Payment intent URL `https://staging-api.dojo.dev/integration-test/payment-intents` ### Webhooks You can subscribe to webhooks with status updates about your payment intent using [Webhooks](https://docs.dojo.tech/payments/development-resources/webhooks). ## Error handling and SDK responses ### Capturing Errors In the event of failure during activation or taking a payment, the sdk provides several ways to capture and identify the resulted error. 1. Use `AnyDojoSDKError` to recevice the necessary details of the current error, which includers the `underlying error`, the `error code`, the `error description` povided by the SDK. 2. The sdk error code `DojoSDKErrorCode` can be obtained from the `AnyDojoSDKError` object to understand which error occured. > **Note:** We recommend taking the following actions when receiving an error. > - `retry` the current process (i.e retry activation or taking a payment) > - `block access` to tap to pay and report the issue to the relevant stakeholders. An example blocking error would be `PaymentCardReaderError.unsupported` > - `restart` activation by deactivating the current terminal using `dojoSDK.deactiveTerminal()` and starting activation again. ```bash do { let terminalStatus = try await ... print(terminalStatus) } catch { let errorValue = AnyDojoSDKError(error: error) if let code = errorValue.code { // handle the sdk error } else { // retry activation } } ``` ```bash do { let result = try await ... print(result.status) } catch { let errorValue = AnyDojoSDKError(error: error) if let readerError = errorValue.error as? PaymentCardReaderError { // handle the card reader errors } else if let sessionError = errorValue.error as? PaymentCardReaderSession.ReadError { // handle the card reader session errors } else if let code = errorValue.code { // handle the sdk error } else { // retry payment } } ``` The list of all the SDK error codes are illustrated in the diagrams below. ### Errors flow diagrams Click through the flow diagrams below to learn about how payment results and errors are structured. This flow chart describes the process flow for payment transactions, including the various steps involved from initiation to final results. An error result is a declined transaction and is associated with a `status` of 5. The error response counts as a data object. This flow chart describes the structure of the error data object. This error flow diagram includes debugging messages that can be obtained using the error data object `AnyDojoSDKError` which includes the error `code` and `description`. [![](https://docs.dojo.tech/images/dojo-icons/Headset.svg) **Support** Our support team is always happy to help with any questions you have.](https://support.dojo.tech/hc/en-gb) [![](https://docs.dojo.tech/images/dojo-icons/Message.svg) **Stack Overflow** Find answers to practical questions.](https://stackoverflow.com/tags/dojo.tech)