v1

latestOpenAPI 3.1.02026-07-26261466.6 KB

Wallet funding

Create a funding session

Returns an Apple Pay / Google Pay payment link for the amount you specify. Show it in your UI; when the user completes the payment the funds land in their wallet. The link is single-use and expires after 30 minutes. Requires a phone verification fresh within 60 days — see POST /api/v2/wallet/phone/start.

post/api/v2/wallet/fund

Request body

user_idstring required

The connected user's id.

amount_centsinteger required

Amount to fund, in USD cents.

payment_method'apple_pay' | 'google_pay'

google_pay with link_type "embedded" is accepted when the user's rail returns the web checkout style; on web rails embedded is Apple Pay only (422 payment_method_not_supported).

link_type'hosted' | 'embedded'

hosted returns an Agentcard-hosted payment page, safe to relay anywhere (chat, email, QR); the underlying payment order is created only when the user opens it, so unopened hosted sessions cost nothing. embedded creates a REAL payment order immediately and returns the raw single-use Apple Pay link for rendering inside your own in-app webview; it lives about 5 minutes, must never be relayed through chat (link unfurlers consume it), and counts toward the user's per-user payment limits even if never paid, so mint it only when the user initiates payment. Embedded sessions support payment_method apple_pay only (google_pay with embedded is rejected). Sandbox-mode credentials create TEST orders (never charged). Embedded responses carry checkout_style (web | web) — branch your rendering on it.

Response

The funding session, with the payment link to show the user.

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.