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 Payment Flow 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.
• Payabli sandbox credentials. A Payabli sandbox entryPoint with Tap to Pay enabled. Contact your Payabli representative if you don’t have one yet.
• Your app registered on the paypoint allowlist. Your app’s appId (<TEAM_ID>.<BUNDLE_ID>) must be authorized on the entrypoint 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 PayabliTTP.

Installation

Install PayabliSDKTapToPay from the sdk-ios Swift package:

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

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

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

1
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 cors dotenv

1
// server.js
2
import "dotenv/config";
3
import express from "express";
4
import cors from "cors";
5
6
const app = express();
7
app.use(cors(), express.json());
8
9
const PAYABLI_URL = process.env.PAYABLI_URL || "https://api-sandbox.payabli.com/api";
10
const { PAYABLI_CLIENT_ID, PAYABLI_CLIENT_SECRET } = process.env;
11
12
app.post("/payabli/token", async (req, res) => {
13
  const upstream = await fetch(`${PAYABLI_URL}/v2/Token/serverside`, {
14
    method: "POST",
15
    headers: { "Content-Type": "application/json" },
16
    body: JSON.stringify({
17
      clientId: PAYABLI_CLIENT_ID,
18
      clientSecret: PAYABLI_CLIENT_SECRET,
19
    }),
20
  });
21
22
  res.status(upstream.status).json(await upstream.json());
23
});
24
25
app.listen(process.env.PORT || 3000, () =>
26
  console.log("Token server ready"));

$
node server.js

1
let tokenProvider: () async throws -> String = {
2
    try await backend.fetchPayabliAccessToken()
3
}

Implementation walkthrough

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

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
45
    func charge(amount: Decimal) async {
46
        guard ttp.isReady else {
47
            print("Tap to Pay isn't ready yet.")
48
            return
49
        }
50
        do {
51
            let result = try await ttp.charge(
52
                type: .sale,
53
                paymentDetails: PayabliTTPPaymentDetails(amount: amount)
54
            )
55
            print("Transaction captured. ID:", result.paymentTransId)
56
        } catch {
57
            print("Charge failed:", error.localizedDescription)
58
        }
59
    }
60
}

Implementation reference

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

PayabliTTP constructor

charge(...) parameters

The charge(...) method returns a TransactionResult, which has a single field: paymentTransId. Use it to track and reconcile the payment.

Errors

PayabliTTPError covers the Tap to Pay session and charge lifecycle. Catch specific cases before the general case so you can respond appropriately:

1
do {
2
    try await ttp.initialize()
3
    let result = try await ttp.charge(
4
        type: .sale,
5
        paymentDetails: PayabliTTPPaymentDetails(amount: 9.99)
6
    )
7
} catch PayabliTTPError.devicePendingActivation {
8
    // First-time device. Prompt for an activation code.
9
} catch let PayabliTTPError.invalidState(current, attempted) {
10
    // The session isn't in the required state for this call.
11
} catch let PayabliTTPError.attestationFailed(reason) {
12
    // App Attest or Payabli refused to attest the device.
13
} catch let PayabliTTPError.nfcFailed(reason) {
14
    // The card was removed too soon, the reader timed out, or similar. Usually retryable.
15
} catch let PayabliTTPError.initiateFailed(reason) {
16
    // POST /MoneyIn/initiate failed. No transaction was created. Safe to retry.
17
} catch let PayabliTTPError.updateFailed(reason) {
18
    // PATCH /MoneyIn/update/{id} failed after retries. See the note below.
19
} catch PayabliTTPError.tokenExpired {
20
    // Your token provider returned no token. Re-authenticate and try again.
21
}

Capturing paymentTransId

Because updateFailed doesn’t carry paymentTransId, capture it earlier by subscribing to ttp.events() and storing the ID from .chargeInitiated(paymentTransId:), 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
}

Example app

The sdk-ios repository includes PayabliDemo, a SwiftUI example app that exercises PayabliPayInPaymentFlow 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

1
enum Secrets {
2
    static let entryPoint = "your-sandbox-entry-point"
3
    static let appId = "ABCDE12345.com.yourcompany.app"
4
    static let placeholderAccessToken = "placeholder-token"
5
    static let partnerTokenEndpoint = URL(string: "https://your-backend.example.com/payabli/token")!
6
    static let partnerPaymentMethodAccessTokenEndpoint = URL(string: "http://127.0.0.1:8787/payabli/access-token")!
7
    static let paymentMethodDiagnosticsEnabled = false
8
    static let paymentCaptureDiagnosticsEnabled = paymentMethodDiagnosticsEnabled
9
10
    static func fetchAccessToken() async throws -> String {
11
        var request = URLRequest(url: partnerTokenEndpoint)
12
        request.httpMethod = "POST"
13
        let (data, _) = try await URLSession.shared.data(for: request)
14
        struct TokenResponse: Decodable { let accessToken: String?; let access_token: String? }
15
        let response = try JSONDecoder().decode(TokenResponse.self, from: data)
16
        if let token = response.accessToken ?? response.access_token { return token }
17
        throw URLError(.userAuthenticationRequired)
18
    }
19
20
    static func fetchPaymentMethodAccessToken() async throws -> String {
21
        var request = URLRequest(url: partnerPaymentMethodAccessTokenEndpoint)
22
        request.httpMethod = "POST"
23
        let (data, _) = try await URLSession.shared.data(for: request)
24
        struct PaymentMethodTokenResponse: Decodable { let accessToken: String?; let access_token: String? }
25
        let response = try JSONDecoder().decode(PaymentMethodTokenResponse.self, from: data)
26
        if let token = response.accessToken ?? response.access_token { return token }
27
        throw URLError(.userAuthenticationRequired)
28
    }
29
30
    static func fetchPaymentCaptureAccessToken() async throws -> String {
31
        try await fetchPaymentMethodAccessToken()
32
    }
33
}

$
cd LocalTokenServer
$
cp .env.example .env

$
node server.mjs

Related resources

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