# Capture transaction

Source: <https://docs.gjold.com/v1/transactions/capture>

Capture all or part of what is left of a transaction's authorization, to take the money. You can capture several times, up to the authorized amount in all.

## Request

**POST** `https://api.gjold.com/v1/transactions/{trnid}/capture`

- `{trnid}` is the transaction's `"id"`, from [seq](https://docs.gjold.com/v1/synchronization/seq), or from the answer to [Charge subscriber](https://docs.gjold.com/v1/subscribers/charge#response).

The key needs the `capture` [permission](https://docs.gjold.com/v1/authentication#permissions).

### Headers

- `Authorization`

  **Required.** Your API key, after `Basic` and base64-encoded. See [Authentication](https://docs.gjold.com/v1/authentication).
- `Idempotency-Key`

  A key you make up for this request, and send again with each retry of it, so that the request is done once however often it arrives. Up to the 4 KiB of all headers, and kept for 24 hours. See [Idempotency](https://docs.gjold.com/v1/idempotency).

### Fields

- `total` (amount, **required**)

  How much to capture: more than 0, at most the transaction's `"left"`, and in its currency. We don't check the last two: the acquirer refuses a capture it won't make.
- `index` (integer)

  The transaction's index: how many acts it has now, the length of its `"acts"` as seq last returned it. If an act has been made since, the request fails with `500 transaction database error: index mismatch`, and nothing is done. An `"autocapture"` is an act too, so the first act of yours on such a transaction has index `1`. Left out, it is `0`, as is a value that is not a number. See [Index](https://docs.gjold.com/v1/transactions#index).

### Example

Capture the first item of an order of two, as it ships, on a transaction without acts:

```sh
curl https://api.gjold.com/v1/transactions/378/capture \
    -u {apikey} \
    -H 'Idempotency-Key: 4c1d2b7e9a0f4e83b1c2d3e4f5a6b7c8' \
    -d @capture.json
```

```json
{
    "total": "199.90 DKK",
    "index": 0
}
```

## Response

We answer `200 OK` with an empty object, `{}`, once the act is done: the transaction as it is now comes through [seq](https://docs.gjold.com/v1/synchronization/seq), with the act in its `"acts"` and its `"rev"` one higher.

The capture's act has `"act": "capture"`, and the transaction's `totals.captured` goes up, and its `totals.left` down, by the `"total"`.

### Headers

| HTTP header | Description |
|---|---|
| `Idempotency-Status: OK` | Sent with every answer to a request that has an `Idempotency-Key`, the first and its replays alike. See [Idempotency](https://docs.gjold.com/v1/idempotency#what-we-do-with-it). |

## Errors

Besides the errors that any request can give, which [Errors](https://docs.gjold.com/v1/errors) lists, a capture can fail with:

| Status and message | Description |
|---|---|
| `400 total must be more than 0` | There is no `"total"`, or it is 0. |

and with the errors of every act:

| Status and message | Description |
|---|---|
| `400 invalid json in {where}: {why}` | The body is not a JSON object, or `"total"` is not an amount with a currency, when `{why}` is `invalid amount` or `missing currency`. A field of another type than the table says is not an error, but ignored. See [Invalid JSON](https://docs.gjold.com/v1/errors#invalid-json). |
| `400 invalid json: garbage at offset {n}` | There is more in the body after the JSON object. |
| `500 transaction database error: transaction not found` | The shop has no transaction with that `{trnid}`. |
| `500 transaction database error: index mismatch` | The `"index"` is not the transaction's number of acts: something acted on it since you last read it. Synchronize, look at it again, and decide afresh. |
| `500 transaction database error: transaction in use` | Another act on the transaction is running. Try again in a moment, with a new key. |
| `500 transaction error: transaction is locked` | The transaction is locked, and refuses acts until it is unlocked. See [`"locked"`](https://docs.gjold.com/v1/transactions#the-transaction-object). |
| `500 {acquirer} error: {why}` | The acquirer refused the act, and nothing was done, or did not answer in time, and the act may have gone through. `{acquirer}` names it, as `clearhaus` or `nets`, and `{why}` is its reason, such as `clearhaus error: card expired`. See [Acquirer errors](https://docs.gjold.com/v1/transactions/capture#acquirer-errors). |
| `500 {why}` | We failed. If the act was sent to the acquirer, it may have gone through: synchronize before you try again. |

v1 answers most failures of an act with `500`, whether the request was wrong or we were, so tell them apart by the message, which starts as the table shows, and treat a `500` whose message you don't know as one that may have done the act.

### Acquirer errors

An act is done by your acquirer, and we answer only when it has: in a second or two, as a rule, but after up to 1 minute with Clearhaus, or 10 minutes with Nets, when the acquirer is slow. See [Timeouts](https://docs.gjold.com/notes/retries#timeouts).

When the acquirer refuses an act, nothing is done. Whether it will refuse again, only its message tells: an authorization that has run out, or a card closed since, refuses however often you try. As v1 doesn't check an act's `"total"` or currency itself, a capture over what is left, or a refund over what was captured, is the acquirer's to refuse, with its own message. When it does not answer in time, the act may have gone through without our knowing.

Either way, the answer is stored under the `Idempotency-Key`, so that a retry with the same key gets the same error. Synchronize first, and if the act is not in seq, send it again with a new key.

## Notes

- Capture when you deliver, and within the card scheme's time limit, which is days, not weeks: see the knowledge base's [Authorizations](https://docs.gjold.com/learn/authorizations). A capture after it can be refused, or cost a fee.
- What you never capture is released when the authorization runs out. Once part is captured, the rest can't be voided.
- Compare `"authorized"` with `"attempted"` before you capture: v1 accepts a payment that the bank authorized only in part. See [Partial authorizations](https://docs.gjold.com/v1/transactions#partial-authorizations).
- A link or charge with `"autocapture"` is captured already, with one act, so there is nothing left to capture.