Tap to Pay is Payabli’s native mobile component for accepting contactless, card-present payments in your app. It reads the payor’s card, phone, or watch over NFC directly, so your app never touches raw card or bank data. See Tap to Pay overview for how the payment flow works conceptually, or Pay In if you’re looking for Payabli’s card/ACH component instead.

Prerequisites

Before you start, confirm you have:

• A physical device. An iPhone XS or newer running iOS 16.7 or later, in a region where Apple supports Tap to Pay on iPhone. The Simulator can’t take a Tap to Pay payment.
• Payabli sandbox credentials. A Payabli sandbox entryPoint with Tap to Pay enabled. Contact your Payabli representative if you don’t have one yet.
• An OAuth2 client ID and client secret. See Permissions for the required permissions.
• Your app registered as an authorized app. Your app’s App ID (<APP_ID_PREFIX>.<BUNDLE_ID>, where the prefix is your Team ID for most apps) must be one of the paypoint’s authorized apps before device attestation succeeds. See Integration steps.
• Apple’s Tap to Pay entitlement. com.apple.developer.proximity-reader.payment.acceptance. Request it through the Apple Developer Portal.
• Xcode 15 or later and Swift 5.9 or later.

Your app’s provisioning profile also needs com.apple.developer.devicecheck.appattest-environment, set to development for development builds or production for release builds. This value must match the environment you pass to PayabliConfig.

Installation

Install PayabliSDKTapToPay from the sdk-ios Swift package:

 https://github.com/payabli/sdk-ios.git

.package(url: "https://github.com/payabli/sdk-ios.git", branch: "main")

.product(name: "PayabliSDKTapToPay", package: "sdk-ios")

import PayabliSDKCore
import PayabliSDKTapToPay

Backend token endpoint

The Tap to Pay component authenticates every request with a short-lived Payabli access token, obtained through a tokenProvider closure you implement. Your backend holds the Payabli clientId and clientSecret, exchanges them for the access token, and never exposes them to your mobile app.

mkdir payabli-token-proxy
cd payabli-token-proxy
npm init -y
npm pkg set type=module

npm install express dotenv

// server.js
import "dotenv/config";
import express from "express";
const app = express();
const PAYABLI_URL = process.env.PAYABLI_URL ?? "https://api-sandbox.payabli.com/api";
// Replace with your app's own check of the caller's session. This example
// accepts a single development credential from APP_SESSION_TOKEN.
async function authenticateUser(req) {
  const expected = process.env.APP_SESSION_TOKEN;
  if (!expected || req.get("Authorization") !== `Bearer ${expected}`) {
    return null;
  }
  return { id: "dev-user" };
}
// Replace with your app's own rule for who may take payments for this paypoint.
async function mayTakePayments(user) {
  return true;
}
app.post("/payabli/token", async (req, res) => {
  // Never return a token to a caller you haven't authenticated.
  const user = await authenticateUser(req);
  if (!user) {
    return res.status(401).json({ error: "unauthenticated" });
  }
  if (!(await mayTakePayments(user))) {
    return res.status(403).json({ error: "forbidden" });
  }
  let accessToken;
  try {
    const upstream = await fetch(`${PAYABLI_URL}/v2/token/serverside`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        clientId: process.env.PAYABLI_CLIENT_ID,
        clientSecret: process.env.PAYABLI_CLIENT_SECRET,
      }),
      redirect: "error", // Never send the client secret to another origin.
      signal: AbortSignal.timeout(10_000), // Well inside the SDK's 30-second limit.
    });
    const body = await upstream.json();
    accessToken = upstream.ok ? (body.access_token ?? body.accessToken) : undefined;
  } catch {
    // A timeout, a redirect, a network failure, or a response that isn't JSON.
  }
  if (!accessToken) {
    return res.status(502).json({ error: "token exchange failed" });
  }
  res.set("Cache-Control", "no-store").json({ accessToken });
});
app.listen(process.env.PORT ?? 3000, () => console.log("Token server ready"));

PAYABLI_CLIENT_ID=<your sandbox client ID>
PAYABLI_CLIENT_SECRET=<your sandbox client secret>
APP_SESSION_TOKEN=<a long random string your app sends as a bearer token>

node server.js

let session = try await PayabliSession.initialize(config: PayabliConfig(
    entryPoint: "your-entry-point",
    environment: .sandbox,
    tokenProvider: { try await backend.fetchPayabliAccessToken() }
))

Implementation walkthrough

This walkthrough builds a minimal Tap to Pay charge, from constructing PayabliTTP through handling the result:

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)
        }
    }
    func charge(amount: Decimal) async {
        do {
            let result = try await ttp.charge(
                type: .sale,
                paymentDetails: PayabliTTPPaymentDetails(amount: amount),
                customer: PayabliTTPCustomerData(firstName: "Jane", lastName: "Doe")
            )
            // Store result.paymentTransId with your order record. Don't log it.
            saveTransactionId(result.paymentTransId)
        } catch let error as TapToPayError where error.type == .cardDeclined {
            print("Declined. Ask for another card.")
        } catch let error as TapToPayError {
            switch error.capture {
            case .notCharged:
                print("Not charged. Safe to retry.")
            case .unknown:
                // Keep the ID to look up the transaction before charging again.
                // When there's no ID, find the transaction in the Payabli Portal.
                saveTransactionId(error.paymentTransId)
                print("Outcome unknown. Look up the transaction before charging again.")
            case .charged:
                // Keep the ID to reconcile the payment. Don't charge again.
                saveTransactionId(error.paymentTransId)
                print("Charged, but a later step failed. Reconcile the payment.")
            }
        } catch {
            // A CancellationError, which charge throws only before the card is read.
            print("Charge canceled before the card was read.")
        }
    }
}

Implementation reference

PayabliTTP and charge(...) are the two types you construct and call directly. There’s no hosted form for Tap to Pay.

Session and PayabliTTP.create()

PayabliTTP runs on the app’s one PayabliSession. Start the session with PayabliSession.initialize(config:) before you call PayabliTTP.create():

let session = try await PayabliSession.initialize(config: PayabliConfig(
    entryPoint: "your-entry-point",
    environment: .sandbox,
    tokenProvider: { try await fetchPayabliAccessToken() }
))
let ttp = try await PayabliTTP.create()

create() throws a TapToPayError whose type is .sessionNotInitialized when no session has been started. Pay In runs on the same session: pass session to PayabliPayIn. You don’t pass your App ID to the SDK. It reads the App ID from the signed app and sends it when the device attests.

PayabliConfig takes these values:

Start the session once. Calling initialize again with the same entrypoint, environment, and telemetry setting returns the same session. Different values throw a PayabliError whose type is .invalidConfiguration, and the running session stays in place.

Methods and properties

Session states

A charge ends at .ready, at .sessionExpired when the reader session was used up, or at .failed(reason: .deviceSetupRequired) when the device’s registration is gone. The charge’s outcome is what charge(...) returns or throws.

To show progress, switch on sessionState in SwiftUI:

struct TerminalView: View {
    @ObservedObject var ttp: PayabliTTP
    var body: some View {
        switch ttp.sessionState {
        case .ready: Button("Charge") { Task { await charge() } }
        case .charging(.waitingForCard): Text("Hold a card near the top of the iPhone")
        case .charging(.cardRemovalRequested): Text("Remove the card")
        case .initializingReader(let percent): ProgressView(value: Double(percent ?? 0), total: 100)
        default: ProgressView()
        }
    }
}

When the session is .failed, reason is a PayabliTTPFailureReason:

charge(...) parameters

The charge(...) method returns a TransactionResult only when the payment is approved. TransactionResult has a single field, paymentTransId. Store it with your order to track and reconcile the payment.

Errors

Every Tap to Pay failure is a TapToPayError, except a cancellation, which can end the call as a CancellationError. A TapToPayError carries the error catalog entry for its cause:

• category: What to do, such as .credential (call initialize() again) or .outcomeUnknown (find the transaction before you repeat the call).
• type: The cause, for the cases your app handles individually, such as .devicePendingActivation.
• code: The catalog number. Give it to Payabli support with the failure.
• message: Fixed text. detail holds the service’s or the reader’s own words, when there are any.
• retryAfter: How long the service asked you to wait before trying again, when it asked.

You don’t need to handle every type individually. Every TapToPayError also carries capture, which tells you whether the card was charged, and paymentTransId, when there is one:

Handle these types individually, then fall back to capture for everything else:

do {
    let result = try await ttp.charge(
        type: .sale,
        paymentDetails: PayabliTTPPaymentDetails(amount: 9.99),
        customer: PayabliTTPCustomerData(firstName: "Jane", lastName: "Doe")
    )
    // Store result.paymentTransId with your order. Don't log it.
} catch let error as TapToPayError where error.type == .devicePendingActivation {
    // The device needs an activation code.
} catch let error as TapToPayError where error.type == .termsNotAccepted {
    // The merchant hasn't accepted Apple's terms. Present them.
} catch let error as TapToPayError where error.type == .cardDeclined {
    // The card was declined. Ask for another card.
} catch let error as TapToPayError where error.type == .paymentOutcomeUnknown {
    // Look up error.paymentTransId before charging again. Don't retry.
} catch let error as TapToPayError {
    switch error.capture {
    case .notCharged:
        break // Safe to retry.
    case .unknown:
        break // Look up error.paymentTransId before charging again.
    case .charged:
        break // Don't charge again. Reconcile the payment.
    }
} catch {
    // A CancellationError, which charge(...) throws only before the card is read,
    // so nothing was charged.
}

A .tokenProviderFailed type means your token provider failed. Credentials without inboundpayments_create reach .ready, and charge(...) then throws a TapToPayError whose type is .permissionDenied, before the card is read.

If you cancel the task running charge(...) after the transaction has opened, charge(...) throws a TapToPayError with paymentTransId and capture. Handle it like any other error.

Example app

The sdk-ios repository includes PayabliDemo, a SwiftUI example app that exercises PayabliPayIn and PayabliTTP (card/ACH capture and Tap to Pay), alongside a bundled local Node.js token server for testing.

git clone https://github.com/payabli/sdk-ios.git
cd sdk-ios/Example/PayabliDemo

cp App/Configuration/Secrets.swift.sample App/Configuration/Secrets.swift

import Foundation
enum Secrets {
    static let entryPoints: [String: String] = [
        "sandbox": "your-sandbox-entry-point"
    ]
    static let localNetworkHost = "your-mac-hostname.local"
    static var partnerTokenEndpoint: URL { DemoConfiguration.TokenServer.accessTokenURL }
    static var partnerPaymentMethodAccessTokenEndpoint: URL { DemoConfiguration.TokenServer.accessTokenURL }
    static let paymentMethodDiagnosticsEnabled = false
    static let paymentCaptureDiagnosticsEnabled = paymentMethodDiagnosticsEnabled
    static func fetchAccessToken() async throws -> String {
        try await token(from: partnerTokenEndpoint)
    }
    static func fetchPaymentMethodAccessToken() async throws -> String {
        try await token(from: partnerPaymentMethodAccessTokenEndpoint)
    }
    static func fetchPaymentCaptureAccessToken() async throws -> String {
        try await fetchPaymentMethodAccessToken()
    }
    private static func token(from url: URL) async throws -> String {
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        let (data, _) = try await URLSession.shared.data(for: request)
        struct TokenResponse: Decodable {
            let accessToken: String?
            let access_token: String?
        }
        let response = try JSONDecoder().decode(TokenResponse.self, from: data)
        guard let token = response.accessToken ?? response.access_token else {
            throw URLError(.userAuthenticationRequired)
        }
        return token
    }
}

cd LocalTokenServer
cp .env.example .env

node server.mjs

Related resources

See these related resources to help you get the most out of Payabli.