Register your app on the paypoint allowlist

Before your app can complete device attestation, authorize its appId (<TEAM_ID>.<BUNDLE_ID>) on the entrypoint’s allowlist. Do this once per 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. If appId isn’t registered, the SDK’s initialize() method rejects attestation with PayabliTTPError.attestationFailed.

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 PayabliTTPError.devicePendingActivation. See How first-time activation works for the full sequence. Handle it by prompting for a code and calling activateDevice(activationCode:).

1
import SwiftUI
2
import PayabliSDKTapToPay
3
4
func fetchPayabliAccessToken() async throws -> String {
5
    var request = URLRequest(url: URL(string: "https://your-backend.example.com/payabli/token")!)
6
    request.httpMethod = "POST"
7
8
    struct Response: Decodable { let access_token: String }
9
    let (data, _) = try await URLSession.shared.data(for: request)
10
    return try JSONDecoder().decode(Response.self, from: data).access_token
11
}
12
13
@MainActor
14
final class TapToPayViewModel: ObservableObject {
15
    let ttp: PayabliTTP
16
17
    init(entryPoint: String, appId: String) async throws {
18
        ttp = PayabliTTP(
19
            accessToken: try await fetchPayabliAccessToken(),
20
            tokenProvider: {
21
                try await fetchPayabliAccessToken()
22
            },
23
            entryPoint: entryPoint,
24
            appId: appId,
25
            environment: .sandbox
26
        )
27
    }
28
29
    func start() async {
30
        do {
31
            try await ttp.initialize()
32
        } catch PayabliTTPError.devicePendingActivation {
33
            let code = await promptForActivationCode()
34
            do {
35
                try await ttp.activateDevice(activationCode: code)
36
                try await ttp.initialize()
37
            } catch {
38
                print("Activation failed:", error.localizedDescription)
39
            }
40
        } catch {
41
            print("Tap to Pay initialization failed:", error.localizedDescription)
42
        }
43
    }
44
}

Process a payment

Once start() completes without throwing, ttp is in the .ready state and can accept a charge:

1
func charge(amount: Decimal, invoiceNumber: String?) async {
2
    guard ttp.isReady else {
3
        print("Tap to Pay isn't ready yet.")
4
        return
5
    }
6
    do {
7
        let result = try await ttp.charge(
8
            type: .sale,
9
            paymentDetails: PayabliTTPPaymentDetails(amount: amount),
10
            invoice: PayabliTTPInvoiceData(invoiceNumber: invoiceNumber)
11
        )
12
        print("Transaction captured. ID:", result.paymentTransId)
13
        // Store result.paymentTransId alongside your order record.
14
    } catch {
15
        print("Charge failed:", error.localizedDescription)
16
    }
17
}

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.

On success, charge(...) returns a TransactionResult with a single field, paymentTransId. Store it alongside your order record — it’s the identifier you use to find or reconcile the transaction later.

Capturing paymentTransId for reconciliation

If the final /update call fails after retries, the transaction may still be authorized by the processor even though charge(...) throws, and the thrown PayabliTTPError.updateFailed(reason:) doesn’t carry the transaction ID. Subscribe to ttp.events() and store paymentTransId from .chargeInitiated, which fires as soon as /initiate succeeds, before any card is read:

1
for await event in ttp.events() {
2
    switch event {
3
    case .chargeInitiated(let paymentTransId):
4
        pendingPaymentTransId = paymentTransId
5
    case .updateFailed(let paymentTransId, let error):
6
        print("Update failed for", paymentTransId, "-", error, "- reconcile manually.")
7
    default:
8
        break
9
    }
10
}