# Authorization & capture

> Learn how to use authorization and capture to place holds on cards and capture funds later.

> AI agents: search and read all Moov docs with the docs MCP server at https://docs.moov.io/mcp (no API key). Setup: https://docs.moov.io/guides/developer-tools/mcp-ai/docs-mcp/index.md

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

> **Note:** 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](/api/v2026.10.00/money-movement/transfers/index.md) 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](/api/v2026.10.00/money-movement/transfers/index.md) 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.

```zsh
 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:

```zsh
 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`.

```zsh
 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`.

```zsh
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](/api/money-movement/refunds/cancel/index.md) 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

```zsh
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](/api/money-movement/refunds/create/index.md) or [canceled](/api/money-movement/transfers/cancel/index.md) 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.

```zsh
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.

```zsh
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](#refund-captured-funds) instead.

### Refund captured funds

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

Use the [refund](/api/money-movement/refunds/create/index.md) endpoint and pass the associated `transferID` in the path. To send a full refund, pass an empty object in the request body.

```zsh
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.

```zsh
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](/guides/webhooks/webhook-events/index.md), which will provide you with relevant updates:

| Webhook                                                                | Description                                                                                        |
|------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| [transfer.updated](/guides/webhooks/webhook-events/index.md#transfers)         | The transfer status moves to `queued`, `pending`, `completed`, `canceled`, `failed`, or `reversed` |
| [capture.updated](/guides/webhooks/webhook-events/index.md#captures)           | The capture status moves to `pending`, `completed`, `failed`, or `canceled`                        |
| [cancellation.created](/guides/webhooks/webhook-events/index.md#cancellations) | Cancellation has been created                                                                      |
| [cancellation.updated](/guides/webhooks/webhook-events/index.md#cancellations) | Cancellation status has changed                                                                    |
| [refund.created](/guides/webhooks/webhook-events/index.md#refunds)             | Refund has been created                                                                            |
| [refund.updated](/guides/webhooks/webhook-events/index.md#refunds)             | 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](/api/money-movement/transfers/list/index.md) with `authorizationIDs` or `transferTypes=card-payment` and filter by `status=awaiting-capture` for open holds.

