---
name: coinme-vault-ios
description: "Add card capture to an iOS app with the Coinme Vault SDK: add the package, configure the vault, build and bind the secure fields, observe form state, and submit the payment method to Coinme with the transient auth token. Use when asked to collect card details, add a payment method or integrate Coinme's vault in an iOS or Swift app."
metadata:
  surface: "caas"
  package: "CoinmeVault · Swift"
  version: "1.0.1"
---

# Coinme Vault SDK on iOS

## When to use this skill

The human wants an iOS app to collect a customer's card details and add them as a payment method at Coinme without the card data touching the app's code or servers. It is not for the Coinme Widget, which handles payment inside its own frame.

## Which integration this is

This skill is for the **Coinme-as-a-Service (CaaS) integration**: the partner keeps its own users and its own screens, and Coinme performs regulated services for them (onboarding and KYC, card vaulting, risk signals, transactions). The users are the partner's customers, not Coinme users. There is no Coinme Widget here, so no `rampId`, `partnerKey`, widget URL or embed allowlist. If the human wants to embed the Coinme Widget instead, this is the wrong skill: read [Two ways to build on Coinme](https://platformdocs.coinme.com/agents/surfaces.md) and pick a Widget skill.

## What you will produce

An iOS app with the vault's secure fields in the payment form, validation wired to the submit control, and a submit that sends the payment method to Coinme with a fresh transient auth token in the Authorization header, a Risk SDK session id fetched right before the submit, and the same device fingerprint the Risk SDK gets.

## Before you start: ask the human for these

The documentation does not contain them and you cannot derive them. Stop and ask, then continue. Never write a real value into a tracked file; keep each where the row says.

| Value | What it is | Where it goes |
| --- | --- | --- |
| `registry token` | Read-only token for the private registry that serves the Coinme SDKs. The install steps below read it from an environment variable they name; set that variable. | An environment variable or a gitignored registry config read at install time; CI reads it from a secret. Never in a committed file. |
| `API client ID and client secret` | The credentials the human's backend exchanges at `POST /services/authorize` for a partner access token, which mints the Transient Auth Token. The client ID is not the partner ID, and not the Risk SDK's `clientId`. | The backend's secret store or environment variables; never in client code or a committed file. |
| `production base URL` | The base URL for `/services/authorize` and `/services/browserAuth` in production; sandbox is `https://caas-staging.coinme.com`. Coinme provides it at onboarding. | Backend configuration, one value per environment. |
| `customerId, paymentProviderId and the Risk SDK webSessionId` | The customer the payment method belongs to, the payment provider, and the Risk SDK session the submit is tied to. | Values from the human's app state at submit time; the Risk SDK must already be integrated to supply the session id, fetched right before the submit. On the web and React Native the Coinme SDKs share the device fingerprint; on iOS and Android the app passes the same value it gives the Risk SDK. |

## Rules for this skill

- Follow the steps in order and keep the code as written; change only identifiers the human gives you and the places marked as yours.
- Do not invent configuration fields, event names or API methods. What exists is what this skill shows plus what the installed package declares in its type definitions; check those before adding anything.
- Samples show the environment (such as `'sandbox'`, `'test'` or a staging base URL) as a literal so each stays self-contained. In the project, read it from the runtime configuration the human's build uses (for Vite, `VITE_*` variables in a gitignored `.env.local` with a committed `.env.example`), with a value per environment.
- This integration has no `rampId`, `partnerKey`, widget URL or embed allowlist. Do not ask for them or add them; they belong to the Widget skills.
- The Transient Auth Token is minted only in the human's backend, never in the browser or the app: write that backend route as the backend step below shows, reading the API client ID, client secret and base URL from the server's configuration. Never send the partner access token, the client ID or the client secret to the client.
- Never pass the partner access token to the SDK, not in sandbox, not in a prototype and not as a fallback when minting fails; the `Authorization` header carries only the Transient Auth Token from `POST /services/browserAuth`.
- When a step needs a value you do not have, ask; do not substitute a placeholder that could ship.
- Read the linked pages when a step is unclear; they are the source this skill was generated from.

## Read first

Every payment-method submit carries a Transient Auth Token as `Authorization: Bearer <token>`, minted by the human's backend for the customer (the backend step below). The client fetches one when the add-card screen opens, keeps it in memory, and on a `server` error with status 401 or 403 fetches a fresh one and retries once. Never store it on the device or in the browser, and never put the backend's credentials in the client. Never pass the partner access token to the SDK; the `Authorization` header carries only the Transient Auth Token from `POST /services/browserAuth`.

The submit also needs a Risk SDK session id, fetched right before the submit because a session tag lives 30 minutes. Pass `X-Device-Fingerprint` with the same value the Risk SDK gets. If the Risk SDK is not integrated yet, say so and offer the Risk skill first.

## Backend: mint the Transient Auth Token

Before the client can submit a card, the human's backend needs a route that returns `mintTransientAuthToken(customerId)` for the signed-in customer: a Transient Auth Token with the default `payment-methods` scope, bound to the customer the card will belong to. The client calls it when the add-card screen opens.

#### Get a partner access token

Call this from your backend only. It authenticates with HTTP Basic: your API client ID and client secret, joined by a colon and base64-encoded.

```bash
curl -X POST "https://caas-staging.coinme.com/services/authorize" \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)"
```

```json
{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": "1800"
}
```

The lifetime differs by environment: 30 minutes (`1800`) in sandbox and 60 minutes (`3600`) in production. Read `expires_in` (seconds, sent as a string) rather than hard-coding it, keep the token in your backend and reuse it until shortly before it expires.

> **Never send the partner access token to a browser or an app.**
>
> It authorizes every CaaS endpoint on your behalf. Only the Transient Auth Token from the next step goes to the client.

#### Mint the Transient Auth Token

Also from your backend only, authenticated with the partner access token from step 1.

```bash
curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}" \
  -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}"
```

| Parameter | In | Required | Notes |
| --- | --- | --- | --- |
| `Authorization` | header | yes | `Bearer <partner access token>`. |
| `customerId` | query | yes | For card capture, the Coinme customer the card will belong to. For onboarding, your identifier for the customer's sign-up session. For phone verification, the Coinme `customerId` onboarding returned, read from your backend's own record, never from the client. For attestations, the Coinme `customerId` of the onboarded customer. The token is bound to this value. |
| `scope` | query | no | `payment-methods` (the default) for the Vault SDK's payment-method submit, `onboarding` for the Onboarding SDK's onboarding submit and phone verification calls (sandbox only for now: Coinme's production environment does not issue tokens with this scope yet), or `attestations` for the Compliance SDK's attestation store, which is not available in the beta at this time. |

For onboarding, pass `scope=onboarding` and the sign-up session's identifier:

```bash
curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${SIGNUP_SESSION_ID}&scope=onboarding" \
  -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}"
```

For phone verification, pass `scope=onboarding` and the `customerId` onboarding returned. Mint a fresh one for each verification call (sending the code, checking it), since a customer waiting for the text can easily pass the 10 minutes:

```bash
curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}&scope=onboarding" \
  -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}"
```

For the Compliance SDK's attestations, pass `scope=attestations` and the onboarded customer's `customerId`. Attestations are not available in the Compliance SDK beta at this time, and Coinme does not issue tokens with this scope:

```bash
curl -X POST "https://caas-staging.coinme.com/services/browserAuth?customerId=${CUSTOMER_ID}&scope=attestations" \
  -H "Authorization: Bearer ${PARTNER_ACCESS_TOKEN}"
```

```json
{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": "600"
}
```

Mint a fresh token each time the customer reaches the add-card, onboarding or consent screen. Tokens last 10 minutes and are cheap to mint; never cache one or reuse it across sessions or customers.

> **Check the body, not just the status.**
>
> A mint that reaches the service but fails validation returns HTTP `200` with an error envelope in the body (for example `{"status":400}`) and no `access_token`. Treat any response without an `access_token` as a failure.

#### In your backend

The two calls as a Node.js module. The route that hands the token to your page or app calls `mintTransientAuthToken`: for card capture, for a signed-in customer only; for onboarding, for the customer's sign-up session, because the customer is not signed in yet; for phone verification, for the `customerId` your backend saved against that customer's record when onboarding succeeded, read from your own record and never from the request; for attestations, for the signed-in customer only.

```typescript
const BASE_URL = process.env.COINME_BASE_URL!; // https://caas-staging.coinme.com in sandbox

let partnerToken: { value: string; expiresAt: number } | undefined;

const getPartnerAccessToken = async (): Promise<string> => {
  if (partnerToken && partnerToken.expiresAt > Date.now() + 60_000) {
    return partnerToken.value;
  }
  const credentials = Buffer.from(
    `${process.env.COINME_CLIENT_ID}:${process.env.COINME_CLIENT_SECRET}`
  ).toString('base64');
  const response = await fetch(`${BASE_URL}/services/authorize`, {
    method: 'POST',
    headers: { Authorization: `Basic ${credentials}` },
  });
  const body = await response.json();
  if (!response.ok || !body.access_token) {
    throw new Error(`Coinme authorize failed (${response.status})`);
  }
  partnerToken = {
    value: body.access_token,
    expiresAt: Date.now() + Number(body.expires_in) * 1000,
  };
  return partnerToken.value;
};

export const mintTransientAuthToken = async (
  customerId: string, // or, for onboarding, the sign-up session's identifier
  scope: 'payment-methods' | 'onboarding' | 'attestations' = 'payment-methods'
): Promise<{ token: string; expiresIn: number }> => {
  const url = new URL(`${BASE_URL}/services/browserAuth`);
  url.searchParams.set('customerId', customerId);
  url.searchParams.set('scope', scope);
  const response = await fetch(url, {
    method: 'POST',
    headers: { Authorization: `Bearer ${await getPartnerAccessToken()}` },
  });
  const body = await response.json();
  // A failed mint can arrive as HTTP 200 with an error envelope and no token.
  if (!response.ok || !body.access_token) {
    throw new Error(`Coinme browserAuth failed (${body.status ?? response.status})`);
  }
  return { token: body.access_token, expiresIn: Number(body.expires_in) };
};
```

The token lasts 10 minutes. When a submit fails because it expired, fetch a fresh one from the backend and retry once; [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md) has the error tables.

## Procedure

Follow the guide below in order. It is the integration guide for this platform as published, so the section names are the guide's own.

# Coinme Vault SDK for iOS Native

## Introduction

The Coinme Vault SDK for iOS is a Swift SDK that wraps the VGS Collect iOS SDK, pre-binds Coinme's VGS vault configuration, and exposes a small, secure data-collection API. It lets your application securely collect sensitive card and payment-method data (card number, expiry, CVV, cardholder name, billing address) and submit it directly to Coinme's vault without that data ever entering your application process.

It is the iOS counterpart to the Coinme Vault SDK for Android, and the public API mirrors the Android SDK for cross-platform parity.

**Security model:** Secure field values (card number, CVV, …) never leave the VGS field views and never enter your application process. The SDK exposes only validity and non-sensitive metadata (`isValid`, `isEmpty`, `cardBrand`, `last4`, …). Submission goes directly from the VGS views to the vault. **Error messages never contain field values (PII).**

### What Does It Collect?

The SDK collects only the payment data you explicitly bind into its fields, and submits it directly to the Coinme vault. The supported fields are:

- **Card data** — card number, expiry month/year, CVV
- **Cardholder name**
- **Billing address** — address lines, city, ZIP code

Your application never receives the raw field values — it sees only validity state and non-sensitive metadata such as the detected card brand and the last four digits.

## SDK Requirements

| Requirement | Value |
| --- | --- |
| Minimum iOS | 15.0 |
| Swift | 5.9 |
| VGS Collect | `~> 1.18` (resolves transitively) |

VGS Collect is resolved as a normal dependency, so the VGS field-view classes (`VGSCardTextField`, …) are available on your compile classpath without an extra dependency.

## Installation

**IMPORTANT:** Ask your Coinme integration contact to obtain your Cloudsmith **entitlement token**. The library publishes to Cloudsmith (`coinme/coinme-sdk-mobile`) for both Swift Package Manager and CocoaPods.

### Swift Package Manager

One-time registry login (uses your Cloudsmith entitlement token):

```
swift package-registry set https://swift.cloudsmith.io/coinme/coinme-sdk-mobile/swift package-registry login https://swift.cloudsmith.io/coinme/coinme-sdk-mobile/ \    --username YOUR_USERNAME --password YOUR_ENTITLEMENT_TOKEN
```

Then add the dependency:

`Package.swift`

```swift
// Package.swift
.package(id: "coinme.CoinmeVaultSDK", from: "1.0.0")
```

The SDK pulls VGSCollectSDK via SCM. To resolve it through the registry instead, run:

```
swift package --replace-scm-with-registry resolve
```

To add the package in Xcode:

**File → Add Package Dependencies**, add the registry URL above, then search for `coinme.CoinmeVaultSDK`.

### CocoaPods

`Podfile`

```swift
# Podfile — <ENTITLEMENT_TOKEN> supplied by Coinme
source 'https://dl.cloudsmith.io/<ENTITLEMENT_TOKEN>/coinme/coinme-sdk-mobile/cocoapods/index.git'
source 'https://cdn.cocoapods.org/'

target 'YourApp' do
  use_frameworks!
  pod 'CoinmeVaultSDK', '~> 1.0'   # pulls VGSCollectSDK transitively
end
```

## Configuration

The account-scoped **vault ID** is baked into the library per environment at publish time and is never passed by callers. For local development, copy `local.properties.example` to `local.properties` and fill in:

```
COINME_VAULT_ID_SANDBOX=your_sandbox_vault_id
COINME_VAULT_ID_LIVE=your_live_vault_id
```

**Ingress hostnames and the submit path are not configured here** — they are public, stable values baked into the SDK per environment (`config/VaultDefaults.swift`): sandbox → `secure.payments-stage.coinme.com`, live → `secure.payments.coinme.com`, path → `/caas/v2/paymentmethods`. They can be overridden per-runtime (but never the vault ID) via `RuntimeVaultConfig` — see Runtime configuration overrides below.

## Quick Start

```swift
import CoinmeVaultSDK

// 1. Create the vault for an environment.
let vault = try CoinmeVault.create(environment: .sandbox)

// 2. Build pre-named VGS fields against the vault's collector and bind them.
let cardNumber = CoinmeFields.cardNumber(collector: vault.collector)
let expiry     = CoinmeFields.expiry(collector: vault.collector)
let cvc        = CoinmeFields.cvc(collector: vault.collector)
let holder     = CoinmeFields.cardHolder(collector: vault.collector)
vault.bind(cardNumber, expiry, cvc, holder)   // add the views to your view hierarchy too

// 3. Observe form validity (drive your submit button's enabled state).
vault.onFormStateChange = { state in submitButton.isEnabled = state.isValid }

// 4. Submit. Throws CoinmeVaultError on failure.
let result = try await vault.submit(
    VaultSubmitOptions(
        extraData: ["accountId": "abc", "country": "US"],
        headers: ["X-Request-Source": "ios"]
    )
)
print("status=\(result.status) body=\(result.body ?? "")")

// 5. Release VGS resources when done (e.g. on screen teardown).
vault.dispose()
```

`CoinmeVault` is `@MainActor` — create it, build fields, bind, and observe state on the main actor.

## Core Concepts

| Type | Role |
| --- | --- |
| `CoinmeVault` | Entry point. Wraps a `VGSCollect` collector, tracks form validity, performs submits. `@MainActor`. |
| `CoinmeVaultEnvironment` | `.sandbox` or `.live`. Selects the baked-in vault ID / ingress / path. |
| `CoinmeFields` | Factory that builds VGS text fields with the correct Coinme field name and VGS type pre-set. |
| `VaultFieldNames` | The dot-notation field-name constants VGS deep-merges into nested submit JSON. |
| `VaultSubmitOptions` | Per-submit `extraData` (non-secure JSON) and `headers`. |
| `VaultSubmitResult` | `status: Int`, `body: String?`, `data: Any?` on success. |
| `CoinmeVaultError` | Error enum thrown by `submit`. |

The collector is exposed as `vault.collector: VGSCollect` — both the input to the `CoinmeFields` factories and the documented escape hatch for advanced VGS usage not covered by the wrapper.

### Creating a vault

```swift
let vault = try CoinmeVault.create(
    environment: .sandbox,
    config: nil   // optional RuntimeVaultConfig; see "Runtime configuration overrides"
)
```

`create()` resolves the vault configuration, builds the underlying `VGSCollect`, and registers a single form-state listener. It throws `CoinmeVaultError.invalidConfiguration` if the vault ID is not baked in or an override is incomplete. Create **one** `CoinmeVault` per form/screen and `dispose()` it when the screen goes away.

### Field names

Field names are **dot-notation keys** that VGS deep-merges into nested submit JSON (`card.cardNumber` → `{"card":{"cardNumber":...}}`). They are defined in `VaultFieldNames`:

| Constant | Value | Notes |
| --- | --- | --- |
| `cardNumber` | `card.cardNumber` |  |
| `expMonth` | `card.month` | child of the expiry serializer |
| `expYear` | `card.year` | child of the expiry serializer |
| `cvc` | `card.cvv` |  |
| `cardHolder` | `cardHolderName` |  |
| `address1` | `billingAddress.addressLine1` |  |
| `address2` | `billingAddress.addressLine2` |  |
| `city` | `billingAddress.city` |  |
| `zipCode` | `billingAddress.zipCode` |  |
| `expiry` | `card` | parent field name for the expiry field |

**The SDK submits every bound field.** Bind only the fields you intend to send.

The expiry field is the special case: its own field name is `card` and it uses a `VGSExpDateSeparateSerializer(monthFieldName: "card.month", yearFieldName: "card.year")` so a single input writes two JSON keys. The year is forced to 4 digits on output. `CoinmeFields.expiry()` configures all of this for you.

## Building Fields

VGS field views subscribe to their collector the moment their `configuration` is set, so each `CoinmeFields` factory takes the owning vault's collector:

```swift
import CoinmeVaultSDK

let cardNumber = CoinmeFields.cardNumber(collector: vault.collector)  // VGSCardTextField, "card.cardNumber"
let expiry     = CoinmeFields.expiry(collector: vault.collector)      // VGSExpDateTextField, separate-date serializer
let cvc        = CoinmeFields.cvc(collector: vault.collector)         // VGSCVCTextField, "card.cvv"
let holder     = CoinmeFields.cardHolder(collector: vault.collector)  // VGSTextField, "cardHolderName"
let custom     = CoinmeFields.text(collector: vault.collector, fieldName: "billingAddress.city")
```

`cardNumber`, `cvc`, and `cardHolder` accept an optional `fieldName` override; `expiry` does not (its serializer is fixed); `text` requires the field name. Returned views are ordinary `VGSTextField` subclasses — style them, add them to your view hierarchy, and `vault.bind(...)` them.

### Rendering VGS fields

VGS fields are UIKit `UIView`s. In UIKit, add them to your view hierarchy directly. In SwiftUI, wrap each field in a `UIViewRepresentable` (the demo's `VGSFieldView` is the canonical reference):

```swift
struct VGSFieldView: UIViewRepresentable {
    let field: VGSTextField
    func makeUIView(context: Context) -> VGSTextField { field }
    func updateUIView(_ uiView: VGSTextField, context: Context) {}
}
```

Build the fields once (e.g. in your view model) so they aren't recreated on every SwiftUI render, then render each with `VGSFieldView(field: cardNumber)`. See the `Example/` app for a full working form.

### Binding fields

```swift
func bind(_ fields: VGSTextField...)          // required fields
func bindOptional(_ fields: VGSTextField...)  // optional fields
```

`bind` registers each field name with the form-validity tracker. **Registration seeds the field as invalid** — a freshly bound form reports `isValid == false` until VGS emits its first state change. Bind a field once.

VGS emits no initial state, so an untouched field's validity is unknown until the user edits it. Use `bindOptional` for fields that may be left empty (e.g. `billingAddress.addressLine2`): they seed as **valid**, so an untouched form can still reach `isValid == true`. Fields with no configured `fieldName` are skipped by `bind`/`bindOptional` — always build them via `CoinmeFields` first.

## Observing Form State

```swift
var formState: VaultFormState                                   // current snapshot
var formStatePublisher: AnyPublisher<VaultFormState, Never>     // Combine stream
var onFormStateChange: ((VaultFormState) -> Void)?             // non-Combine callback
func fieldState(_ fieldName: String) -> VaultFieldState?        // one field

public struct VaultFormState: Equatable {
    public let fields: [String: VaultFieldState]
    public let isValid: Bool   // true only when every bound field is valid
}

public struct VaultFieldState: Equatable {
    public let fieldName: String
    public let isValid: Bool
    public let isEmpty: Bool
    public let isFocused: Bool
    public let contentLength: Int
    public let cardBrand: String?  // card-number field only
    public let last4: String?      // card-number field only
}
```

Typical use — drive the submit button:

```swift
// Callback style:
vault.onFormStateChange = { state in submitButton.isEnabled = state.isValid }

// Combine style:
vault.formStatePublisher
    .map(\.isValid)
    .receive(on: RunLoop.main)
    .assign(to: \.isEnabled, on: submitButton)
    .store(in: &cancellables)

// React to a single field, e.g. show the detected card brand:
let brand = vault.fieldState(VaultFieldNames.cardNumber)?.cardBrand
```

**No secure values are ever present in these snapshots** — only validity and the non-sensitive metadata shown above.

## Submitting the Data

> **Never use your partner access token with the Vault SDK.**
>
> The `Authorization` header must be `Bearer <transient-auth-token>` with a [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md) your backend mints from `POST /services/browserAuth`. Never pass your partner access token (from `POST /services/authorize`) to the SDK.

```swift
@discardableResult
func submit(_ options: VaultSubmitOptions = VaultSubmitOptions()) async throws -> VaultSubmitResult

public struct VaultSubmitOptions {
    public let extraData: [String: Any]   // deep-merged into the submit JSON alongside fields
    public let headers: [String: String]  // merged with trace headers; caller wins on conflict
}
```

What `submit` does, in order:

1. **Pre-validates** from the tracker; if the form is invalid it throws `CoinmeVaultError.validation(fields:)` **before any network call**.
2. Generates per-request `X-B3-TraceId` / `X-B3-SpanId` and merges your `headers` on top (your headers win on conflict).
3. POSTs to the configured submit path with `extraData` as custom data via VGS.
4. Maps the response — including the **CAAS envelope** case where VGS returns HTTP 200 with a nested `errorResponse` payload (thrown as `CoinmeVaultError.caas`, not returned as success).

**Only one submit may be in flight at a time** — a concurrent call throws `CoinmeVaultError.submitInProgress`.

### Completion-handler variant

```swift
vault.submit(VaultSubmitOptions()) { (result: Result<VaultSubmitResult, Error>) in
    switch result {
    case .success(let r): // ...
    case .failure(let e): // ...
    }
}
```

### Payment-method convenience

A higher-level helper for the CAAS payment-method endpoint:

```swift
let result = try await vault.submitPaymentMethod(
    PaymentMethodInput(
        accountId: "abc",
        providerId: "prov-1",
        webSessionId: "sess-1",
        paymentProcessAssociation: .buy,
        // optional billingAddress* fields default to ""/omitted; country defaults to "US"
        billingAddressFirstName: "Jane",
        billingAddressLastName: "Doe",
        billingAddressState: "WA"
    ),
    headers: ["Authorization": "Bearer \(transientAuthToken)"]
)
```

It builds the CAAS `extraData` shape (`accountId`, `stagingProviderId`, `webSessionId`, `paymentProcessAssociation`, `billingAddress`) and delegates to `submit`. The card fields themselves are supplied securely by the bound VGS fields.

## Error Handling

`submit` only ever throws `CoinmeVaultError`

```swift
do {
    try await vault.submit(options)
} catch let error as CoinmeVaultError {
    switch error {
    case .validation(let fields):
        fields.forEach { name, reasons in showFieldError(name, reasons) }
    case .caas:
        switch error.submitCardError {
        case .cardInUseByAnotherUser: showCardInUse()
        case .maxNumberOfCardsReached: showTooManyCards()
        default: showGenericError()
        }
    case .server(let status, _):
        showServerError(status)
    default:
        showGenericError()
    }
}
```

| Case | Meaning | Associated values |
| --- | --- | --- |
| `.validation(fields:)` | Form invalid; thrown before any network call. | `[String: [String]]` — `["required"]` / `["invalid"]` per field |
| `.network(underlying:)` | Connectivity / transport failure. | `Error?` |
| `.server(status:body:)` | HTTP 4xx/5xx with no recognizable CAAS envelope. | `Int`, `String?` |
| `.caas(status:errorResponse:)` | CAAS error envelope (4xx/5xx, or nested in an HTTP 200). | `Int`, `CaasErrorResponse` |
| `.submitInProgress` | A submit is already in flight. | — |
| `.invalidConfiguration(_:)` | Missing/invalid configuration (e.g. an unbaked vault ID). | `String` |
| `.unknown(underlying:)` | Anything else. | `Error?` |

`error.submitCardError` is a convenience on `CoinmeVaultError` that resolves the first known CAAS error code to a `SubmitCardError` (or `nil` if unrecognized). The raw code remains available via the associated `CaasErrorResponse` (`errorResponse.firstKnownError()?.errorCode`). `SubmitCardError` maps known CAAS card-submit codes to enum constants and is ported from the Coinme app to ease migration.

**Error cases never carry a field value (PCI).** Log them freely.

## Runtime Configuration Overrides

The vault ID is **always** baked in at publish time and cannot be overridden. The ingress host and submit path **can** be overridden at runtime by passing a `RuntimeVaultConfig` to `create`:

```swift
let runtime = RuntimeVaultConfig(
    sandbox: EnvironmentOverride(ingress: "tnt-xyz.sandbox.verygoodproxy.com", path: "/caas/v2/paymentmethods"),
    live:    EnvironmentOverride(ingress: "tnt-xyz.live.verygoodproxy.com",    path: "/caas/v2/paymentmethods")
)
let vault = try CoinmeVault.create(environment: .sandbox, config: runtime)
```

When `config` is `nil`, the baked-in defaults are used: a blank ingress means the VGS default host, and the path defaults to `/caas/v2/paymentmethods`.

## Lifecycle

Call `vault.dispose()` when the form is gone. It stops state observation and unsubscribes all VGS text fields to release resources. After disposal the instance must not be reused — create a new one.

In SwiftUI, tie disposal to the view's lifetime (e.g. call `dispose()` from `.onDisappear` on the view model that owns the vault).

## Verify

Build and run the app. Confirm the secure fields render and validate, that the submit control stays disabled until the form is valid, that the client gets a Transient Auth Token from the human's backend route and sends it as `Authorization: Bearer <token>` together with a Risk SDK session id fetched right before the submit and the device fingerprint the Risk SDK uses, that the `Authorization` header never carries the partner access token, and that no token or backend credential is in the client or a committed file.

### Reading the result

**Done when:** Invalid input keeps the form invalid, the submit succeeds, and listing the customer's payment methods from your backend shows the card `CREATED`.

**Stop and ask the human when** the card is refused as in use and you cannot find the earlier test that holds it, or the session tag keeps failing to match after you minted it on the same device.

Judge every Coinme call by its body, not its HTTP status: a refused request usually comes back as HTTP 200 with the error in the body. [Reading results](https://platformdocs.coinme.com/agents/results.md) has the rule, what each common error code asks you to do, and what to send your Coinme integration contact when something fails.

## Reference
- [Coinme Vault SDK](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md)
- [Coinme Vault SDK for iOS Native](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md)
- [Build: the Library of SDKs and documents](https://platformdocs.coinme.com/pages/build/library.md)
