> ## 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}`](/companies/api/reference/wallet-fund-status) to know when — that endpoint is the source of truth for money; treat any client-side signal as advisory.

## 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 (for example, a non-US user).
* **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.** `hosted` and `embedded` links both stay openable for the session's 30-minute window.

## 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](/companies/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.
* `fee_cents` on the create response is `null` when the fee is already included in the quoted total.

### 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](/companies/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 and returns the raw single-use
                    Apple Pay link for rendering inside your own in-app webview;
                    it lives about 5 minutes, must never be relayed through chat
                    (link unfurlers consume it), and counts toward the user's
                    per-user payment limits even if never paid, so mint it only
                    when the user initiates payment. Embedded sessions support
                    payment_method apple_pay only (google_pay with embedded is
                    rejected). Sandbox-mode credentials create TEST orders
                    (never charged). Embedded responses carry checkout_style
                    (web | web) — branch your rendering on it.
            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: >-
            Provider fee included in amount_cents, in USD cents. Returned only
            on the create response of embedded sessions (the order is priced at
            create time); absent on hosted sessions and on the poll endpoint.
            Null on the web checkout style (the fee is inside the quoted total).
          nullable: true
        checkout_style:
          type: string
          enum:
            - web
          description: >-
            Embedded create responses only. How to render checkout_url: 'web' —
            an Agentcard-hosted checkout page. Load it in a WKWebView (iOS) or
            Android WebView; on iOS 16+ the Apple Pay button renders in-app. The
            page navigates to /fund/success on completion.
    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.

````