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)")
        }
    }
}

The completion argument is required — pass a closure, or completion: nil if you don't need the pre-flight result. The completion reports whether the payment was accepted into the queue. It can run after asynchronous login and delegate decisions; success does not mean the purchase completed. 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.

Pre-flight errors

OnsidePaymentQueueAddProductError	Meaning
.loginDiscarded	Required login did not complete.
.rejectedAfterLogin	Your queue delegate rejected the payment in shouldContinueAfterLogin.
.notSupportedForExternalLogin	The signed-in external profile cannot buy this subscription or non-consumable.
.applePayRequired	An external profile is buying a consumable, but Apple Pay is unavailable.

These failures happen before enqueueing, so there is no transaction to finish and no transaction update for the rejected attempt. The external-profile checks run before shouldContinueAfterLogin; that delegate cannot override the restrictions.

Purchases with external accounts

External profiles can buy only consumables, using Apple Pay. Saved cards and payment-method switching are unavailable. Configure the full OnsideKit build and Apple Pay before the first purchase.

After a successful external-account purchase, the SDK shows a receipt reminder with options to open/share the receipt or skip. This uses OnsideScreen.externalAccountNotification for presentation customization. Continue processing and finishing transactions through your observer as usual; dismissing that reminder is not the signal to grant content.

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. It is separate from the identifier returned by onsideExternalAccountToken(): setting appAccountToken does not authenticate the user or enable external login.

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