The Pay In component is Payabli’s native mobile UI for card and ACH payments in your app. It owns sensitive field state and renders a hosted form, so your app never touches raw card or bank data. See Tap to Pay if you’re looking for Payabli’s contactless payment component instead.

Prerequisites

Before you start, confirm you have:

• Xcode 15 or later and Swift 5.9 or later
• iOS 16.7 or later as your deployment target
• A Payabli sandbox entryPoint with card and ACH enabled
• A Payabli clientId and clientSecret with a permission for each operation you use. See OAuth authentication to provision them.

Installation

Install PayabliSDKPayIn 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: "PayabliSDKPayIn", package: "sdk-ios")

import PayabliSDKCore
import PayabliSDKPayIn

Backend token endpoint

The Pay In 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() }
))

Operations

PayabliPayIn’s operation parameter selects the hosted form’s behavior:

• .storePaymentMethod — Tokenizes a card or ACH account for later use, without charging it. This is the default.
• .capture — Authorizes and captures a card or ACH payment in one step.
• .authorize — Authorizes a card payment without capturing it. The hosted form offers card only in this mode.

PayabliPayIn also exposes direct methods for building your own UI: capture(_:), authorize(_:), captureAuthorizedTransaction(_:), voidTransaction(_:), addCard(_:options:), addBankAccount(_:options:), and addPaymentMethod(_:options:). If you collect card data in your own UI and pass it to these methods, your app handles card numbers and security codes, which brings it into scope for PCI DSS. The hosted form keeps that data out of your app.

Implementation walkthrough

This walkthrough builds a minimal card or ACH capture, from constructing PayabliPayIn through rendering the hosted form:

import SwiftUI
import PayabliSDKCore
import PayabliSDKPayIn
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
}
func startPayabliSession(entryPoint: String) async throws -> PayabliSession {
    try await PayabliSession.initialize(config: PayabliConfig(
        entryPoint: entryPoint,
        environment: .sandbox,
        tokenProvider: { try await fetchPayabliAccessToken() }
    ))
}
@MainActor
final class CheckoutViewModel: ObservableObject {
    let payIn: PayabliPayIn
    init(session: PayabliSession, orderId: String) {
        payIn = PayabliPayIn(
            session: session,
            operation: .capture,
            requestConfiguration: PayabliPayInRequestConfiguration(
                paymentDetails: PayabliPayInPaymentDetails(
                    totalAmount: 1.00,
                    currency: "USD"
                ),
                customerData: PayabliPayInCustomerData(
                    customerNumber: "C-1001",
                    firstName: "Jane",
                    lastName: "Doe"
                ),
                orderDescription: "iOS checkout",
                orderId: orderId,
                source: "ios-sdk"
            )
        )
    }
}
struct CheckoutView: View {
    @StateObject var viewModel: CheckoutViewModel
    var body: some View {
        PayabliPayInView(
            component: viewModel.payIn,
            configuration: PayabliPayInFormConfiguration(),
            onCompleted: { result in
                guard let paymentTransId = result.transaction?.paymentTransId else {
                    // No transaction ID came back. Find the transaction by
                    // orderId before you charge again.
                    reconcileByOrderId()
                    return
                }
                // Store paymentTransId with your order record. Don't log it.
                saveTransactionId(paymentTransId)
            },
            onError: { error in
                if let payInError = error as? PayabliPayInError,
                   case .submissionInterrupted = payInError {
                    // The outcome is unknown, and the payor may have been charged.
                    // Find the transaction by orderId before another attempt.
                    reconcileByOrderId()
                    return
                }
                // Show error.localizedDescription to the payor. Don't log it.
                // It can quote what was submitted.
                showError(error.localizedDescription)
            }
        )
    }
}

Implementation reference

PayabliPayInFormConfiguration controls the hosted form’s fields, labels, and layout for every operation, and its hiddenValues and options carry the data sent when the form stores a payment method. PayabliPayInRequestConfiguration carries the request data for capture and authorize forms. PayabliPayInSheetConfiguration controls the sheet presentation.

PayabliPayInFormConfiguration fields

This hosted form is shared by all three operations. See Operations for what each one does.

PayabliPayInRequestConfiguration fields

Used by hosted capture and authorize forms. Not used for .storePaymentMethod. The direct capture(_:) and authorize(_:) methods take a PayabliPayInRequest instead, which has the same fields plus a required paymentMethod.

PayabliPayInSheetConfiguration fields

Controls the sheet presentation for .payabliPayInSheet(...). The sheet wraps the same hosted form as PayabliPayInView, so configuration, requestConfiguration, and style still apply:

Button("Add Payment Method") {
    isPresented = true
}
.payabliPayInSheet(
    isPresented: $isPresented,
    component: payIn,
    configuration: configuration,
    sheetConfiguration: PayabliPayInSheetConfiguration(
        title: "Add Payment Method",
        dismissButton: .close
    ),
    onCompleted: { result in
        print(result.storedPaymentMethod?.storedMethodId ?? "")
    }
)

Response reference

PayabliPayInResult is a unified wrapper for both token-storage and transaction operations.

Outcomes and errors

Every charge ends in one of three outcomes. Only not charged is safe to retry.

A returned result means something different for each call:

For voidTransaction(_:), transactionFailed means the void was refused. It doesn’t mean the original payment wasn’t charged.

Show error.localizedDescription to the payor, since it names what the service rejected. Don’t log it, because it can quote what was submitted. Log (error as? any PayabliError)?.code instead.

Theming & diagnostics

Style the hosted form to match your app and inspect network activity for debugging:

let diagnostics = PayabliPayInDiagnostics.enabled { entry in
    print(entry.phase, entry.method, entry.statusCode ?? 0)
}

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.