Skip to content

Manual capture

Place a hold on your customer's card and capture the funds later, fully or partially, in one capture or several.

With manual capture, the authorization places a hold on the customer's funds and you capture later, once you have shipped the goods or delivered the service. This is also called auth and capture, or the two-step flow.

Use it when:

  1. You want to charge only after delivery.
  2. You may capture less than you authorized (out-of-stock items, adjusted orders).
  3. The customer should see a charge that matches what they received.

Choose a capture method before you authorize#

capture_method is set when you create the payment and cannot change after authorization.

capture_method What it does
automatic Default. Authorization and capture together. The capture endpoint rejects these payments.
manual One capture: the whole hold or part of it, once.
manual_multiple Several captures against one authorization, up to the authorized amount.

Pick manual_multiple if you might ship in more than one parcel. With manual, whatever you do not take in the single capture is no longer capturable.

1. Create the payment with deferred capture#

Set "capture_method": "manual". Here the payment is also confirmed with a test card from the server; with the checkout SDK, omit confirm and payment_method_data and let the SDK confirm.

curl https://sandbox.cardencer.com/payments \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 6540,
    "currency": "EUR",
    "confirm": true,
    "capture_method": "manual",
    "description": "Order 58212",
    "return_url": "https://example.com/checkout/complete",
    "payment_method": "card",
    "payment_method_type": "credit",
    "payment_method_data": {
      "card": {
        "card_number": "4242424242424242",
        "card_exp_month": "12",
        "card_exp_year": "2030",
        "card_holder_name": "Test Customer",
        "card_cvc": "123"
      }
    }
  }'

On a successful authorization the payment is requires_capture and amount_capturable equals the authorized amount. Tell the customer their funds are held and will be charged on shipment.

2. Capture#

Call POST /payments/{payment_id}/capture. Omit amount_to_capture to capture everything capturable, or pass a smaller amount.

curl https://sandbox.cardencer.com/payments/pay_mbabizu24mvu3mela5njyhpit4/capture \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_to_capture": 6540 }'

Rules:

  • amount_to_capture must be greater than zero and no greater than amount_capturable.
  • For manual_multiple, amount_to_capture is required on every call.
  • The endpoint accepts payments in requires_capture, partially_captured_and_capturable or partially_authorized_and_requires_capture, and processing for manual_multiple.

3. Or cancel the authorization#

If the order will not ship, release the hold instead of capturing:

curl https://sandbox.cardencer.com/payments/pay_mbabizu24mvu3mela5njyhpit4/cancel \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cancellation_reason": "out_of_stock" }'

The payment moves to cancelled.

What happens to the amount you did not capture#

manual: one capture ends the payment. Capture the full amount and it is succeeded. Capture less and it is partially_captured, amount_capturable drops to 0 and the rest of the hold can no longer be captured. When the remaining hold disappears from the customer's statement depends on their issuer.

manual_multiple: each capture that does not exhaust the hold leaves the payment partially_captured_and_capturable, with the remainder still capturable. When the captures add up to the authorized amount, the payment is succeeded.

amount_captured tracks what you actually took and is the ceiling for refunds. A payment is refundable only once it is succeeded or partially_captured.

Statuses#

Status Meaning
requires_capture Authorized. The full amount is capturable.
succeeded Everything capturable has been captured. Terminal.
partially_captured Part captured, nothing left to capture. Terminal. Refundable up to amount_captured.
partially_captured_and_capturable Part captured, remainder still capturable. Not refundable yet.
processing A manual_multiple capture is in flight.
partially_authorized_and_requires_capture The issuer authorized less than requested. Capture against the smaller amount.
cancelled Cancelled before any capture.

Authorizations do not last forever. Most card authorizations expire after about 7 days, depending on the card scheme and issuer. Capture as soon as you ship.