Void transaction
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://{trnid}is the transaction's"id", from seq, or from the answer to Charge subscriber.
The key needs the void permission.
Headers
| HTTP header | Description |
|---|---|
Authorization |
Required. Your API key, after |
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. |
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
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, 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 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. |
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". |
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. |
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.
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.