v1

latestOpenAPI 3.1.02026-07-26261466.6 KB

Wallet funding

Get a funding session

Poll a funding session until it is completed — the payment status is refreshed from the provider on every read.

get/api/v2/wallet/fund/{session_id}

Path parameters

session_idstring required

Response

The funding session.

object'funding_session'

idstring

user_idstring

status'pending' | 'processing' | 'completed' | 'failed' | 'expired'

amount_centsinteger

currencystring

payment_method'apple_pay' | 'google_pay'

checkout_urlstring

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'region_not_supported' | 'provider_error' | 'null' nullable

completed_atstring date-time nullable

created_atstring date-time

expires_atstring date-time

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'hosted' | 'embedded'

Which kind of checkout_url this session carries. Returned only on the create response; the poll endpoint does not include it.

fee_centsinteger nullable

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).

checkout_style'web'

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.