Integration guide

Create a VoltCheckout instance

let checkout = VoltCheckout(
    configuration: .sandbox(
        customerId: "your-customer-id",
        tokenProvider: { try await YourAuth.fetchAccessToken() }
    )
)

customerId is your merchant identifier in the merchant portal.

tokenProvider is a closure the SDK calls before each API request. It expects a valid OAuth access token. Include scope=mobile in your token request to limit the token's privileges.

You are responsible for caching and refreshing the token — the SDK does not store it and calls this closure each time it needs one.

For details on authentication to Volt API see .

Create the VoltCheckout instance once and keep it alive for the duration of the session (e.g. in an @StateObject or as a property of your app's root object). Do not recreate it per payment.

Attach the sheet modifier

ContentView()
    .voltCheckoutSheet(using: checkout)

Attach this modifier to a view that is on screen when you start the flow. The SDK uses it to present its full-screen cover. You only need to attach it once — the same instance handles multiple consecutive payments.

Attach .voltCheckoutSheet to a view in the main navigation hierarchy, not inside a modal or alert that might be dismissed before the payment flow ends.

Build a PaymentIntent

PaymentIntent requires three things: an amount, payer information, and a transaction type.

The SDK ships a result builder that lets you compose a PaymentIntent declaratively. All failable initializers are handled automatically — if any component is invalid the whole expression evaluates to nil.

let intent = PaymentIntent {
    Amount(currency: .EUR, minorUnits: 7700)
    Payer(reference: "user@example.com") {
        Payer.Person(firstName: "Jane", lastName: "Doe")
    }
    TransactionType.goods
}
guard let intent else { /* validation failed */ return }

Payer accepts an optional email and phone, and its entity block can contain a Person, an Organization, or both — the correct Entity case is inferred automatically:

// Organisation payer
Payer(reference: "acme-corp") {
    Payer.Organization(name: "Acme Ltd")
}

// Both person and organisation
Payer(reference: "jane@acme.com", email: "jane@acme.com", phone: "+447700900123") {
    Payer.Person(firstName: "Jane", lastName: "Doe")
    Payer.Organization(name: "Acme Ltd")
}

Adding optional payment references works the same way — include PaymentReferences anywhere in the block:

let intent = PaymentIntent {
    Amount(currency: .EUR, minorUnits: 7700)
    Payer(reference: "user@example.com") {
        Payer.Person(firstName: "Jane", lastName: "Doe")
    }
    TransactionType.goods
    PaymentReferences(paymentReference: "ORD20250514", internalReference: "order-9f2c1")
}

If you prefer to build each component separately and handle validation yourself:

Amount is expressed in minor units (cents, pence, etc.). For all Volt-supported currencies the minor unit is 1/100. Amount returns nil for zero.

// EUR 12.50
let amount = Amount(currency: .EUR, minorUnits: 1250)

// GBP 100.00
let amount = Amount(currency: .GBP, minorUnits: 10000)

Payer requires a reference (your unique ID for this customer) and an entity (person, organisation, or both). Reference and Person return nil when the value fails validation.

let ref    = Payer.Reference("user@example.com")!
let person = Payer.Person(firstName: "Jane", lastName: "Doe")!

// Person payer
let payer = Payer(reference: ref, entity: .person(person))

// Organisation payer
let org   = Payer.Organization(name: "Acme Ltd")!
let payer = Payer(reference: ref, entity: .organization(org))

// Both
let payer = Payer(reference: ref, entity: .both(person, org))

// With optional contact info
let payer = Payer(
    reference: ref,
    entity: .person(person),
    email: "user@example.com",
    phone: "+447700900123"   // E.164 format
)

Full PaymentIntent:

let intent = PaymentIntent(
    amount: Amount(currency: .EUR, minorUnits: 7700)!,
    payer: Payer(
        reference: Payer.Reference("user-123")!,
        entity: .person(Payer.Person(firstName: "Jane", lastName: "Doe")!)
    ),
    transactionType: .goods
)

Optional: payment references attach your internal IDs to the payment for reconciliation:

let intent = PaymentIntent(
    amount: amount,
    payer: payer,
    transactionType: .goods,
    references: PaymentReferences(
        paymentReference: "ORD20250514",  // up to 18 alphanumeric characters
        internalReference: "order-9f2c1"  // up to 100 characters
    )
)

PaymentReferences returns nil if either value fails its constraint.

TransactionType describes what the payment is for:

Value	Description
`.bill`	Utility or recurring bill
`.goods`	Physical goods
`.services`	Services
`.other`	Other

Start the payment flow

let result = await checkout.payment(with: intent)

This suspends until the flow ends — either the payment is created, or the user dismisses the sheet. The SDK presents its UI automatically via the .voltCheckoutSheet modifier you attached in step 2.

Handle the result

switch result {
case .paymentCreated(let id, let status, let institution):
    // Payment was created. id is the Volt payment ID.
    // status is the status at the moment the user returned to your app.
    // institution is the bank the user paid from.
    print("Payment \(id) with status \(status) via \(institution.name)")

case nil:
    // User dismissed the sheet before the payment was created.
    // Treat this as a cancellation — no payment exists.
    break

default:
    break
}

status reflects the state at the moment the flow ended. Payments continue processing asynchronously after the user returns to your app. Subscribe to Volt webhooks to receive final status updates. For details on each status value see the .

nil means the user cancelled before payment was created — it is expected behaviour. Only treat .paymentCreated statuses like failed or refusedByBank as payment errors.