# Void transaction

Source: <https://docs.gjold.com/v2/transactions/void>

Release a transaction's whole authorization, so that the payer's bank frees the held amount and nothing can be captured. A transaction can be voided only before its first capture.

## Request

**POST** `https://api.gjold.com/v2/{shopid}:trn:{trnid}/void`

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

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

### Headers

- `Authorization`

  **Required.** Your API key, after `Basic` and base64-encoded. See [Authentication](https://docs.gjold.com/v2/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/v2/idempotency).

### Body

A void has no fields, so its body is `{}`. It takes no `"total"`, as it is always for the whole authorization, and no `"index"`, as it can only be the transaction's first act.

### Example

```sh
curl https://api.gjold.com/v2/{shopid}:trn:378/void \
    -u {apikey} \
    -H 'Idempotency-Key: 0b5e8d3c61f24a97c3d4e5f6a7b8c9d0' \
    -d '{}'
```

## 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/v2/synchronization/seq), with the act in its `"acts"` and its `"rev"` one higher.

The void's act has `"act": "void"` and the whole amount as its `"total"`, and is the transaction's only act. Its `totals.voided` is then the whole amount, and its `totals.left` is `0`.

### Headers

| HTTP header | Description |
|---|---|
| `Idempotency-Status: OK` | The answer is a replay: the stored answer to the first request with this `Idempotency-Key`, which this request did not run again. |

## Errors

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

| Status and message | Description |
|---|---|
| `400 request does not accept a total` | The body has a `"total"`. Leave it out. |
| `409 transaction has acts` | The transaction has been captured, or voided already. Refund what was captured instead. |

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 a field is not as the table says. See [Invalid JSON](https://docs.gjold.com/v2/errors#invalid-json). |
| `404 transaction not found` | The shop has no transaction with that `{trnid}`. |
| `409 transaction in use` | Another act on the transaction is running. Try again in a moment, with a new key. |
| `409 transaction is locked` | The transaction is locked, and refuses acts until it is unlocked. See [`"locked"`](https://docs.gjold.com/v2/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. `{why}` is the acquirer's, such as `clearhaus error: card expired`. See [Acquirer errors](https://docs.gjold.com/v2/transactions/void#acquirer-errors). |
| `500 {why}` | We failed. If the act was sent to the acquirer, it may have gone through: synchronize before you try again. |

### 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. 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

- Void an order that is cancelled before you have captured anything. It is better for the payer than a capture and a refund: their bank releases the held amount, most often at once and at most in a day or two, where a refund takes days. See the knowledge base's [Voiding](https://docs.gjold.com/learn/authorizations#voiding).