> ## 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` | Waiting for the user to open the link and pay. | Hosted: show the `checkout_url`. Embedded: keep the webview link you already rendered. | | `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 used within 30 minutes, or the payment was started and abandoned. | Create a new session. | `checkout_url` is present only while a hosted link can still be opened. Embedded sessions never carry `checkout_url` here — the link appears only on the create response; if it lapsed, create a new session. `expires_at` on this endpoint always reflects the session's 30-minute fundability window. ## 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 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: >- 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' 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. ````