Authorization & capture

Place a hold on a card and collect money later through one or multiple captures.

An authorization creates a single card-payment transfer. The transferID created for the authorization is used throughout the lifecycle of the payment, including captures, cancellations, and refunds.

Authorization and capture should be used when the final amount or timing of the charge isn't known at checkout. When you authorize a hold, a card-payment transfer is created with an awaiting-capture status. The transfer tracks the hold throughout the capture, cancel, or refund cycle.

The lifecycle of the transfer can capture and cancel in any order until the capturable amount reaches zero, or a final capture is created. After the final capture, any leftover capturable amount is voided automatically.

The top-level amount of an authorization changes over the course of the payment lifecycle:

  • Before the final capture: amount is the authorized amount
  • After the final capture: amount is the cumulative captured amount
If you currently use amount for reporting or reconciliation, use authorization.capturedAmount until there's a final capture on the transfer.

Use cases & actions

Use an authorization and capture flow when the final amount to be charged, or the timing of the charge, is unknown.

  • Charge on fulfillment: Retailer authorizes at checkout and charges when the order ships. Authorize, then one capture with isFinal: true.
  • Split shipments: A three-item order ships in two boxes. One capture per shipment; set isFinal: false until the last capture, then set isFinal: true.
  • Tips & adjustments: Restaurant authorizes the bill, adds the tip later. Capture the adjusted total and pass amountDetails.tip.
  • Holds & deposits: Hotel or rental holds $500, charges $320 at checkout. Capture $320 with isFinal: true; the remaining $180 is released automatically.
  • Out of stock fulfillment: Customer ordered $100, only $75 is available. Cancel $25 of the hold, then capture $75.
  • Order canceled before shipment: Customer cancels before anything is charged. Cancel the transfer with no amount to release the whole hold.

You can authorize, capture, cancel, and refund from the API. If you're using the API, the create transfer endpoint handles both authorizations and captures. Setting captureMethod to manual places a hold you can capture later; setting captureMethod to automatic (or omitting the captureMethod field) charges the card immediately.

Action Endpoint Result
Authorize POST /accounts/{accountID}/transfers with captureMethod.manual Creates a card-payment transfer in awaiting-capture status
Authorize POST /accounts/{accountID}/transfers with captureMethod.automatic Creates a card-payment transfer and charges the card immediately
Capture POST /accounts/{accountID}/transfers/{transferID}/captures Creates a full or partial capture
Cancel (void) POST /accounts/{accountID}/transfers/{transferID}/cancellations Releases some or all of the uncaptured hold
Refund POST /accounts/{accountID}/transfers/{transferID}/refunds Refunds captured funds

Create an authorization

Use the create transfer endpoint to set authorization options. To create a hold and capture funds later, set captureMethod to manual. Setting captureMethod to automatic, or omitting it entirely, will charge the card right away.

 1curl -X POST "https://api.moov.io/accounts/{accountID}/transfers" \
 2  -H "Authorization: Bearer $MOOV_TOKEN" \
 3  -H "X-Moov-Version: v2026.10.00" \
 4  -H "X-Idempotency-Key: $(uuidgen)" \
 5  -H "Content-Type: application/json" \
 6  -d '{
 7    "source": {
 8      "paymentMethodID": "03334567-99ab-cdef-0223-456789abcdec"
 9    },
10    "destination": {
11      "paymentMethodID": "01234567-89ab-cdef-0123-456789abcdef"
12    },
13    "amount": { 
14      "currency": "USD", 
15      "valueDecimal": "100.00" 
16    },
17    "description": "Order #4821",
18    "options": {
19      "cardPayment": {
20        "captureMethod": "manual",
21        "dynamicDescriptor": "WhlBdy *Yoga 11-12",
22        "transactionSource": "first-recurring",
23        "requestExtendedAuthorization": false,
24        "estimatedAuthorization": false
25      }
26    }
27  }'

Moov authorizes the amount and returns an awaiting-capture card-payment transfer:

 1{
 2  "transferID": "d835gf30-4b19-4850-a9b2-c0624c41ecb3",
 3  "transferType": "card-payment",
 4  "status": "awaiting-capture",
 5  "amount": { 
 6    "currency": "USD", 
 7    "valueDecimal": "100.00" 
 8  },
 9  "authorization": {
10    "authorizationID": "twkx2my2tjd2vfda7ynjb4ad3u_auth",
11    "requestedAmount": { 
12      "currency": "USD", 
13      "valueDecimal": "100.00" 
14    },
15    "authorizedAmount": { 
16      "currency": "USD", 
17      "valueDecimal": "100.00" 
18    },
19    "capturedAmount": { 
20      "currency": "USD", 
21      "valueDecimal": "0.00" 
22    },
23    "capturableAmount": { 
24      "currency": "USD", 
25      "valueDecimal": "100.00" 
26    }
27  },
28  "options": {
29    "cardPayment": {
30      "captureMethod": "manual",
31      "dynamicDescriptor": "WhlBdy *Yoga 11-12",
32      "requestExtendedAuthorization": false,
33      "estimatedAuthorization": false
34    }
35  },
36  "processingDetails": {
37    "cardPayment": {
38      "authorizationCode": "A1B2C3",
39      "networkTransactionID": "123456789012345",
40      "retrievalReferenceNumber": "615318762094",
41      "status": "submitted"
42    }
43  },
44  "source": {
45    "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
46    "paymentMethodType": "card-payment",
47    "card": {
48      "brand": "Visa",
49      "lastFourCardNumber": "2000",
50      "cardVerification": {
51        "cvv": "match",
52        "postalCode": "match",
53        "addressLine1": "unavailable"
54      }
55    }
56  },
57  "createdOn": "2026-10-02T15:00:00Z"
58}

Create a capture

Create a capture on the transfer when you're ready to collect. You can capture the full amount at once, or create multiple captures for partial amounts. On the last capture, mark the capture as final.

To capture a partial amount, set an amount and set isFinal to false. On the last capture, set isFinal to true.

 1curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/captures" \
 2  -H "Authorization: Bearer $MOOV_TOKEN" \
 3  -H "X-Moov-Version: v2026.10.00" \
 4  -H "X-Idempotency-Key: $(uuidgen)" \
 5  -H "Content-Type: application/json" \
 6  -d '{
 7    "destinationPaymentMethodID": "01234567-89ab-cdef-0123-456789abcdef",
 8    "amount": { 
 9      "currency": "USD", 
10      "valueDecimal": "60.00" 
11    },
12    "isFinal": false,
13    "description": "Shipment 1 of 2",
14    "lineItems": {
15      "items": [
16        { 
17          "name": "Trail shoes", 
18          "basePrice": { 
19            "currency": "USD", 
20            "valueDecimal": "60.00" 
21          }, 
22          "quantity": 1 
23        }
24      ]
25    },
26    "facilitatorFeeAmount": { 
27      "currency": "USD", 
28      "valueDecimal": "0.60"
29    }
30  }'

To capture the full amount, omit amount and set isFinal to true.

1curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/captures" \
2  -H "Authorization: Bearer $MOOV_TOKEN" \
3  -H "X-Moov-Version: v2026.10.00" \
4  -H "X-Idempotency-Key: $(uuidgen)" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "destinationPaymentMethodID": "01234567-89ab-cdef-0123-456789abcdef",
8    "isFinal": true
9  }'

Reversals, cancellations, & refunds

In some instances, you may need to reverse, cancel, or refund payments. Uncaptured funds can be canceled, but captured funds can only be refunded.

Reverse funds

The reversals endpoint can be used in the following two scenarios:

  1. No capture: The full capturable amount is canceled
  2. One capture, marked final: Cancels or refunds, depending on processing status
curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/reversals" \
  -H "Authorization: Bearer $MOOV_TOKEN" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": {
    "currency": "USD",
    "valueDecimal": "60.00"
  }
}'

Multiple captures and non-final captures are not supported by the reversals endpoint and must be refunded or canceled directly.

Cancel uncaptured funds

A cancellation voids part or all of the hold that has not been captured. You can cancel between captures, or before any capture exists.

  • Partial cancel: Decreases the capturable amount. The authorized amount doesn't change, and the remainder stays available to capture if needed.
  • Full cancel: Voids the entire remaining capturable amount

For a partial cancel, pass an amount, which decreases the capturableAmount. authorizedAmount doesn't change.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/cancellations" \
  -H "Authorization: Bearer $MOOV_TOKEN" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { 
      "currency": "USD", 
      "valueDecimal": "25.00" 
    }
  }'

For a full cancel, omit amount and send an empty object.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/cancellations" \
  -H "Authorization: Bearer $MOOV_TOKEN" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "Content-Type: application/json" \
  -d '{}'

A cancellation cannot return captured funds. Create a refund instead.

Refund captured funds

You can refund the full captured amount or a partial amount.

Use the refund endpoint and pass the associated transferID in the path. To send a full refund, pass an empty object in the request body.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/refunds" \
  -H "Authorization: Bearer $MOOV_TOKEN" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

To refund a specific capture, send the amount and captureID in the request body.

curl -X POST "https://api.moov.io/accounts/{accountID}/transfers/{transferID}/refunds" \
  -H "Authorization: Bearer $MOOV_TOKEN" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { "currency": "USD", "valueDecimal": "10.00" },
    "captureID": "cap_01"
  }'

Webhooks

Subscribe to the following webhook events, which will provide you with relevant updates:

Webhook Description
transfer.updated The transfer status moves to queued, pending, completed, canceled, failed, or reversed
capture.updated The capture status moves to pending, completed, failed, or canceled
cancellation.created Cancellation has been created
cancellation.updated Cancellation status has changed
refund.created Refund has been created
refund.updated Refund status has changed

Best practices

  • Store one ID. The transferID is the handle for the whole payment. Store captureID next to it only if you refund at the capture level.
  • Capture before expiresOn. An expired hold cannot be captured
  • Mark the last capture final. Without isFinal: true, the leftover hold stays on the customer's card until it expires
  • Check authorizedAmount. Issuers can approve less than you requested
  • Reconcile from the authorization object. Before the final capture, the top-level amount shows what was authorized, not what was collected
  • Test in sandbox first with the X-Moov-Version: v2026.10.00 header

FAQ

Can I capture more than the authorized amount?
No. Captures cannot exceed capturableAmount.
What happens to the uncaptured amount after a final capture?
It's voided automatically, and capturableAmount drops to 0.00.
Can each capture have its own fee and line items?
Yes. Pass facilitatorFeeAmount, lineItems, and amountDetails per capture. These fields on the top-level transfer will be aggregated as captures are created.
How do I find all auth and capture transfers?
List transfers with authorizationIDs or transferTypes=card-payment and filter by status=awaiting-capture for open holds.