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

# Create a checkout authorization

> Pause a captured processor request until the user approves it with Face ID.

Post the request your browser captured when the agent submitted a placeholder card to a recognized payment processor. Agentcard returns an `approvalUrl` for the user. When they approve, their device sends the real card to the processor and the authorization carries the processor `response` you replay into the paused request.

The SDK makes this call for you. Call it directly only if you run your own interception.

<ParamField body="user" type="string" required>The connected user whose vaulted card pays.</ParamField>
<ParamField body="merchant" type="string" required>Shown to the user on the approval screen. Up to 120 printable characters.</ParamField>
<ParamField body="amount_cents" type="integer">The amount the user approves, in the smallest unit (2306 for \$23.06). Travels with `currency`. On a Stripe PaymentIntent confirm, Agentcard holds the processor to this amount.</ParamField>
<ParamField body="currency" type="string">ISO 4217 code for `amount_cents`.</ParamField>
<ParamField body="amount" type="string">Display string, required only when `amount_cents` and `currency` are not given.</ParamField>
<ParamField body="psp" type="string" required>The payment processor: `stripe`, `shopify`, `square`, `recurly`, `razorpay`, `adyen`, `tranzila`.</ParamField>
<ParamField body="mode" type="string">`token` (default), `cse` (Adyen), or `hosted_form` (Tranzila). Required for `cse` and `hosted_form`.</ParamField>
<ParamField body="card_id" type="string">Which of the user's vaulted cards should pay. Defaults to the most recently added. The user can still pick another.</ParamField>
<ParamField body="request" type="object" required>The captured processor request: `url`, `method`, `headers`, `body`.</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.agentcard.sh/api/v2/checkout/authorizations \
    -H "Authorization: Bearer $ORG_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "user": "usr_8f3k2m",
      "merchant": "shop.example.com",
      "amount_cents": 2306,
      "currency": "usd",
      "psp": "stripe",
      "request": {
        "url": "https://api.stripe.com/v1/tokens",
        "method": "POST",
        "headers": { "content-type": "application/x-www-form-urlencoded" },
        "body": "card[number]=4242424242424242&..."
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "cauth_2q9d1x8f3k2m4t7w",
    "object": "checkout_authorization",
    "status": "awaiting_approval",
    "mode": "token",
    "amount": "$23.06",
    "amount_cents": 2306,
    "currency": "usd",
    "amount_authority": "display_only",
    "amount_verified": null,
    "charged_amount_cents": null,
    "charged_currency": null,
    "replay_attempted": false,
    "approvalUrl": "https://vault.agentcard.sh/authorize?id=cauth_2q9d1x8f3k2m4t7w",
    "expiresAt": "2026-08-27T21:15:00Z"
  }
  ```
</ResponseExample>

**Errors.** `400 mode_required`, `400 mode_mismatch`, `400 currency_required` / `amount_cents_required`, `404 card_not_found`, `409 amount_mismatch` (Stripe intent disagrees with `amount_cents`; carries `expected_cents` and `actual_cents`), `409 intent_not_confirmable`, `502 amount_unverifiable`.

Authorizations expire after 15 minutes without approval. When you fulfill the paused browser request with the approved `response`, add `access-control-allow-origin` echoing the request's `Origin` and `access-control-allow-credentials: true`, or the page rejects it.