Capture a Payment

POST /v1/payments/capture

Captures a previously authorized payment to settle the funds. Only PaymentIntents with status authorized and capture_method: manual can be captured.

Request Parameters

Parameter	Type	Required	Description
`payment_intent_id`	string (UUID)	Yes	The ID of the authorized PaymentIntent to capture.
`connector_account`	string	No	Must equal the connector account that settled the originating authorize. See the override-forbidden note below.

Capture inherits the authorize’s connector account. The gateway captures through the same connector_account that authorized the charge — regardless of the merchant’s current default. Passing a different connector_account (body or X-Connector-Account header) returns 400 connector_account_override_forbidden. This is a hard PCI-audit invariant; do not override.

Examples

Response


{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchant_id": "m1234567-89ab-cdef-0123-456789abcdef",
  "amount": 5000,
  "currency": "usd",
  "status": "succeeded",
  "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,
  "created_at": "2026-03-18T12:00:00Z",
  "updated_at": "2026-03-18T12:00:01Z",
  "captured_at": "2026-03-18T12:00:01Z"
}

Error — override forbidden

Capture refuses any connector_account that differs from the one that authorized the PaymentIntent. If the originating authorize used ca_abc123def4 but capture specifies ca_ghi789jkl0:


POST /v1/payments/capture
Authorization: Bearer sk_test_your_key_here
Idempotency-Key: cap_01HK...
Content-Type: application/json
 
{
  "payment_intent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "connector_account": "ca_ghi789jkl0"
}

Response — 400 Bad Request:


{
  "error": {
    "type": "invalid_request_error",
    "code": "connector_account_override_forbidden",
    "message": "Capture must use the same connector_account as the originating authorization.",
    "param": "connector_account",
    "request_id": "req_01HK9ABCD3F7X1YZ2Q3W4E5R6T"
  }
}

Fix: drop the connector_account field on capture — the gateway inherits it from the authorize automatically.

When to Use

Use the authorize-then-capture pattern when:

You need to verify card validity before fulfilling an order.
You ship physical goods and want to capture only after shipment.
You need time to review orders for fraud.

Timing: Authorizations typically expire after 7 days (varies by processor). Capture before the authorization expires to avoid decline.

Error Cases

Error Code	HTTP Status	Cause
`invalid_param`	400	Missing payment_intent_id
`payment_intent_not_found`	404	PaymentIntent does not exist
`invalid_state_transition`	409	PaymentIntent is not in `authorized` status
`connector_account_override_forbidden`	400	Capture supplied a different `connector_account` than the originating authorize. See example above.
`connector_account_inactive`	400	Originating connector account has since been soft-deleted.
`originating_account_unavailable`	409	Originating connector account has been hard-deleted; capture cannot route through it.