Poll a top-up request

Poll an owned Checkout or Hosted Link payment request. Agent tokens can poll only their own request. Checkout polling validates the live session, metadata, amount and authoritative PaymentIntent before crediting once; unpaid and expired sessions do not mint. Hosted Link approval and payment settlement remain separate states.

GET/v1/payments/topups/{id}

Authorization

AuthorizationBearer token (JWT) · headerrequired

Clerk human owner session JWT; iss must equal the configured Clerk issuer and the identity must be a human (not agent) owner with a verified email.

AuthorizationBearer token (JWT) · headerrequired

Verified AgentID agent JWT (iss https://auth.agentid.com) or an agentsub OAuth access token (typ at+jwt, iss https://api.agentsub.dev, scope agentsub:agent). The agent's human owner must exist in Clerk with the same verified email.

AuthorizationOAuth2 access token · headerrequired

Scopes:agentsub:owner

Path parameters

idstringrequired

Responses

200

Top-up state (pending / approved / settled / expired)

idstring

agentIdstring

amountUsdCentsinteger

statusstring

kindstring

Allowed:checkoutlink

approvalUrlstring<uri>

checkoutUrlstring<uri>

nextActionobject

Show properties

resolutionstring

actionUrlstring<uri>

intentIdstring

503

payment_unavailable

codestringrequired

Allowed:owner_requiredagent_mismatchidempotency_requiredinvalid_inputstripe_signature_requiredpayment_unavailable

statusintegerrequired

Request

curl -X GET 'https://api.agentsub.dev/v1/payments/topups/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response = await fetch("https://api.agentsub.dev/v1/payments/topups/string", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://api.agentsub.dev/v1/payments/topups/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "id": "string",
  "agentId": "string",
  "amountUsdCents": 0,
  "status": "string",
  "kind": "checkout",
  "approvalUrl": "http://example.com",
  "checkoutUrl": "http://example.com",
  "nextAction": {
    "resolution": "string",
    "actionUrl": "http://example.com"
  },
  "intentId": "string"
}

{
  "code": "owner_required",
  "status": 0
}