Capture transaction

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, or from the answer to Charge subscriber.

The key needs the capture permission.

Headers

HTTP header	Description
`Authorization`	Required. Your API key, after `Basic` and base64-encoded. See 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.

Fields

Field	Type	Description
`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.

Example

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

curl https://api.gjold.com/v1/transactions/378/capture \
    -u {apikey} \
    -H 'Idempotency-Key: 4c1d2b7e9a0f4e83b1c2d3e4f5a6b7c8' \
    -d @capture.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, 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.

Errors

Besides the errors that any request can give, which 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.
`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"`.
`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.
`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.

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. 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.
A link or charge with "autocapture" is captured already, with one act, so there is nothing left to capture.