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, checkout_style? , fee_cents? }

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": checkout_url is an in-app link, minted immediately. Load it in a
    WKWebView (iOS) or Android WebView so the user pays without leaving your 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
  - hosted: open/relay checkout_url.
  - embedded: load checkout_url in a WKWebView. On iOS 16+ the Apple Pay button
    renders in-app (Apple Pay on the Web works in WKWebView, NOT in
    SFSafariViewController — use WKWebView). Google Pay works in a modern Android
    WebView; card is always available. No domain verification on your side.
    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).
The embedded page also navigates to /fund/success on completion — observe that
navigation to close your WebView — but treat the status endpoint as authoritative.

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: load checkout_url in a WKWebView (iOS) or Android WebView. On iOS 16+ the Apple Pay button renders in-app and pops the native Apple Pay sheet — Apple Pay on the Web is supported in WKWebView but not in SFSafariViewController, so use a WKWebView. Google Pay works in a modern Android WebView, and card is always available. No domain verification is needed on your side.

let webView = WKWebView(frame: .zero, configuration: WKWebViewConfiguration())
webView.load(URLRequest(url: checkoutUrl))

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 as advisory. The embedded page also navigates to /fund/success when payment completes, which you can observe to close your WebView.→ 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