Capture, cancel, void, and refund

Part of the Certification guide. Mark your scope on that page before you run these cases. Base payloads and test cards are on the Reference page.

---

8. Capture

Applies to: CIT-AUTHORIZE, MIT-ASYNC-AUTHORIZE, SYNC-MIT. /capture requires the FlexFactor orderId, amount in cents, and currency. idempotencyKey is optional on the API, and this guide requires it on every capture so that a retry after a timeout replays the original response. The amount and currency must match the authorization. A double capture is always prevented on the combination of orderId, amount, and currency.

The response status is the capture outcome: SUCCESS or FAILED. result is always null on this endpoint, and success stays true when the processor declines the capture, so key your logic on status alone. The full capture is proved by CIT-AUTHORIZE-02, MIT-ASYNC-AUTHORIZE-03, or SYNC-MIT-04; the cases below reuse that order or a new authorization from the same flow.

Reference: /capture, /capture HTTP status codes, Appendix A.3.

📘

Partial capture is not available

The capture amount must equal the authorized amount. CAPTURE-05 proves that a lower amount is rejected. To reduce an order before capture, void part of it with /void and capture the remaining amount (Section 9.2). To return part of a charge after capture, use /refund with a partial amount.

---

9. Cancel and void

Two endpoints release an order before capture. /cancel in 9.1 always releases the full order amount. /void in 9.2 releases the full amount or part of it, and its cases apply only when you use that endpoint.

9.1 Cancel

Applies to: CIT-AUTHORIZE, MIT-ASYNC-PURCHASE, MIT-ASYNC-AUTHORIZE, SYNC-MIT. Cancel is a void. It applies to MIT orders in any state other than Completed or Cancelled (Draft, Onhold, Processing, Capturerequired) and to CIT orders in Capturerequired or Onhold. A captured order must be refunded instead. The only accepted body field is the optional idempotencyKey; there is no amount or currency field, and a cancel always applies to the full order amount.

A cancel returns HTTP 200 with the same envelope as /void (success, result, status, statusCode, errors, customProperties, responseCode, responseMessage). Read success; do not key on status. The same body is returned when the order was not in a cancellable state and nothing changed, so a 200 does not by itself prove that the order was cancelled. Mark the order cancelled only after GET /v1/orders/{id} returns status cancelled or order.cancelled arrives.

Reference: /cancel, /cancel response, Workflows §2.6.

📘

Partial cancel is not available

A cancel releases the full order amount. The request body accepts no amount or currency field. To release part of an order, use /void (Section 9.2).

9.2 Void

Applies to: VOID. /void takes an optional amount in cents and an idempotencyKey. An amount equal to the order amount is a full void and cancels the order. A lower amount is a partial void: the order keeps its pre-capture state, its amount drops by the voided value, and you capture the remainder later. Partial voids must be enabled for your sandbox account. Send a new idempotencyKey on every void and reuse it only on retries.

Read success in the response, then confirm the order with GET /v1/orders/{id}. The cases below use a new 9900-cent authorization in Capturerequired state from CIT-AUTHORIZE, MIT-ASYNC-AUTHORIZE, or SYNC-MIT unless the case says otherwise.

Reference: /void, /void HTTP status codes, Appendix A.5.

---

10. Refund

Applies to: CORE. amount is in cents, the same as /capture and /void. The older amountToRefund field (dollars) is deprecated but still accepted; send one or the other, not both. REFUND-09 is required only if your integration sends amountToRefund; otherwise mark it Not applicable. Full refunds are de-duplicated by order ID. Partial refunds are not, so every partial refund must carry an idempotencyKey. FlexFactor refunds the cardholder directly and adjusts merchant settlement, so a refund on a rescued order must call /refund and must not go to the original processor.

The response status is the refund outcome: SUCCESS or FAILED. result is always null on this endpoint. A failed refund normally returns HTTP 200 with status FAILED and success false. A refunded order stays at status completed; GET /v1/orders/{id} reports the refunded total in refundsAmount, in dollars, and order.refunded carries EventData.Amount in cents.

Reference: /refund, /refund HTTP status codes, Workflows §2.7, Appendix A.4.

---