• Request
• Response
• Payload examples
• Void by external order ID

Use /void to release all or part of an order before it is captured. A void never moves funds: it stops or reduces an order that is still pending, rather than reversing a settled charge. To return money after capture, use /refund instead.

You can void the same orders that /cancel accepts:

• MIT orders in draft, onhold, processing, or capturerequired status — any status that is not completed or cancelled
• CIT orders in capturerequired or onhold status

❗️

Prerequisites to invoke this API:

• Authenticate and send the bearer token for this call.
• Partial voids must be enabled for your account. Contact your FlexFactor Solutions engineer before you send a void below the order amount.

📘

Idempotency

Send an idempotencyKey (a GUID, in the JSON body) on every partial void and reuse it on retries. Several partial voids against one order are legitimate, so the order ID alone cannot tell a retry apart from an intentional second void. Within the 24-hour replay window, a retry with the same key returns the original response instead of voiding a second time, and a reused key carrying a different payload is rejected as a 409 conflict. See the Idempotency reference (§3.4) for the full behavior.

Request

Details

Body

Full and partial voids

Full and partial voids use the same request. amount is the amount to remove from the order, in cents; it is not the new order total.

• There is no currency field. The void is applied in the currency of the original order.
• Full void. An amount equal to the order amount cancels the whole order. The order moves to cancelled, and the order.cancelled webhook fires when the status changed and you subscribe to the event.
• Partial void. An amount lower than the order amount reduces the order and keeps the remainder open. The order stays in its pre-capture state, and order.cancelled does not fire. GET /v1/orders/{id} returns the reduced amount in amount and formattedAmount, in dollars. When you capture the order later, send the remaining amount to /capture.
• You can issue several partial voids against one order. Each void is applied to the amount that remains after the previous one, so two 2000-cent voids take a 10000-cent order to 8000 cents and then to 6000 cents.

For example, if you void 4000 cents from a 9900-cent order, the order amount becomes $59.00 and nothing is captured. When you capture the order, send amount 5900 to /capture.

Try it right now:

• Check out the /void Reference.

Response

The void response uses the common FlexFactor envelope. Read success to decide whether the void succeeded, then confirm the order with GET /v1/orders/{id} before you update your own records. The envelope is defined in Workflows §3.5.

HTTP status codes

❗️

Confirm the order after every void

Check success on every 200; do not treat the HTTP code alone as the outcome. After a full void, GET /v1/orders/{id} returns status cancelled. After a partial void, it returns the reduced amount and the order status is unchanged.

❕

Updating the status order

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

Payload examples

Request

curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/orders/{id}/void \ //insert the orderId returned by the response to /evaluate
     --header 'Authorization: Bearer abc123def456' \ //replace with bearer returned by /oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 9900, //in cents — equal to the order amount
  "idempotencyKey": "{generate_a_GUID_and_reuse_it_on_retries}"
}

curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/orders/{id}/void \ //insert the orderId returned by the response to /evaluate
     --header 'Authorization: Bearer abc123def456' \ //replace with bearer returned by /oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 4000, //in cents — lower than the order amount
  "idempotencyKey": "{generate_a_GUID_and_reuse_it_on_retries}"
}

Response

{
   "success": true,
   "status": null,
   "result": null,
   "responseCode": null,
   "responseMessage": null,
   "statusCode": null,
   "errors": [],
   "customProperties": {}
}

{
   "success": false,
   "status": null,
   "result": null,
   "responseCode": "{processor response code}",
   "responseMessage": "{processor response message}",
   "statusCode": null,
   "errors": [
      { "item1": "{failure reason}", "item2": "{error key}", "item3": "{error code}", "item4": true }
   ],
   "customProperties": {}
}

Void by external order ID

external-void identifies the order by your own external order ID (the orderId you sent to /evaluate) instead of the FlexFactor order ID returned in the response. It works exactly like /void: the same eligible orders, the same body, the same full and partial void behavior, and the same response. Use it when you do not store the FlexFactor order ID, or when you never received it, for example because the /evaluate response timed out.

Request

Details

Body

Same as /void — see Body above. Send an idempotencyKey on every partial void and reuse it on retries.

Response

Same as /void, including the HTTP status codes — see Response above. A 404 means no order matches the external order ID for your account.

Payload examples

Request

curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/orders/{external-order-id}/external-void \ //insert the orderId you sent to /evaluate
     --header 'Authorization: Bearer abc123def456' \ //replace with bearer returned by /oauth2
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 4000, //in cents — lower than the order amount
  "idempotencyKey": "{generate_a_GUID_and_reuse_it_on_retries}"
}

Try it right now:

• Check out the /external-void Reference.