Register your app as an authorized app

Before your app can complete device attestation, register its App ID as one of the paypoint’s authorized apps. An App ID is your App ID prefix and your bundle ID, joined by a dot. For example, in TEAM123456.com.yourcompany.app, the App ID prefix is TEAM123456 and the bundle ID is com.yourcompany.app. The prefix is your Team ID for most apps, but an older App ID can have a different prefix, which your Apple Developer account shows. Register once per paypoint for each bundle ID you ship, including debug and white-label builds. Your code never passes the App ID: the SDK reads it from the signed app and sends it when the device attests.

In the Payabli Portal at the paypoint level, go to Pay In > Devices, then choose Authorized apps from the dropdown menu. Authorized apps appears only at the paypoint level, not at the organization level. Or register the app from your backend or a provisioning script:

curl -X POST "https://api-sandbox.payabli.com/api/v2/paypoint/{entryPoint}/apps" \
  -H "Content-Type: application/json" \
  -H "requestToken: $API_KEY" \
  -d '{
    "deviceOs": "ios",
    "appId": "TEAM123456.com.yourcompany.app",
    "friendlyName": "Terragon Field Tech iOS App"
  }'

deviceOs must be "ios". friendlyName is optional. This endpoint is idempotent on (entryPoint, deviceOs, appId), so it’s safe to call from an automated provisioning script. The call needs the pos_create permission.

If the App ID isn’t registered, attestation is refused with an HTTP 403. initialize() throws a TapToPayError whose type is .permissionDenied, and sessionState is .failed(reason: .configurationRejected). Register the app, then call initialize() again.

Build the backend token proxy

Tap to Pay uses the same access token model as the rest of the mobile SDK: your backend holds the Payabli clientSecret, exchanges it for a short-lived access token, and never exposes it to the app. See Backend token endpoint in the Tap to Pay component reference for more information.

Install the SDK

Add PayabliSDKTapToPay from the sdk-ios Swift package and link the PayabliSDKTapToPay product. See Installation in the Tap to Pay component reference for more information.

Initialize and handle first-time activation

The interactive walkthrough displays code examples alongside step-by-step explanations.

On a device’s first launch, initialize() throws a TapToPayError whose type is .devicePendingActivation, and sessionState is .pendingActivation(activationId:). See How first-time activation works for the full sequence. Handle it by prompting for a code and calling activateDevice(activationCode:). Activation is per device and per paypoint, not per user. A reinstall, a restore to a new device, or a new device needs a new code.

The code is six digits and can start with zero, so keep it as a string. It’s valid for 30 minutes, and asking again before it expires returns the same code, so it’s safe to ask again if the operator needs it resent. Issue it in one of these ways:

• From the Payabli Portal: At the paypoint level, go to Pay In > Devices, then choose Generate activation code from the dropdown menu. You can also generate a code at the organization level from Pay In > Devices > All devices, where you select the paypoint first.
• From your backend: Read the device’s activation ID from .pendingActivation(activationId:) and send it to your backend. Your backend calls Generate Tap to Pay activation code with the paypoint’s entrypoint and the activation ID in the request’s deviceId field, and returns the code to the app. Anyone who can call this route on your backend can set up a device to take payments for your paypoint, so authenticate the caller the same way your token endpoint does.

if case let .pendingActivation(activationId) = ttp.sessionState {
    // Send activationId to your backend.
}

If the merchant hasn’t accepted Apple’s Tap to Pay terms, initialize() stops at .pendingTerms and throws a TapToPayError whose type is .termsNotAccepted. A merchant accepts the terms once per merchant, not once per device. After they accept on one device, other devices for the same merchant don’t ask again. Call presentTerms() from a screen where someone with the authority to accept is present, confirm with areTermsAccepted(), then call initialize() again. See Apple’s Tap to Pay on iPhone Human Interface Guidelines for when to show the terms and to whom, and linkAccount(using:) for how acceptance works.

import SwiftUI
import PayabliSDKCore
import PayabliSDKTapToPay
func fetchPayabliAccessToken() async throws -> String {
    var request = URLRequest(url: URL(string: "https://your-backend.example.com/payabli/token")!)
    request.httpMethod = "POST"
    // Your app's own session credential, which your token endpoint verifies.
    request.setValue("Bearer \(yourSessionToken)", forHTTPHeaderField: "Authorization")
    struct Response: Decodable { let accessToken: String }
    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONDecoder().decode(Response.self, from: data).accessToken
}
@MainActor
final class TapToPayViewModel: ObservableObject {
    let ttp: PayabliTTP
    init(ttp: PayabliTTP) {
        self.ttp = ttp
    }
    static func make(entryPoint: String) async throws -> TapToPayViewModel {
        _ = try await PayabliSession.initialize(config: PayabliConfig(
            entryPoint: entryPoint,
            environment: .sandbox,
            tokenProvider: { try await fetchPayabliAccessToken() }
        ))
        return TapToPayViewModel(ttp: try await PayabliTTP.create())
    }
    func start() async {
        do {
            try await ttp.initialize()
        } catch let error as TapToPayError where error.type == .devicePendingActivation {
            let code = await promptForActivationCode()
            do {
                try await ttp.activateDevice(activationCode: code)
            } catch {
                print("Activation failed:", error.localizedDescription)
                return
            }
            await start()
        } catch let error as TapToPayError where error.type == .termsNotAccepted {
            do {
                try await ttp.presentTerms()
                guard try await ttp.areTermsAccepted() else { return }
            } catch {
                print("Couldn't confirm Apple's terms:", error.localizedDescription)
                return
            }
            await start()
        } catch {
            print("Tap to Pay initialization failed:", error.localizedDescription)
        }
    }
}

Process a payment

start() handles its own errors, so finishing it doesn’t mean setup succeeded. Offer a charge only when ttp.isReady is true. charge(...) also accepts a session in the .sessionExpired state, and refreshes it before it reads the card:

func charge(amount: Decimal, invoiceNumber: String?) async {
    do {
        let result = try await ttp.charge(
            type: .sale,
            paymentDetails: PayabliTTPPaymentDetails(amount: amount),
            customer: PayabliTTPCustomerData(firstName: "Jane", lastName: "Doe"),
            invoice: PayabliTTPInvoiceData(invoiceNumber: invoiceNumber)
        )
        // Store result.paymentTransId with your order record. Don't log it.
        saveTransactionId(result.paymentTransId)
    } catch let error as TapToPayError {
        handleChargeError(error)
    } catch {
        // A CancellationError, which charge(...) throws only before the card is read.
        showError(error.localizedDescription)
    }
}

charge(type:paymentDetails:customer:invoice:orderDescription:) does three things in order: it calls POST /MoneyIn/initiate (which creates the transaction’s paymentTransId), prompts the NFC card read, then calls PATCH /MoneyIn/update/{paymentTransId}. See Implementation reference for the full parameter list.

charge(...) returns a TransactionResult only when the payment is approved. It has a single field, paymentTransId. Store it alongside your order record, because it’s the identifier you use to find or reconcile the transaction later.

Handle the outcome

When charge(...) throws a TapToPayError, check its capture value to decide what to do next:

• .notCharged: The card wasn’t charged. You can retry.
• .unknown: The outcome isn’t known. Look up error.paymentTransId with Get transaction details before you charge again. When there’s no ID, find the transaction in the Payabli Portal.
• .charged: The card was charged, but a later step failed. Don’t charge again. Reconcile the payment.

These error types need their own handling: .cardDeclined (ask for another card), .paymentOutcomeUnknown (look up the transaction, and don’t retry), .devicePendingActivation (enter an activation code), and .termsNotAccepted (present Apple’s terms). See Errors for the full list.