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://{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 |
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. |
index |
integer, required | The transaction's index: how many acts it has now, the length of its
|
history |
array of objects | What the act covers, item by item, for your records and the dashboard,
each as |
Example
Capture the first item of an order of two, as it ships:
curl https://api.gjold.com/v2/{shopid}:trn:378/capture \
-u {apikey} \
-H 'Idempotency-Key: 4c1d2b7e9a0f4e83b1c2d3e4f5a6b7c8' \
-d @capture.json{
"total": "199.90 DKK",
"index": 0,
"history": [
{"item": 0, "quantity": 2, "total": "199.90 DKK"}
]
}
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 |
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 capture can fail with:
| Status and message | Description |
|---|---|
400 total must be more than 0 |
There is no "total", or it is 0. |
400 total exceeds left |
The "total" is more than the transaction's "left": more than is left to capture, or anything at all of a voided transaction. |
400 currency mismatch |
The "total" is in another currency than the transaction. |
400 missing index |
There is no "index". |
409 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. |
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
- 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.
- A link or charge with
"autocapture"is captured already, with one act, so there is nothing left to capture.