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

# Create a funding session

> Returns an Apple Pay / Google Pay payment link for the amount you specify. Show it in your UI; when the user completes the payment the funds land in their wallet. The link is single-use and expires after 30 minutes. Requires a phone verification fresh within 60 days — see `POST /api/v2/wallet/phone/start`.

## How it works

Ask for a funding session for an amount; we return a `checkout_url`. There are two kinds, picked with `link_type`:

* **`hosted`** (default): an Agentcard-hosted payment page. Render it anywhere — an "Add funds" button, a QR code, a chat message — and the user opens it and pays with Apple Pay, Google Pay, or card. Safe to relay: the underlying payment order is created only when the user opens the page. Creating a hosted session is free; an unopened link costs nothing.
* **`embedded`**: an in-app payment link, minted immediately. Load `checkout_url` in a `WKWebView` (iOS) or Android WebView and the user pays without leaving your app.

When the payment completes, the funds land in the user's wallet. Poll [`GET /api/v2/wallet/fund/{session_id}`](/api-reference/wallet/fund-status) to know when — that endpoint is the source of truth for money; treat any client-side signal as advisory.

## Fees: send the exact amount

**Agentcard covers the payment provider's fee.** Send `amount_cents` for exactly what the user should receive — the wallet is credited the full amount. Do **not** gross up the charge to compensate for fees; that just over-charges your user.

* `fee_cents` on the create and status responses is the provider's fee (which Agentcard absorbs) when known, or `null` while it isn't yet — `null` means "unknown", never "free".
* `fees_covered` tells you whether the fee is on us: `true` (it is — the user receives the full `amount_cents`), `false` (an anomalous fee we won't absorb — the wallet receives the net amount), or `null` (fee not known yet). `false` is rare; treat it as net delivery rather than failing the flow.

## Requirements

* **The user must be identity-verified.** Funding reuses the user's completed identity verification — there is no separate verification step inside checkout. If the user isn't verified, create-session returns `422 kyc_required`; run identity verification first, then retry. Other verification-related 422s:
  * `funding_profile_required` — a one-time funding profile is missing (collect it, then retry).
  * `kyc_transfer_required` — the user's existing verification needs a one-time carry-over before funding (a single extra step, no re-verification).
  * `unsupported` — the user's verification can't be used for funding. The body's `reason` names the wall. `restricted_country` (or a `*_region_unsupported` value) means the user's country of residence isn't served for funding: nothing about their verification is missing, so don't send them back through identity verification. `incomplete_address`, `no_identity_document`, `no_nationality`, `no_phone`, and `no_full_ssn` (US residents) clear once that detail is on the user's verification.
* **Amount bounds come from the API.** If the amount is out of range you get `422 amount_out_of_range` with `min_amount_cents` and `max_amount_cents` in the response — read those rather than hardcoding limits.
* **Link lifetime.** Every session has a 30-minute window (`expires_at`), but a link is consumed by use, not just by time. A `hosted` link is single-use: the moment the user opens the page and starts the payment sheet, that link is spent, even if they close it without paying. An `embedded` link must be rendered immediately (its underlying payment token lives about 5 minutes).
* **Abandoned sessions need no cleanup.** There is no cancel endpoint because none is needed: an unpaid session never charges, holds no funds, and flips to `expired` on its own. To retry, create a new session at any time; sessions are independent of each other, and creating `hosted` sessions is free and not throttled. See [session status](/api-reference/wallet/fund-status) for the poll-side rule.

## Embedded: in-app checkout

Create the session with `link_type: "embedded"`, hand `checkout_url` to your app, and load it in a WebView:

```swift theme={null}
let webView = WKWebView(frame: .zero, configuration: WKWebViewConfiguration())
webView.load(URLRequest(url: checkoutUrl))
```

* **Apple Pay** renders inside a `WKWebView` on **iOS 16+** (Apple Pay on the Web is supported in `WKWebView`, but **not** in `SFSafariViewController` — use a `WKWebView`). On older iOS the user pays with Google Pay or card. No domain verification is required on your side; the checkout runs on our Apple-registered domain and pops the native Apple Pay sheet in-app.
* **Google Pay** works in a modern Android WebView; **card** is always available as a fallback.
* **Completion:** the page navigates to **`/fund/success`** when the payment completes — observe that navigation to close your WebView — and the [status endpoint](/api-reference/wallet/fund-status) is the authoritative confirmation.
* **Wallet-only sheet:** append `&only=apple_pay` (or `&only=google_pay`) to the `checkout_url` fragment to present just that wallet button with no card form.

### Mint on demand, not per render

Every embedded session creates a real payment order the moment you call the endpoint. Mint one only when the user has actually initiated payment (tapped "Add funds"), render it immediately, and create a fresh session for the next attempt if the link lapses. Don't mint on page render or in retry loops — the API refuses excess pending sessions for the same user with `too_many_pending_sessions`.

* **Never relay an embedded link** through chat or email; link unfurlers can consume it and leave the user a dead page. Server → WebView, immediately, is the only safe path.
* The embedded `checkout_url` appears only on the create response; the [status endpoint](/api-reference/wallet/fund-status) never re-serves it. If it lapsed, create a new session.
* **Test with sandbox-mode credentials** — sandbox clients create TEST orders (never charged), so you can exercise the full WebView flow end to end before switching to live keys.
* On a physical device, cards must be in the platform wallet; simulators cannot show the Apple Pay sheet.


## OpenAPI

````yaml openapi.json POST /api/v2/wallet/fund
openapi: 3.1.0
info:
  title: Agentcard API
  version: 2.0.0
  description: >-
    The Agentcard v2 API — connect your users and verify their identity from
    your own backend. Every call is authenticated with a platform access token
    minted from your `client_id` + `client_secret`.
servers:
  - url: https://api.agentcard.sh
    description: >-
      There is one base URL. Sandbox vs production is decided by the client
      credential you use, never by the host.
security:
  - platformToken: []
tags:
  - name: Authentication
    description: >-
      Exchange your client credentials for a platform access token, and
      introspect what a token acts as.
  - name: Connect
    description: >-
      Connect a user to your platform: send a one-time code, verify it, record
      consent, and keep the connection alive.
  - name: Identity verification
    description: >-
      Verify a connected user's identity: upload their ID, submit any extra
      fields we ask for, then show a short face scan.
  - name: Wallet funding
    description: >-
      Fund a connected user's wallet from your own UI — request a payment link,
      relay the phone verification code, and poll until the funds land.
  - name: Withdrawals
    description: >-
      Move money out of a connected user's wallet — to a saved bank account or a
      crypto address on Base. Transfers are processed manually by the Agentcard
      team, usually within 1-3 business days.
paths:
  /api/v2/wallet/fund:
    post:
      tags:
        - Wallet funding
      summary: Create a funding session
      description: >-
        Returns an Apple Pay / Google Pay payment link for the amount you
        specify. Show it in your UI; when the user completes the payment the
        funds land in their wallet. The link is single-use and expires after 30
        minutes. Requires a phone verification fresh within 60 days — see `POST
        /api/v2/wallet/phone/start`.
      operationId: walletFund
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - amount_cents
              properties:
                user_id:
                  type: string
                  description: The connected user's id.
                amount_cents:
                  type: integer
                  description: Amount to fund, in USD cents.
                payment_method:
                  type: string
                  enum:
                    - apple_pay
                    - google_pay
                  default: apple_pay
                  description: >-
                    google_pay with link_type "embedded" is accepted when the
                    user's rail returns the web checkout style; on web rails
                    embedded is Apple Pay only (422
                    payment_method_not_supported).
                link_type:
                  type: string
                  enum:
                    - hosted
                    - embedded
                  default: hosted
                  description: >-
                    hosted returns an Agentcard-hosted payment page, safe to
                    relay anywhere (chat, email, QR); the underlying payment
                    order is created only when the user opens it, so unopened
                    hosted sessions cost nothing. embedded creates a REAL
                    payment order immediately for rendering inside your own app;
                    mint it only when the user initiates payment, render it
                    immediately, and never relay it through chat (link unfurlers
                    consume it). Embedded responses carry checkout_style
                    (crossmint_sdk | cb_onramp | web) — branch your rendering on
                    it: crossmint_sdk boots Crossmint's native mobile SDK from
                    the response's `crossmint` object (native Apple Pay / Google
                    Pay sheet in-app), cb_onramp loads checkout_url in a
                    WKWebView with the cbOnramp message handler (Apple Pay only
                    — google_pay on that rail is rejected with
                    payment_method_not_supported; the link lives about 5 minutes
                    and counts toward the user's per-user payment limits even if
                    never paid), web opens checkout_url in a browser context.
                    Sandbox-mode credentials create TEST orders (never charged).
            example:
              user_id: usr_123
              amount_cents: 5000
              payment_method: apple_pay
      responses:
        '201':
          description: The funding session, with the payment link to show the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingSession'
              example:
                object: funding_session
                id: os_123
                user_id: usr_123
                status: pending
                amount_cents: 5000
                currency: USD
                payment_method: apple_pay
                checkout_url: https://api.agentcard.sh/fund/…
                expires_at: '2026-07-13T18:30:00.000Z'
        '400':
          description: '`invalid_request` — missing or malformed fields.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ConnectionNotFound'
        '409':
          $ref: '#/components/responses/UserConflict'
        '422':
          description: >-
            `amount_out_of_range` (with `min_amount_cents` /
            `max_amount_cents`), `phone_verification_required`,
            `email_required`, or `region_not_supported`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: '`funding_provider_error` — try again.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '`funding_unavailable` — funding is temporarily unavailable.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    FundingSession:
      type: object
      properties:
        object:
          type: string
          const: funding_session
        id:
          type: string
        user_id:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - expired
        amount_cents:
          type: integer
        currency:
          type: string
        payment_method:
          type: string
          enum:
            - apple_pay
            - google_pay
        checkout_url:
          type: string
          description: >-
            The payment link to show the user. hosted: an Agentcard-hosted page,
            present while the link can still be opened. embedded: the raw
            provider Apple Pay link, present ONLY on the create response; the
            poll endpoint never re-serves it, so load it in an in-app webview
            immediately, never relay it, and create a new session if it lapses.
        failure_reason:
          type:
            - string
            - 'null'
          enum:
            - region_not_supported
            - provider_error
            - null
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
          description: >-
            On the create response: hosted links stay openable for 30 minutes;
            embedded links are single-use and expire about 5 minutes after
            creation (create a new session instead of retrying a lapsed link).
            On the poll endpoint, expires_at always reflects the session's
            30-minute fundability window, not the embedded link's shorter life.
        link_type:
          type: string
          enum:
            - hosted
            - embedded
          description: >-
            Which kind of checkout_url this session carries. Returned only on
            the create response; the poll endpoint does not include it.
        fee_cents:
          type:
            - integer
            - 'null'
          description: >-
            The payment provider's fee in USD cents, which Agentcard covers (see
            fees_covered) — the user's wallet is credited the full amount_cents,
            so do NOT gross up the charge. Null while the fee isn't known yet
            (e.g. a hosted link whose payment order hasn't been minted) — null
            means unknown, never free. Always present on both the create
            response and the poll endpoint.
          nullable: true
        fees_covered:
          type:
            - boolean
            - 'null'
          description: >-
            Whether Agentcard absorbs the provider fee for this session. true:
            the wallet receives the full amount_cents — send the exact amount
            the user should receive and do not gross up. false (rare): the fee
            was anomalous and the wallet receives the net amount. null: the fee
            isn't known yet. After completion this reflects the actual outcome.
          nullable: true
        checkout_style:
          type: string
          enum:
            - crossmint_sdk
            - cb_onramp
            - web
          description: >-
            Embedded create responses only — which rendering contract applies.
            'crossmint_sdk': initialize Crossmint's native mobile checkout SDK
            with the `crossmint` object (native Apple Pay / Google Pay sheet
            in-app; checkout_url stays a web fallback). 'cb_onramp': load
            checkout_url in a WKWebView with a script message handler named
            cbOnramp (native Apple Pay button page with lifecycle events).
            'web': open checkout_url in a browser context; the page navigates to
            /fund/success on completion. Treat unrecognized values as 'web'.
        embed_url:
          type: string
          description: >-
            Embedded create responses on the crossmint_sdk style only — the
            PREFERRED integration. A fully-built, provider-opaque wallet-button
            page: load it as-is in an in-app webview (Agentcard's iOS tooling
            renders it as a native-looking Apple Pay button pill). Built
            entirely server-side, so the payment rail behind it can change
            without any partner-side work. Same one-time, single-order lifetime
            as the credentials it embeds.
        crossmint:
          type: object
          description: >-
            Embedded create responses on the crossmint_sdk style only. Boot
            credentials for Crossmint's native checkout SDK (Swift / Kotlin /
            React Native) — an alternative to embed_url for apps that prefer the
            vendor SDK. client_secret is scoped to this single order and is
            returned exactly once — hand it to the paying user's device, never
            store or relay it; create a new session if it is lost.
          required:
            - order_id
            - client_secret
            - client_api_key
            - api_environment
          properties:
            order_id:
              type: string
              description: >-
                The Crossmint order backing this session — pass as the SDK's
                orderId.
            client_secret:
              type: string
              description: >-
                Single-order checkout credential — pass as the SDK's
                clientSecret.
            client_api_key:
              type:
                - string
                - 'null'
              description: >-
                Agentcard's public Crossmint client key. Required by the React
                Native SDK's CrossmintProvider; the Swift/Kotlin SDKs only need
                orderId + clientSecret.
              nullable: true
            api_environment:
              type: string
              enum:
                - production
                - staging
              description: >-
                Which Crossmint environment minted the order — initialize the
                SDK's environment to match.
    Error:
      type: object
      description: Every v2 error uses the same envelope.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable, machine-readable string (snake_case). Branch on this.
            message:
              type: string
              description: A human-readable explanation, safe to log.
            docs:
              type: string
              description: A link back to the reference.
            field_errors:
              type: object
              additionalProperties:
                type: string
              description: Only on `invalid_fields` — names each field to fix.
            warnings:
              type: array
              items:
                type: string
              description: >-
                Only on document upload errors — actionable feedback safe to
                show the user.
  responses:
    Unauthorized:
      description: >-
        `unauthorized` — the platform access token is missing or expired.
        Exchange your client credentials for a fresh one.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ConnectionNotFound:
      description: >-
        `connection_not_found` — no connection exists for that user under your
        client.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UserConflict:
      description: >-
        `user_conflict` — the email on file in your organization belongs to a
        different account. Contact support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    platformToken:
      type: http
      scheme: bearer
      description: >-
        A platform access token. Get one on the **Create an access token**
        endpoint by exchanging your `client_id` + `client_secret`, then send it
        as `Authorization: Bearer <token>`. Tokens live one hour.

````