> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimepayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorize and Capture

> Place a hold on a card now and collect the money later.

## When to use it

A normal card charge collects the money right away. Authorize and capture splits that into two steps:

1. **Authorize** places a hold on the cardholder's available credit. No money moves.
2. **Capture** collects the money, up to the amount you authorized.

Use it when the final amount isn't known yet, or when you shouldn't take payment until something happens first, such as an order shipping or a service being completed.

<Note>
  Authorize and capture works with credit cards only. The token needs the `transaction:authorize-capture` ability. Releasing a hold uses the void endpoint, which is gated separately by `transaction:charge-card-token`, so give the token both if you'll ever need to release holds. See [Authentication](/guides/authentication#token-abilities).
</Note>

## Step 1: Authorize

Send the amount and the card. You can supply the card in one of two ways:

* **A token** from [Tokenize a Credit Card](/api-reference/transaction-management/tokenize-a-credit-card). No PCI paperwork needed, because no card number is sent.
* **Raw card details**: `card_number`, `expiration_date` (mm/YYYY), `cardholder_name`, and `billing_address.zip`. This requires PCI compliance, meaning an Attestation of Compliance on file with Dime Payments. Without one, the request is refused with `403 Merchant is not PCI Compliant`.

Identify the customer with either `phone` (e.164 format, which creates or matches a customer) or `customer_uuid`.

```bash theme={null}
curl --request POST \
  --url https://app.dimepayments.com/api/transaction/authorize \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "sid": 1234567,
      "amount": 100.50,
      "token": "abc123def456",
      "phone": "+17701234567",
      "memo": "order 1234"
    }
  }'
```

A successful authorization returns `transaction_status: Pending` and `status_text: APPROVAL`. Save the `transaction_number` from the response. It's your handle on the authorization for everything that follows.

If the card is declined, you'll get a `400` with `status_code: 05` and `status_text: DECLINE`, and nothing is held.

## Step 2: Capture

Pass the `transaction_number` from the authorization as `data.transaction_id`:

```bash theme={null}
curl --request POST \
  --url https://app.dimepayments.com/api/transaction/capture \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "sid": 1234567,
      "transaction_id": 1234567890,
      "amount": 87.25
    }
  }'
```

Leave out `amount` to capture the full authorized amount, or send a smaller amount to capture part of it.

<Warning>
  **An authorization can only be captured once.** A partial capture settles that amount and releases the rest back to the cardholder. A second capture for the balance is refused with `Transaction is not an open authorization.` If you need to collect in more than one installment, such as a split shipment, authorize each installment separately.
</Warning>

Once captured, the payment behaves like any other card payment and can be refunded or voided.

## Releasing a hold without charging

If the sale falls through, don't capture. Void the authorization instead to release the hold right away:

```bash theme={null}
curl --request PATCH \
  --url https://app.dimepayments.com/api/transaction/void \
  --header 'Authorization: Bearer your-api-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "sid": 1234567,
      "transaction_type": "CC",
      "transaction_id": "1234567890"
    }
  }'
```

`transaction_type` must be `CC`.

## Timing

Capture promptly, ideally within 24 hours. An authorization that is never captured is released by the card issuer on its own schedule, and once it expires it can no longer be captured. If that happens, authorize again.

If you authorized with a token and the token has expired, the request fails with `422 Token expired. Please retokenize, or provide the card details.`

## Errors

| Status | Message | What it means |
| - | - | - |
| `400` | `DECLINE` (in `status_text`) | The card was declined on authorization |
| `400` | `Transaction is not an open authorization.` | Already captured, voided, or expired |
| `400` | `Amount cannot be greater than the authorized amount` | Capture amount exceeds the hold |
| `400` | `No transaction found.` | The `transaction_id` doesn't match an authorization for this merchant |
| `400` | `Error processing capture` | The processor couldn't complete the capture |
| `403` | `Merchant is not PCI Compliant` | Raw card details sent without an AoC on file. Use a token instead |
| `422` | `Token expired. Please retokenize, or provide the card details.` | Tokenize the card again |

See [Response Codes](/guides/response-codes) for permission and merchant errors common to every endpoint.

## Next steps

* [Webhooks](/guides/webhooks#credit-card): `Credit Card Authorize`, `Credit Card Capture`, and `Credit Card Void` tell you when a hold is placed, collected, or released
* [API Reference](/api-reference): full request and response fields


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.