Making a Purchase

Start a purchase by adding a payment to the queue, process the resulting transaction, and finish it.

A purchase is initiated by adding a payment to the payment queue. The SDK presents whatever UI is needed (login, payment sheet), and the result is delivered to your transaction observer.

Make sure you have registered a transaction observer first — the queue does nothing until one is registered. See The Payment Queue & Transactions.

Start the purchase

Create an OnsidePayment from an OnsideProduct and add it to the queue:

@MainActor func add(
    _ payment: OnsidePayment,
    completion: ((Result<Void, OnsidePaymentQueueAddProductError>) -> Void)?
)

func buy(_ product: OnsideProduct) {
    let payment = OnsidePayment(product: product)
    Onside.defaultPaymentQueue().add(payment) { result in
        if case .failure(let error) = result {
            // Pre-flight failure, e.g. the user dismissed the login screen.
            print("Couldn't start the purchase: \(error)")   // .loginDiscarded
        }
    }
}

The completion argument is required — pass a closure, or completion: nil if you don't need the pre-flight result. The completion reports only the synchronous pre-flight outcome (OnsidePaymentQueueAddProductError.loginDiscarded). The actual transaction updates arrive through your observer.

If the user is not logged in, OnsideKit presents the login flow automatically and resumes the purchase afterwards. See Authentication & User Account.

Associating a purchase with your account system

OnsidePayment.appAccountToken lets you tie a purchase to your own user/account. Its only initializer is init(product:), so set the token by mutating the value:

var payment = OnsidePayment(product: product)
payment.appAccountToken = currentUser.id   // your opaque account token
Onside.defaultPaymentQueue().add(payment, completion: nil)

The token is carried with the transaction and echoed back on transaction.payment.appAccountToken.

Process the transaction

Updates are delivered to your observer's onsidePaymentQueue(_:updatedTransactions:). Inspect each transaction's state, unlock content, and finish it:

func onsidePaymentQueue(
    _ queue: OnsidePaymentQueue,
    updatedTransactions: [OnsidePaymentTransaction]
) {
    for transaction in updatedTransactions {
        switch transaction.transactionState {
        case .purchased:
            unlockContent(for: transaction.payment.product.productIdentifier)
            queue.finishTransaction(transaction)

        case .restored:
            unlockContent(for: transaction.payment.product.productIdentifier)
            queue.finishTransaction(transaction)

        case .failed:
            // transaction.error is an OnsidePaymentTransactionError (e.g. .cancelled).
            print("Transaction failed: \(String(describing: transaction.error))")
            queue.finishTransaction(transaction)

        case .purchasing:
            break   // in progress — show a spinner if you like

        @unknown default:
            break
        }
    }
}

private func unlockContent(for productIdentifier: String) {
    UserDefaults.standard.set(true, forKey: productIdentifier)
    // Update your UI and grant access.
}

You must finish every transaction that reaches .purchased, .restored, or .failed. Otherwise OnsideKit re-delivers it on the next launch. See The Payment Queue & Transactions.

transaction.error is an OnsidePaymentTransactionError. On a .failed transaction, .cancelled means the user backed out rather than a hard error; .presentationFailed means OnsideKit couldn't present the purchase UI (no active window scene was available) so the purchase never started — retry once the app is in the foreground.

Next

• Restoring Purchases — let users get their purchases back

• Handling Storefront & Price Changes — confirm or cancel a purchase when the region/price changes

• Purchase Validation — verify purchases on your backend