Funding a wallet

Each connected user has an Agentcard wallet that backs the cards they create. When the balance is short, you create a funding session and hand the user a checkout link — they pay with Apple Pay, Google Pay, or card, and the funds land in their wallet. You build the trigger and (optionally) host the checkout inside your app; Agentcard runs the payment. Funding reuses the user’s completed identity verification — there’s no separate verification step inside checkout. A user who isn’t verified yet is refused with kyc_required; run step 2 first, then fund. Every call is made from your backend with your platform access token, and names the user with the user_id you received when they connected. Each step links to its page in the API reference — full parameters, responses, error codes, and a live playground.

Instructions for your agent

Paste this into your coding agent to implement wallet funding. It assumes the user is already connected and identity-verified (you have their user_id).

Instructions for your agent

You are adding wallet funding for a connected, identity-verified user (you have
their user_id). Implement server-side with your platform token
(Authorization: Bearer <token>); base URL https://api.agentcard.sh.

1. CREATE A FUNDING SESSION
POST /api/v2/wallet/fund
  { "user_id": "<id>", "amount_cents": <int>,
    "payment_method": "apple_pay" | "google_pay" (optional, default apple_pay),
    "link_type": "hosted" | "embedded" (optional, default hosted) }
-> 201 { id, status: "pending", amount_cents, currency, payment_method,
         link_type, checkout_url, expires_at, fees_covered, checkout_style?,
         fee_cents?, embed_url?, crossmint? }

FEES: Agentcard covers the payment provider's fee — send amount_cents for
exactly what the user should receive; the wallet is credited in full. Do NOT
gross up the charge. fee_cents is the provider's fee we absorb (null = unknown
yet, never "free"); fees_covered true = fee on us, false = rare anomalous fee
(net delivery), null = not known yet.

Pick link_type by where the user is:
  - "hosted"  (default): checkout_url is an Agentcard-hosted page. Relay it
    anywhere — a button, a QR code, a chat message. The payment order is created
    only when the user opens it, so an unopened link costs nothing.
  - "embedded": the payment order is minted immediately for rendering inside
    your own app. Mint it ONLY when the user taps "Add funds" (it places a real
    order); never relay it (link unfurlers can consume it); render it
    immediately.

2. HANDLE THE 422s (verification-gated)
  - kyc_required        -> user isn't verified; run identity verification, retry.
  - funding_profile_required -> a one-time funding profile is missing; collect it, retry.
  - kyc_transfer_required    -> a one-time carry-over of an existing verification; do it, retry.
  - unsupported         -> the user's verification can't be used (e.g. non-US).
  - amount_out_of_range -> read min_amount_cents / max_amount_cents from the body;
                           don't hardcode limits.

3. SHOW THE CHECKOUT — branch on checkout_style (embedded only)
  - "crossmint_sdk": PREFERRED — render the response's `embed_url` (a
    fully-built, provider-opaque wallet-button page; treat it as a black box)
    in an in-app webview. On iOS use Agentcard's AgentcardPayButton component
    (SwiftPM: github.com/tiny-agent-company/agentcard-ios) — it renders
    embed_url as a native-looking Apple Pay button pill; one tap pops the
    REAL native Apple Pay sheet in-app. No domain verification, no Apple
    merchant ID, no provider constants in your code.
      AgentcardPayButton(embedUrl: session.embedUrl) { /* ready */ }
        .frame(height: 58)
    Alternative (vendor SDK): the `crossmint` object
    { order_id, client_secret, client_api_key, api_environment } boots
    Crossmint's own checkout SDKs (Swift/Kotlin/React Native) if you prefer
    their full checkout component. checkout_url remains the plain web
    fallback.
  - "cb_onramp": load checkout_url in a WKWebView and register a message
    handler named "cbOnramp" — the page pops the native Apple Pay sheet and
    posts lifecycle events (load_success, commit_success, cancel, ...).
  - "web" or anything else: open checkout_url in a browser context. Optional:
    append "&only=apple_pay" (or "&only=google_pay") to the checkout_url
    fragment to show a wallet-only sheet with no card form.

4. CONFIRM COMPLETION (source of truth)
Poll GET /api/v2/wallet/fund/<session_id>
-> { status, amount_cents, currency, failure_reason?, completed_at?, ... }
status: pending -> processing -> completed (or failed / expired).
Treat the status endpoint as authoritative; SDK callbacks and the embedded
page's /fund/success navigation are advisory UX signals only. client_secret is
returned once at create time and never again — if the app loses it, create a
new session.

ERRORS: { error: { code, message, docs } } — branch on code.

TESTING (test-mode credentials only): sandbox clients create TEST orders (never
charged), so you can exercise the full flow end to end before switching to live
keys.

The flow

Create a funding session

From your backend, POST /api/v2/wallet/fund with the user_id and amount_cents. Choose link_type: hosted (default) returns an Agentcard-hosted page you can relay anywhere; embedded returns an in-app link you load in a WebView. If the user isn’t verified you get 422 kyc_required — send them through identity verification first. Read min_amount_cents / max_amount_cents off 422 amount_out_of_range rather than hardcoding limits.→ Create a funding session

Show the checkout

Hosted: open or relay checkout_url; the user pays in their browser.Embedded: branch on the response’s checkout_style.crossmint_sdk — render the response’s embed_url with Agentcard’s iOS component and the real native Apple Pay sheet slides up in-app — no domain verification, no Apple merchant ID or entitlements, and no payment-provider constants in your code (embed_url is built server-side and provider-opaque, so the rail behind it can change without you re-integrating):

import AgentcardFunding // SwiftPM: github.com/tiny-agent-company/agentcard-ios

AgentcardPayButton(embedUrl: session.embedUrl)
    .frame(height: 58)

The component renders a black wallet-button pill (label is Apple-mandated); one tap opens the native sheet. Alternatively, the crossmint object (order_id, client_secret, client_api_key, api_environment) boots Crossmint’s own checkout SDKs (Swift / Kotlin / React Native) if you prefer their full checkout component — native Google Pay rides the Kotlin/React Native path. checkout_url remains a plain web fallback if you can’t ship either.cb_onramp — load checkout_url in a WKWebView and register a script message handler named cbOnramp; the page renders the Apple Pay button in-app and posts lifecycle events (load_success, commit_success, cancel, …) to your handler.web (or any unrecognized style) — open checkout_url in a browser context. To present a wallet-only sheet (just the Apple Pay button, no card form), append &only=apple_pay to the checkout_url fragment.Mint an embedded session only when the user has actually initiated payment, render it immediately, and never relay it — link unfurlers can consume it.

Confirm completion

Poll GET /api/v2/wallet/fund/{session_id} until completed. That endpoint is the source of truth for money; treat any client-side signal (SDK callbacks included) as advisory. The embedded web page also navigates to /fund/success when payment completes, which you can observe to close your WebView. client_secret is returned once at create time and never again — if your app loses it, create a new session.→ Get a funding session

Status values

Status	Meaning	What to do
`pending`	Waiting for the user to open the link and pay.	Hosted: show `checkout_url`. Embedded: keep the WebView link you 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 went unused within its window, or payment was started and abandoned.	Create a new session.

Testing in test mode

With a test-mode credential the whole flow runs against a test environment — sandbox clients create TEST orders that are never charged, so you can exercise create → checkout → completed end to end (including the embedded WebView flow) before switching to live keys. On a physical device, cards must be in the platform wallet; simulators can’t show the Apple Pay sheet.

Getting Started

Authentication

Guides

Webhooks

Funding options

Withdrawals

MCP

Examples

Instructions for your agent

The flow

Status values

Testing in test mode

​Instructions for your agent

​The flow

​Status values

​Testing in test mode

Instructions for your agent

The flow

Status values

Testing in test mode