> ## 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. # Get a funding session > Poll a funding session until it is `completed` — the payment status is refreshed from the provider on every read. ## Status values | Status | Meaning | What to do | | ------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pending` | The session can still complete: the link can still be opened, or a started payment is inside its grace. | Show the user the link you have (hosted: `checkout_url`; embedded: the link you rendered). No link to show? Wait, or create a new session (either is fine). | | `processing` | Paid — the deposit is settling. | Wait; poll again. | | `completed` | Funds are in the wallet. | Done. | | `failed` | The payment failed (`failure_reason` says why). | Create a new session. | | `expired` | The link was never opened within 30 minutes, or a started payment was abandoned. | Create a new session. | One policy covers every `pending` case, so you never need to diagnose them: surface the freshest link you hold, and whenever the user wants to retry, create a new session immediately, at any time. Sessions are independent; an unpaid one never charges, holds no funds, and needs no canceling (there is no cancel endpoint because none is needed). Hosted links are single-use: once the user opens the page and starts the payment sheet, that link is spent, even if they close it without paying, and a session whose started payment was abandoned reads `expired` on its own within about ten minutes of the attempt. `checkout_url` is present only while a hosted link can still be opened; embedded sessions never carry it here (the link appears only on the create response). `expires_at` always reflects the session's 30-minute funding window. ## Fees `fee_cents` is the payment provider's fee when known (`null` = unknown yet, never "free"). **Agentcard covers it** — the wallet is credited the full `amount_cents`; don't gross up. `fees_covered` reports the outcome: `true` (fee absorbed by Agentcard), `false` (rare anomalous fee — the wallet received the net amount), `null` (fee not known yet). ## OpenAPI ````yaml openapi.json GET /api/v2/wallet/fund/{session_id} 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/{session_id}: get: tags: - Wallet funding summary: Get a funding session description: >- Poll a funding session until it is `completed` — the payment status is refreshed from the provider on every read. operationId: walletFundStatus parameters: - name: session_id in: path required: true schema: type: string responses: '200': description: The funding session. content: application/json: schema: $ref: '#/components/schemas/FundingSession' example: object: funding_session id: os_123 user_id: usr_123 status: completed amount_cents: 5000 currency: USD payment_method: apple_pay failure_reason: null fee_cents: 89 fees_covered: true completed_at: '2026-07-13T18:12:00.000Z' created_at: '2026-07-13T18:00:00.000Z' expires_at: '2026-07-13T18:30:00.000Z' '401': $ref: '#/components/responses/Unauthorized' '404': description: '`not_found` — no funding session with that id for your users.' 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' 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 `. Tokens live one hour. ````