❗️
Prerequisites to invoke this API:

Authenticate and send the bearer token for this call.

Capture must be called within 5 minutes of the authorize response by default — this applies to all authorize flows. If no capture arrives within that window, the order expires: its status becomes cancelled and the order.expired webhook fires. The window is measured from the order's last update and can be set per merchant.

📘
Idempotency
idempotencyKey is optional on /capture, and we recommend sending one on every request. A double capture is always prevented on (orderId, amount, currency), with or without a key. When you send a key, a retry with the same key replays the original response within 24 hours, and the same key with a different payload returns 409. A key that is not a GUID returns 400. See the Idempotency reference (§3.4).

Workflow

According to your configuration, a call to /evaluate or /orders can return the status CAPTURE REQUIRED.

In that scenario, you will need to invoke /capture, and then update the definitive status with /orders.

Request

Details


HTTP Method	POST
Endpoint * Sandbox	`https://api-sandbox.flexfactor.io/v1/capture`
Endpoint * Production	https://api.flexfactor.io/v1/capture
Authentication	Bearer Token

Body

Property Name	Type	Required	Optimization Rank	Notes
`idempotencyKey`	Guid	Optional, recommended	—	Generate a GUID and reuse it on retries. A double capture is always prevented on `(orderId, amount, currency)`; the key also replays the original response within 24 hours and returns `409` when reused with a different payload. A value that is not a GUID returns `400`. See Idempotency.
`orderId`	Guid	Required	Required	The FlexFactor `orderId` returned by /evaluate. (The response also includes `orderSessionKey`; `orderId` is preferred.)
`amount`	int	Required	Required	The amount to capture from the order. In cents
`currency`	string	Required	Required	The ISO 4217 currency code for the transaction.

Response

After receiving a response from /capture, you need to update this order in your CRM with the corresponding status.

The response uses the common FlexFactor envelope. status is the capture outcome: SUCCESS or FAILED. result is never populated on this endpoint, and success stays true when the processor declines the capture, so key your logic on status alone. HTTP 200 with status: FAILED means the funds were not captured. The envelope and the transaction state model are defined in Workflows §3.5.


Status Code	200
Response Body	Envelope with `status` = `SUCCESS` \| `FAILED` (capture outcome); `result` is always `null`


`result`	string	Always `null` on this endpoint. Do not use it.
`status`	string	Capture outcome: `SUCCESS` \| `FAILED`. Key your logic on this field.
`success`	boolean	`true` when `errors` is empty. Stays `true` on a processor capture failure — do not use it to judge the capture.
`statusCode`	string	Always `null` on this endpoint. It is not the HTTP status code.
`errors`	array of objects	Error details; empty when the capture succeeded. Each item is serialized positionally: `item1` message, `item2` key, `item3` error code, `item4` friendly flag (boolean).
`customProperties`	object	Additional custom properties for the API request Optional

HTTP status codes

Situation	HTTP	Body
Capture succeeded	`200`	`status: SUCCESS`, `success: true`
Processor did not capture the funds	`200`	`status: FAILED`; `success` remains `true`
Capture not enabled on the account, order not in `capturerequired`, `amount` / `currency` do not match the order, or `idempotencyKey` is not a GUID	`400`	Validation problem details — see Error Handling
Invalid or expired bearer token	`401`	—
No order matches `orderId`, or it belongs to another merchant	`404`	Problem details
Same `idempotencyKey` reused with a different body, or the first request is still running	`409`	Problem details — see Idempotency §3.4
Earlier attempt with the same key failed with an unknown outcome	`500`	Problem details
Unexpected error during the capture	`500`	Plain text `Capture call failed`
Duplicate-request check temporarily unavailable	`503`	Problem details, with a `Retry-After` header; safe to retry

Payload examples

Request

curl --request POST \
    --url https://api-sandbox.flexfactor.io/v1/capture \
		--header 'Authorization: Bearer {bearer_token_returned_by_oauth2}' \	//replace with bearer returned by /oauth2
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '
{
	"idempotencyKey": "{generate_a_GUID_and_reuse_it_on_retries}",
  "orderId": "{same_orderId_returned_by_/evaluate_for_that_order}",
  "amount": 10000,
  "currency": "USD"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "result": null,
   "status": "SUCCESS | FAILED",
   "success": true,
   "statusCode": null,
   "errors": [],
   "customProperties": {}
}