Manual capture & partial refunds

Every card payment intent chooses a capture method at creation. With capture_method: "automatic" (the default), a successful authorize immediately captures the full amount — this is what the Quickstart walks through. With capture_method: "manual", the authorize step only places a hold: funds aren’t captured until you separately call commit, and you choose the amount at that point.

This is the standard pattern for orders that finalize after payment — shipping-on-fulfillment, tabs that close later, or authorization holds you want to release without ever charging.

The manual-capture lifecycle

1. Create the intent with capture_method: "manual".

   Create a manual-capture intent

   curl https://api.paygasus.com/payments/card \
     -H "Authorization: Bearer sk_test_…" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 5000,
       "currency": "USD",
       "capture_method": "manual",
       "description": "order #4471"
     }'

2. Authorize with the encrypted card block, exactly as in the Quickstart. The intent moves to authorized — the issuer has placed a hold, but no funds have moved yet:

   200 OK — authorized, not captured

   {
     "id": "pi_card_9Z3K01ARZ3NDEKTSV4RRFFQ69G5FAV",
     "amount": 5000,
     "amount_captured": 0,
     "amount_refunded": 0,
     "currency": "USD",
     "status": "authorized",
     "capture_method": "manual",
     "payment_method": { "brand": "visa", "last4": "0019" },
     "created": 1746500000,
     "updated": 1746500041,
     "livemode": false
   }

3. Commit the amount you actually want to capture. amount is required on commit — it does not have to equal the original authorized amount. Capture less than you authorized (e.g. the order shipped partially) and the remainder is simply never captured; you cannot commit more than the authorized amount.

   Commit (capture) the intent

   curl -X POST https://api.paygasus.com/payments/card/pi_card_9Z3K01ARZ3NDEKTSV4RRFFQ69G5FAV/commit \
     -H "Authorization: Bearer sk_test_…" \
     -H "Content-Type: application/json" \
     -d '{ "amount": 4500 }'

   200 OK — committed

   {
     "id": "pi_card_9Z3K01ARZ3NDEKTSV4RRFFQ69G5FAV",
     "amount": 5000,
     "amount_captured": 4500,
     "amount_refunded": 0,
     "currency": "USD",
     "status": "committed",
     "capture_method": "manual",
     "payment_method": { "brand": "visa", "last4": "0019" },
     "processor_ref": "ch_0k2f8a91b3",
     "created": 1746500000,
     "updated": 1746500071,
     "livemode": false
   }

Automatic-capture intents skip commit entirely

commit only applies to intents that are authorized — which only capture_method: "manual" intents rest in. An automatic intent captures during authorize and moves straight to committed; calling commit on it returns a 409.

Voiding instead of capturing

If you decide not to capture at all — the order was cancelled before fulfillment — call cancel on the authorized intent instead of commit. Cancel releases the hold same-day, before settlement; once an intent is committed, use refund instead (see below).

Cancel an authorized (uncaptured) intent

curl -X POST https://api.paygasus.com/payments/card/pi_card_9Z3K01ARZ3NDEKTSV4RRFFQ69G5FAV/cancel \
  -H "Authorization: Bearer sk_test_…"

Partial and multiple refunds

Refunds work against any committed intent, in whole or in part, and you can call refund more than once. There is no separate refund object and no refund-listing endpoint — the intent itself is the source of truth: every refund call adds to the running amount_refunded, and the amount you request must not push that total past amount_captured.

Refund part of a committed intent

curl -X POST https://api.paygasus.com/payments/card/pi_card_9Z3K01ARZ3NDEKTSV4RRFFQ69G5FAV/refund \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1500 }'

200 OK — running refund total

{
  "id": "pi_card_9Z3K01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "amount": 5000,
  "amount_captured": 4500,
  "amount_refunded": 1500,
  "status": "committed",
  "...": "..."
}

Call refund again later for the remaining 3000 — each call is checked against amount_captured − amount_refunded at that moment, so you can issue as many partial refunds as you need up to the full captured amount.

Cancel vs. refund — same-day vs. later

Cancel only works on an unsettled, uncaptured (authorized) intent. Once an intent is committed, cancel is no longer valid — issue a refund instead, partial or full. Attempting either operation on the wrong side of that line returns a 409 with the standard error envelope.

Next steps

• Review the Quickstart for the default automatic-capture flow this guide builds on.
• See Errors for the 409 conflict shape returned by an invalid commit/cancel/refund call.
• Browse the full API reference for commit, cancel, and refund request/response schemas.