Skip to main content

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

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, 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
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.developer.proximity-reader.payment.acceptance</key>
	<true/>
</dict>
</plist>

Demo​

Check out our working demo app 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.
  2. Generate a secret key using the POST /secret endpoint.
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'

  1. Pass this secret key when using the DojoTapToPayOniPhoneSDK in your app's .swift file. For example: .activateTerminal(secret: <your_secret_key>)

    note

    During activation process, if your secret key expires, generate a new secret key and try again.

  2. Start activation as follows and you'll be notified by the SDK once your device activation is complete.

let dojoSDK = DojoTapToPayOniPhone(env: .staging) // use .staging or .production
let secret: String = "<secret>"

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

mobile-sdk/ios/tap-to-pay/swift/link-account.swift
loading...

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.

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.
mobile-sdk/ios/tap-to-pay/swift/activation-error.swift
loading...

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.

Payment results

Support Our support team is always happy to help with any questions you have.

Stack Overflow Find answers to practical questions.

Last updated on