Authorization & capture
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:
amountis the authorized amount - After the final capture:
amountis the cumulative captured amount
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: falseuntil the last capture, then setisFinal: 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
amountto 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:
- No capture: The full capturable amount is canceled
- 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
transferIDis the handle for the whole payment. StorecaptureIDnext 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
amountshows what was authorized, not what was collected - Test in sandbox first with the
X-Moov-Version: v2026.10.00header
FAQ
What happens to the uncaptured amount after a final capture?
capturableAmount drops to 0.00.Can each capture have its own fee and line items?
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?
authorizationIDs or transferTypes=card-payment and filter by status=awaiting-capture for open holds.