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:
- You want to charge only after delivery.
- You may capture less than you authorized (out-of-stock items, adjusted orders).
- 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"
}
}
}'const res = await fetch("https://sandbox.cardencer.com/payments", {
method: "POST",
headers: { "api-key": process.env.CARDENCER_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
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" },
},
}),
});
const payment = await res.json(); // payment.status === "requires_capture"payment = requests.post(
"https://sandbox.cardencer.com/payments",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
json={
"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"}},
},
).json() # payment["status"] == "requires_capture"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 }'const res = await fetch(`https://sandbox.cardencer.com/payments/${paymentId}/capture`, {
method: "POST",
headers: { "api-key": process.env.CARDENCER_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ amount_to_capture: 6540 }),
});requests.post(
f"https://sandbox.cardencer.com/payments/{payment_id}/capture",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
json={"amount_to_capture": 6540},
)Rules:
amount_to_capturemust be greater than zero and no greater thanamount_capturable.- For
manual_multiple,amount_to_captureis required on every call. - The endpoint accepts payments in
requires_capture,partially_captured_and_capturableorpartially_authorized_and_requires_capture, andprocessingformanual_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.