> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a checkout authorization

> The authoritative state of one authorization, including the processor response once approved.

**id** `string` *required*

The authorization id.

```bash cURL theme={null}
curl https://api.agentcard.sh/api/v2/checkout/authorizations/cauth_2q9d1x8f3k2m4t7w \
  -H "Authorization: Bearer $ORG_TOKEN"
```

```json 200 theme={null}
{
  "id": "cauth_2q9d1x8f3k2m4t7w",
  "object": "checkout_authorization",
  "status": "approved",
  "mode": "token",
  "psp": "stripe",
  "merchant": "shop.example.com",
  "amount": 2306,
  "currency": "usd",
  "amount_display": "$23.06",
  "amount_authority": "processor",
  "amount_verified": true,
  "charged_amount": 2306,
  "charged_currency": "usd",
  "charged_kind": "captured",
  "replay_attempted": true,
  "settlement": {
    "status": "settled",
    "reason": "processor_succeeded",
    "final": true,
    "processor_reference": "ch_3Qxample",
    "processor_status": "succeeded",
    "processor_error_code": null,
    "settled_amount": 2306,
    "settled_currency": "usd",
    "checked_at": "2026-09-17T20:59:12.000Z",
    "resolved_at": "2026-09-17T20:59:12.000Z",
    "message": "The processor reports this payment succeeded: the charge settled."
  },
  "request_id": "areq_c59cf33fcb3b5b9ae3f853cb",
  "interval": 2,
  "poll_interval_ms": 2000,
  "expires_at": "2026-09-17T21:13:40.000Z",
  "response": { "status": 200, "headers": { "content-type": "application/json" }, "body": "{\"id\":\"tok_…\"}" }
}
```

**status** `string`

`awaiting_approval`, `approved`, `submitted_on_device` (hosted-form processors only; no processor evidence exists), `declined`, or `expired`.

**interval** `integer`

How many seconds to wait between reads while `status` is `awaiting_approval`. `2` for most purchases, and never under `1`.

**poll\_interval\_ms** `integer`

The same wait in milliseconds, exact. `2000` for most purchases; a few processors whose payment form gives up within seconds get a shorter one, down to `100`. Wait `poll_interval_ms`; `interval` rounds it up to whole seconds.

**execution\_mode** `string`

`user_approval` when the user approves in the Vault, `autopilot` when Agentcard pays without asking the user. An `autopilot` authorization carries no `approvalUrl` and names the permission that paid in `grant_id`. See [Enable auto-approval](/vault/app-auto-approval).

**autopilot\_status** `string`

Present once Agentcard tried to pay without asking: `dispatching`, `succeeded`, `declined`, `not_submitted` (the purchase went back to waiting for the user), `outcome_unknown`, or `action_required` (the user's bank asked them to confirm the payment).

**execution\_reason** `string`

`unverified_origin` when the purchase waits for the user because the create carried no `checkout_origin`, with a sentence in `execution_detail`. Absent otherwise.

**outcome** `object | null`

On an auto-approved purchase with `charged_kind: "none"`: what your app reported the merchant charged, refunded, or declined, with the `net_amount`. Null on any other purchase. See [Report a checkout outcome](/api-reference/vault/authorizations-outcome).

**response** `object`

On `approved` in `token` mode: the processor's response to replay into the paused request.

**substitutions** `object`

On `approved` in `cse` mode: the encrypted card fields to write into the paused body, plus `remove` for sibling keys to drop.

**amount** `integer | null`

The amount, in the currency's smallest unit, with `currency` and `amount_display` (the human form, `$23.06`). Null until an authority names one.

**amount\_authority** `string`

Who named the amount: `processor` (the payment request, or the Stripe intent read back), `agent` (the `amount` your agent sent), `page` (the total read off the checkout page), or `none`. The highest known wins, and the processor's is read right before the card is sent.

**amount\_verified** `boolean | null`

Whether what the processor charged matches the approved amount. Null when there was nothing to compare.

**charged\_kind** `string | null`

`captured`, `authorized`, `none`, or null.

**reason** `string`

On `declined`: `user_declined`, `amount_mismatch`, `intent_not_confirmable`, `processor_refused` (with `psp_error_code`), or `processor_declined` (the processor declined an auto-approved purchase).

**processor\_error** `object`

Optional on a Razorpay `processor_refused` result: bounded `reason`, `source`, `step`, `payment_id`, and `order_id` identifiers reported by the processor. Raw response bodies and descriptions are excluded. Older records may not contain these details.

**replay\_attempted** `boolean`

True when a device may already have sent the card. On `expired`, read `settlement` for what the processor says.

**settlement** `object | null`

Whether the charge settled, read back from the processor by Agentcard itself once the authorization finished. `status` is `settled` (the processor reports a succeeded payment; `processor_reference` is its charge or intent, `settled_amount` what it collected), `not_settled` (no charge was made: `reason` is `processor_canceled`, `confirm_failed` with `processor_error_code`, or `not_confirmed`), or `unknown` with a `reason` (`check_pending`, `awaiting_customer_action`, `processor_processing`, `awaiting_merchant_capture`, `processor_unreachable`, `processor_refused_read`, `processor_reply_malformed`, `no_processor_reference`, `processor_reference_incomplete`). `final` is true once Agentcard will not check again; while false, poll or wait for the `checkout_authorization.settled` / `settlement_unconfirmed` webhook. `message` says it in a sentence. Only a Stripe PaymentIntent confirm can be read back; every other request is `unknown` / `no_processor_reference`, final at once. Null while awaiting approval, on a decline, and on an expiry where no device ever held the card.

**Polling.** While `status` is `awaiting_approval`, read the authorization no more often than every `poll_interval_ms` milliseconds. Your first read after the create is always answered. Once `status` is anything else, read as often as you like.

A read that comes sooner is refused, and the authorization does not change. The API answers:

```text theme={null}
HTTP 400
{
  "error": {
    "code": "slow_down",
    "message": "Poll this request no faster than every 2 seconds.",
    "docs": "https://docs.agentcard.sh",
    "interval": 2,
    "request_id": "areq_c59cf33fcb3b5b9ae3f853cb"
  }
}
```

Wait `interval` seconds and read again. The refusal carries no `Retry-After` header, so `interval` is the only wait it names.

The limit belongs to the authorization, not to the server reading it. Two of your servers reading the same authorization share one limit, and so do reads at `/api/v2/checkout/authorizations/{id}` and `/v2/checkout/authorizations/{id}`. The checkout SDK reads at this pace on its own, so do not also read an authorization from your server while the SDK polls it: a refused SDK read ends the checkout with `PaymentOutcomeUnknownError` and the reason `authorization_poll_failed`.

To learn when a purchase finishes without polling, subscribe a [webhook endpoint](/api-reference/webhook-endpoints/create) to [checkout authorization events](/webhooks/checkout-authorizations/overview). When `checkout_authorization.approved` arrives, read this endpoint once for the `response` or `substitutions` your runtime continues with. `checkout_authorization.submitted`, `declined`, and `expired` also finish the authorization, but they carry no processor answer to replay; act on the event itself.

| Code | What it means | What to do next |
| - | - | - |
| `400 slow_down` | You read an authorization awaiting approval sooner than `poll_interval_ms` after the last answered read. | Wait `interval` seconds and read again. |
| `404 not_found` | No authorization with this id belongs to your app. | Check the `id` from the create response. |

An approval is not an order. Confirm the order with the merchant before acting on it. A settled charge is not an order either: it tells you the money moved when the merchant page never showed a receipt, and the merchant's order is still where the purchase is confirmed.

`processor_refused` means the device reported a rejected processor request. A generic code such as Razorpay's `BAD_REQUEST_ERROR` does not establish an issuer decline or prove that nothing was charged. Check the merchant payment status before starting another attempt.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.