DocsAuthorizations, Captures & Voids
Manage payment authorization, capture, and void flows
Some payment methods support a two-step flow: first authorize (reserve funds), then capture (collect the funds) or void (release the reservation).
Capture Modes
Set capture_mode on the order to control when funds are captured:
| Mode | Behavior |
|---|---|
manual | You explicitly capture when ready (e.g., after shipping). If you don't capture before the order expires, the authorization is lost and cannot be captured. |
delayed | Funds are automatically captured at the moment the expiration_period elapses. |
{
"currency": "EUR",
"amount": 5000,
"capture_mode": "manual",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
]
}With manual capture, you must capture before the order's expiration period ends. Once expired, the authorization is released and the funds cannot be captured. Set an appropriate expiration_period for your fulfillment timeline.
You can set capture_mode at the order level without specifying transactions. The hosted payment page will then only show payment methods that support the specified capture mode.
Checking Capturable Amounts
Before capturing, you can check how much is available for capture by requesting amount_details:
curl -u YOUR_API_KEY: \
"https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"The response includes an amount_details object:
{
"amount": 5000,
"amount_details": {
"capturable": 5000,
"captured": 0,
"refundable": 0,
"refunded": 0,
"voidable": 5000,
"voided": 0
}
}Order Lines
When using captures and voids by order line, use these types:
| Type | Description |
|---|---|
physical | Physical product |
discount | Discount amount |
shipping_fee | Shipping cost |
sales_tax | Sales tax |
digital | Digital product |
gift_card | Gift card |
store_credit | Store credit |
surcharge | Surcharge |
Capturing Payments
Capture by Order Line
POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines{
"description": "Shipping item #1",
"order_line": {
"merchant_order_line_id": "item-001",
"quantity": 1
}
}Capture by Amount
POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount{
"description": "Partial capture",
"amount": 2500
}Voiding Payments
Void releases the authorized funds back to the customer.
Void by Order Line
POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines{
"description": "Voiding item #2",
"order_line": {
"merchant_order_line_id": "item-002",
"quantity": 1
}
}Void by Amount
POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount{
"description": "Partial void",
"amount": 1500
}Query Parameters
Add query parameters to include additional details in the response:
| Parameter | Description |
|---|---|
?fields[]=order_line_details | Include order line breakdown |
?fields[]=amount_details | Include amount breakdown |
Optimistic Locking
Capture and void endpoints support ETag-based optimistic locking via the if-match header. This prevents race conditions when multiple systems attempt to capture the same transaction.
curl -X POST https://api.costplus.online/v1/orders/{id}/transactions/{tid}/captures/amount \
-u {api_key}: \
-H "Content-Type: application/json" \
-H "if-match: \"etag-value\"" \
-d '{"description": "Capture", "amount": 2500}'If the ETag doesn't match (the order was modified since you last fetched it), you'll receive a 412 Precondition Failed response.
Cost+ supports one capture per authorization, and voids can only be processed before any capture. Plan your capture strategy accordingly.
Related Endpoints
- Capture by Amount — capture a specific amount from an authorized order
- Capture by Order Line — capture specific order lines
- Void by Amount — void a specific amount from an authorized order
- Void by Order Line — void specific order lines