> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nevermined.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Enrollment

> Enroll Visa, Stripe, or Braintree payment cards into Nevermined with PCI-compliant tokenization.

## Overview

Before an agent can charge a payment card, the card must be enrolled in Nevermined. Enrollment tokenizes the card data (Nevermined never stores raw card numbers) and registers the card with the provider so future delegations can authorize off-session charges.

Nevermined supports three enrollment providers, each available as a separate tab in the [Nevermined App](https://nevermined.app). Which provider you should enroll with depends on the plan you intend to pay for — the plan's `fiatPaymentProvider` metadata determines the required card type:

* **Stripe-priced plans** require a Stripe-vaulted card.
* **Braintree-priced plans** require a Braintree-vaulted card.
* **Visa Trusted Agent plans** require a Visa Agentic Token (enrolled through the Visa tab).

## Enrollment Paths

<Tabs>
  <Tab title="Visa">
    ### Visa Enrollment

    Visa cards are enrolled as **Visa Agentic Tokens** through the VGS Credential Management Platform (CMP). Card capture happens in a VGS Collect iframe in the Nevermined webapp, so the raw PAN never reaches Nevermined infrastructure.

    <Steps>
      <Step title="Capture card data">
        Enter your card details in the VGS Collect iframe rendered by the webapp. VGS Collect's `form.createCard()` posts the tokenized card directly to CMP and returns a CMP `cardId` (`CRD…`) to the browser. The PAN and CVC never transit the Nevermined backend.
      </Step>

      <Step title="Mint the Agentic Token">
        The browser sends only the `cardId` (plus BIN-derived `last4`, `brand`, and `expMonth`/`expYear`) to `POST /api/v1/delegation/enroll-visa`. The backend calls VGS Agentic `POST /cards/{cardId}/agentic-tokens` to mint the long-lived Agentic Token (`vat_…`) and persists it as the card's `providerPaymentMethodId`.
      </Step>

      <Step title="Create a delegation">
        After enrollment, create a [spending delegation](/docs/products/payments/mandates). Each Visa delegation requires a one-time WebAuthn/passkey device-binding ceremony embedded by Visa VTS — see the Visa tab on the [Delegations](/docs/products/payments/mandates) page.
      </Step>
    </Steps>

    #### Visa Card Lifecycle

    ```
    PAN captured in VGS Collect iframe
      |
      |-> CMP card created (cardId)
      |
      |-> Backend enrolls Agentic Token (vat_…)
      |
      |-> PaymentMethodEntity persisted (provider='visa')
      |
      |-> Active -> Delegations can be created
            |
            |-> Removed (card and all delegations revoked)
    ```

    <Note>
      VGS Agentic Tokens are keyed on PAN globally. Re-enrolling the same physical card always resolves to the same `cardId`/`tokenId`. If the card is already enrolled under a different Nevermined account, enrollment returns `BCK.VISA.0018` (HTTP 409).
    </Note>

    <Note>
      No passkey is required at enrollment. The WebAuthn/passkey ceremony happens once per delegation, not once per card.
    </Note>

    <Note>
      Visa enrollment is only reachable from the Nevermined webapp. The `/api/v1/delegation/enroll-visa` endpoint expects a CMP `cardId` produced by VGS Collect in the browser; it cannot be driven from a server-side SDK or curl call.
    </Note>
  </Tab>

  <Tab title="Stripe">
    ### Stripe Enrollment

    Stripe cards are captured via a VGS Collect iframe and confirmed against a Stripe SetupIntent. This is a single-step flow with no passkey requirement.

    <Steps>
      <Step title="Request a SetupIntent">
        The webapp asks the API for a Stripe SetupIntent. The API returns the `client_secret`.
      </Step>

      <Step title="Enter card details">
        Enter your card number, expiry, and CVC into the VGS Collect iframe. VGS forwards the tokenized card directly to Stripe to confirm the SetupIntent and return a PaymentMethod (`pm_…`).
      </Step>

      <Step title="Finalize enrollment">
        The webapp posts the SetupIntent ID to `POST /api/v1/delegation/finalize-enrollment`. The API links the Stripe `pm_…` to the user.
      </Step>

      <Step title="Create a delegation">
        After enrollment, create a [spending delegation](/docs/products/payments/mandates) to define how agents can charge this card.
      </Step>
    </Steps>

    #### Stripe Card Lifecycle

    ```
    SetupIntent created
      |
      |-> Card confirmed (VGS Collect -> Stripe tokenization)
      |
      |-> Enrollment finalized (linked to Nevermined account)
      |
      |-> Active -> Delegations can be created
            |
            |-> Removed (card and all delegations revoked)
    ```
  </Tab>

  <Tab title="Braintree">
    ### Braintree Enrollment

    Braintree cards are captured via the Braintree Drop-in (or hosted fields) and exchanged for a vaulted `paymentMethodToken`. The flow is similar to Stripe — no passkey is required — but uses Braintree's tokenization and vaulting primitives so the token can be charged by the seller's OAuth-connected Braintree merchant at settlement time.

    <Steps>
      <Step title="Request a client token">
        The Nevermined webapp requests a short-lived **Braintree client token** from the facilitator. The client token authorizes the in-browser Drop-in / hosted fields to talk directly to Braintree.
      </Step>

      <Step title="Enter card details">
        Enter your card number, expiry, and CVC into the Braintree Drop-in. Card data goes directly to Braintree and never touches the Nevermined backend. Drop-in returns a single-use **payment-method nonce** to the browser.
      </Step>

      <Step title="Vault the card">
        The browser submits the nonce to `POST /api/v1/delegation/enroll-braintree`. The facilitator looks up (or creates) your Braintree customer record and exchanges the nonce for a permanent **`paymentMethodToken`** by vaulting the card with `verifyCard: true`. From this point on, Nevermined only ever stores the token — never raw card data.
      </Step>

      <Step title="Create a delegation">
        After enrollment, create a [spending delegation](/docs/products/payments/mandates) backed by the vaulted Braintree token. The delegation can then settle x402 charges against any Braintree-priced plan in the supported currency.
      </Step>
    </Steps>

    #### Braintree Card Lifecycle

    ```
    Client token requested
      |
      |-> Card details captured (Braintree Drop-in tokenization)
      |
      |-> Nonce returned to browser (single-use)
      |
      |-> Card vaulted (paymentMethodToken issued, verifyCard pass)
      |
      |-> Active -> Delegations can be created
            |
            |-> Removed (card and all delegations revoked)
    ```

    <Note>
      A Braintree-vaulted card can only be charged for plans whose seller has a Braintree merchant account in the card's transaction currency. See [Braintree onboarding](/docs/products/payments/braintree-onboarding) for the seller-side per-currency requirements.
    </Note>
  </Tab>
</Tabs>

## Card Properties

Visa, Stripe, and Braintree cards share these core properties:

| Property                  | Description                                                                                              |
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `id`                      | Unique payment-method identifier (UUID)                                                                  |
| `userId`                  | Owner of the card                                                                                        |
| `provider`                | `visa`, `stripe`, or `braintree`                                                                         |
| `providerPaymentMethodId` | PSP-side token. Visa: `vat_…` (Agentic Token). Stripe: `pm_…`. Braintree: `paymentMethodToken`.          |
| `last4`                   | Last 4 digits of the card number (for display)                                                           |
| `brand`                   | Card brand (`visa`, `mastercard`, …)                                                                     |
| `alias`                   | User-friendly name (e.g., "Work Visa", "Dev Card")                                                       |
| `status`                  | `active` or `inactive`                                                                                   |
| `spendingCeiling`         | Maximum total amount that can be allocated across all active delegations on this card (default: \$10.00) |

## Spending Ceiling

Every card has a **spending ceiling** — a cumulative limit on the total amount allocated to active delegations. This prevents over-allocation and provides a safety net. Visa, Stripe, and Braintree cards enforce the same ceiling.

For example, if your card has a \$10.00 ceiling:

* Delegation A: \$5.00
* Delegation B: \$3.00
* Remaining capacity: \$2.00

<Note>
  The default spending ceiling is \$10.00 during the pilot phase. Contact the Nevermined team if you need a higher limit.
</Note>

When you create or update a delegation, Nevermined validates that the total allocated amount across all active delegations on the card doesn't exceed the ceiling. If it would, the request is rejected with a clear error showing the remaining capacity.

## Managing Cards

### Via the Nevermined App

The [Nevermined App](https://nevermined.app) provides a visual interface for managing your enrolled cards. Visa, Stripe, and Braintree cards appear in separate tabs:

* View all enrolled cards with their status and spending ceiling
* See active delegations per card with remaining capacity
* View transaction history for each card
* Deactivate or remove cards

### Via the API

The payment-methods endpoint is heterogeneous: it lists enrolled cards across all three providers plus, when the user has a smart account configured, the ERC-4337 wallet entry that backs crypto delegations. Filter by `provider` to narrow to a single shape.

| Endpoint                               | Method   | Description                                             |
| -------------------------------------- | -------- | ------------------------------------------------------- |
| `/api/v1/payment-methods`              | `GET`    | List enrolled payment methods (cards + ERC-4337 wallet) |
| `/api/v1/payment-methods/{id}`         | `PATCH`  | Update alias or allowed API keys                        |
| `/api/v1/payment-methods/{id}`         | `DELETE` | Remove card and revoke all delegations on it            |
| `/api/v1/delegation/{id}/transactions` | `GET`    | Per-delegation transaction history                      |

## Choosing a Provider

|                           | Visa                                                            | Stripe                                               | Braintree                                                                               |
| ------------------------- | --------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Enrollment complexity** | VGS Collect capture, no passkey at enrolment                    | VGS Collect capture against a SetupIntent            | Braintree Drop-in capture                                                               |
| **Per-delegation auth**   | WebAuthn/passkey device binding (browser-only)                  | API credentials only                                 | API credentials only                                                                    |
| **Best for**              | Visa Trusted Agent Protocol plans, high-security agent payments | Quick setup, developer testing, broader card support | Plans whose seller settles on Braintree (per-currency merchant accounts, OAuth Connect) |
| **Settlement**            | Stripe Connect against the seller's connected account           | Stripe PaymentIntents directly                       | Braintree `transaction.sale` against vaulted `paymentMethodToken`                       |

All three providers support the same spending controls (ceilings, usage limits, expiration) and API key linking. The right enrollment provider for a given plan is determined by the plan's `fiatPaymentProvider` metadata: a Braintree-priced plan can only be paid by a Braintree-vaulted card; a Visa Trusted Agent plan can only be paid by a Visa Agentic Token.

Don't guess — read the plan's provider before you enroll. `resolveNetwork()` / `resolve_network()` returns the plan's card provider (`stripe`, `braintree`, or `visa`), or `undefined`/`None` for a crypto plan:

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { resolveNetwork } from '@nevermined-io/payments'

    const provider = await resolveNetwork(payments, planId)
    // 'stripe' | 'braintree' | 'visa' for fiat plans; undefined for crypto plans
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from payments_py.x402.resolve_scheme import resolve_network

    provider = resolve_network(payments, plan_id)
    # 'stripe' | 'braintree' | 'visa' for fiat plans; None for crypto plans
    ```
  </Tab>
</Tabs>

Enroll with that provider, then [create a delegation](/docs/products/payments/mandates) from the enrolled card. If `resolveNetwork` returns nothing, the plan is crypto — fund a smart account instead of enrolling a card.

## What's Next?

Once your card is enrolled, create a spending delegation to control how agents can charge it.

<Card title="Create a Delegation" icon="shield-check" href="/docs/products/payments/mandates">
  Define spending limits, usage caps, and expiration for agent payments
</Card>