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`.
`metadata`	object	No	Key-value pairs for your reference (e.g., order ID).

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",
  "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_error`	502	Processor declined or failed
`connector_timeout`	504	Processor did not respond