Authorizations, Captures & Voids

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)
`delayed`	Auto-capture after the `expiration_period` elapses

POST /v1/orders/ (manual capture)

{
  "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"
    }
  ]
}

[!NOTE] delayed capture mode requires expiration_period to be set. The funds will be captured automatically when the expiration period ends.

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

Request body

{
  "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

Request body

{
  "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

Request body

{
  "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

Request body

{
  "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.

Capture with optimistic locking

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.

[!WARNING] Rapyd limitation: Rapyd supports only one capture per authorization, and voids can only be processed before any capture. Plan your capture strategy accordingly.

On this page