Authorize a Payment

POST /v1/payments/authorize

Authorizes a payment without capturing funds. Use this when you want to place a hold on the card and capture later (e.g., after shipping an order).

Request Parameters

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in cents (e.g., 5000 = $50.00). Must be positive.
`currency`	string	No	Three-letter currency code. Defaults to `usd`.
`gateway_token`	string	Yes	Token from tokenization (e.g., `tok_test_...`).
`capture_method`	string	No	Set to `manual` for authorize-then-capture. Defaults to `manual`.
`connector_account`	string	No	Short_id (`^ca_[a-z0-9]{10}$`) of the connector account that settles the charge. Equivalent to the `X-Connector-Account` header (body wins). Omit to use the merchant’s default for the routed connector.
`metadata`	object	No	Key-value pairs for your reference (e.g., order ID).

connector_account is required for merchants with more than one active account per (connector, mode, key_kind) triple. Single-account merchants can omit it — the default account is picked automatically.

Examples

Response


{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchant_id": "m1234567-89ab-cdef-0123-456789abcdef",
  "amount": 5000,
  "currency": "usd",
  "status": "authorized",
  "capture_method": "manual",
  "gateway_token": "tok_test_aBcDeFgHiJkLmNoPqRsTuVwX",
  "connector_id": "stripe",
  "connector_account_id": "aa0e8400-e29b-41d4-a716-446655440aaa",
  "connector_account_short_id": "ca_abc123def4",
  "test_mode": true,
  "metadata": {"order_id": "ord_123"},
  "created_at": "2026-03-18T12:00:00Z",
  "updated_at": "2026-03-18T12:00:00Z"
}

Status Lifecycle

After authorization, the PaymentIntent follows this lifecycle:


authorized --> succeeded (via capture)
authorized --> canceled (via void)
authorized --> failed (connector decline)

Error Cases

Error Code	HTTP Status	Cause
`invalid_param`	400	Missing or invalid amount, currency, or token
`missing_idempotency_key`	400	No Idempotency-Key header
`authentication_required`	401	No API key provided
`invalid_api_key`	401	Key revoked or invalid
`connector_account_required`	400	Merchant has no resolvable default connector account and caller did not specify one. See Connector Accounts.
`connector_account_not_found`	404	`connector_account` short_id does not exist or belongs to another merchant.
`connector_account_inactive`	400	Specified `connector_account` is soft-deleted (`is_active=false`).
`connector_account_ambiguous`	400	Body `connector_account` and `X-Connector-Account` header disagree.
`connector_error`	502	Processor declined or failed
`connector_timeout`	504	Processor did not respond