Refund transaction
Refund all or part of what was captured of a transaction, to the card it was paid with. You can refund several times, up to what was captured in all.
Request
POST https://{trnid}is the transaction's"id", from seq, or from the answer to Charge subscriber.
The key needs the refund 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 refund: more than 0, at most what was captured and not yet refunded, captured - refunded, and in the transaction's currency. We don't check the last two: the acquirer refuses a refund it won't make. |
index |
integer | The transaction's index: how many acts it has now, the length of its
|
Example
Refund one item of a captured order, after the payer returned it:
curl https://api.gjold.com/v1/transactions/378/refund \
-u {apikey} \
-H 'Idempotency-Key: 9e2f71c04b3a5d68a7b8c9d0e1f2a3b4' \
-d @refund.json{
"total": "99.95 DKK",
"index": 1
}
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 refund's act has "act": "refund", and the transaction's
totals.refunded goes up 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 refund 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
- A refund goes to the card that paid. The payer usually sees it within a few working days. See the knowledge base's Captures and refunds.
- If nothing was captured yet, void the transaction in the dashboard instead, as v1 has no void request: the payer gets their money back sooner.