Get a funding session

curl --request GET \
  --url https://api.agentcard.sh/api/v2/wallet/fund/{session_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.agentcard.sh/api/v2/wallet/fund/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/wallet/fund/{session_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

GET

api

wallet

fund

{session_id}

Get a funding session

curl --request GET \
  --url https://api.agentcard.sh/api/v2/wallet/fund/{session_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.agentcard.sh/api/v2/wallet/fund/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/wallet/fund/{session_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

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.

Authorizations

Authorization

string

header

required

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 <token>. Tokens live one hour.

Path Parameters

session_id

string

required

Response

The funding session.

object

string

Allowed value: "funding_session"

string

user_id

string

status

enum<string>

Available options:

pending,

processing,

completed,

failed,

expired

amount_cents

integer

currency

string

payment_method

enum<string>

Available options:

apple_pay,

google_pay

checkout_url

string

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

enum<string> | null

Available options:

region_not_supported,

provider_error,

null

completed_at

string<date-time> | null

created_at

string<date-time>

expires_at

string<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

enum<string>

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

Available options:

hosted,

embedded

fee_cents

integer | null

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

enum<string>

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.

Available options:

web

Create a funding session Get the user's wallet

⌘I

Authentication

Connect

Card attachment

Identity verification

Balance funding

Withdrawals

Platform connect

Get a funding session

Status values

Authorizations

Path Parameters

Response

​Status values

Authorizations

Path Parameters

Response

Status values