Refunds
How to return a successful payment to the payer in full or in part, and how to learn that the money has gone.
A refund sends the money of a successful payment back to the payer, in full or in part. The merchant's server creates it. A refund goes the same way as the payment, in the payment currency.
Steps
Create a refund with a retry key and an amount:
curl -sS -X POST https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \ -H "Authorization: Bearer $TARGET_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 0b8e4f3a-6c21-4d7e-9a15-2f4c8b7d1e90" \ -d '{ "reference": "refund-1001-1", "amountMinor": "500", "description": "Partial refund, ticket T-5521", "metadata": { "ticket": "T-5521" } }'A 201 response carries the refund in the state it is in after the call to the provider. Fields: reference.
Wait for the outcome: a
refund.updatednotification (Notifications) or reading the refund. Read aPENDINGrefund yourself as well, even if you wait for notifications: an undelivered notification is never resent.curl -sS https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds/rf_5n7q2w8x4k3m9t6v2b8c4d \ -H "Authorization: Bearer $TARGET_API_KEY"GET /api/v1/payments/:id/refundsreturns all refunds of a payment, newest first.
There is no default "refund everything" amount: the amount is always named. After a refund the payment stays SUCCEEDED; what was returned shows in its refundedMinor field.
What can be refunded
Only a payment in the SUCCEEDED status, created through the API and not under review. The refundable remainder is paidMinor minus all refunds of the payment except failed ones. A payment has no more than 50 refunds, not counting failed ones, and 200 in all. A 409 error names what blocks a refund: reference.
A merchant disabled by an administrator can still create and read refunds; the rest of the API is closed to it.
Retry key
The Idempotency-Key header is required for a refund: without it, a 400 error with the rule idempotency_key_required.
- The same key and the same body for the same payment: the same refund as it is now and the
Idempotency-Replayed: trueheader, no second refund. - A 409 error with a rule, for example
refund_exceeds_remaining, takes the key: a retry with the same key gets the same error, so send the corrected request with a new key. The exception isrequest_in_progress: the request with this key is still running, retry it with the same key and the same body.refund_in_progressmeans another refund of the payment is in progress: read the payment's refunds, and if the running one is not yours, retry after its outcome with the same key. - An API key, merchant or environment error with a correct secret (401
api_key_disabled,api_key_revoked,api_key_expired, 403merchant_not_active,environment_closed) also takes the key: a retry with the same key gets the same error, even after the API key is enabled or the merchant is opened. A revoked or expired API key takes the retry key only for a day after the key ended; after that its 401 does not take the key, but it still gets what was recorded for the same body on a retry. The first response does not show whether a 401 was recorded: retry the same request with the same retry key using a valid API key, and a recorded error comes back withIdempotency-Replayed: true. - After a timeout, a dropped connection or a 5xx response, retry the creation with the same key and the same body: the refund may have been created. A 503
dependency_unavailableresponse to a refund is not a failure but "no answer", whatever rule it names. A new key and a new refund number would create a second one. - Keys are shared with payment creation keys: a key already used by a payment gets
idempotency_key_reusedon a refund.
The refund number reference is unique per merchant within an environment: a second refund with the same number gets the refund_reference_exists error with the ID of the refund already created.
Statuses
| Status | What it means |
|---|---|
PENDING | The refund is in progress or its outcome is unknown |
SUCCEEDED | The money has gone to the payer |
FAILED | There was no refund; the reason is in reason |
Read an unknown status as PENDING. An unknown outcome is PENDING with inReview: true, not a failure: the money may have gone out, so do not create a second refund of the same money. A provider inquiry names the outcome: often in the first hour, hourly up to a day, then daily and weekly, up to 90 days. A refund the provider does not process through the API, and a refund whose outcome the provider has not named or named contradictorily, are decided by Target employees: SUCCEEDED if the refund was made at the provider, or FAILED with the reason operator_declined if it was not. Until the decision such a refund stays PENDING. Read it hourly during the first day and daily after that; if it stays PENDING longer than a day, ask support, quoting the refund id. If the provider returned a different amount, the refund stays PENDING with inReview: true until it is corrected manually: ask support, quoting the refund id.
A late answer from the provider can give FAILED or SUCCEEDED an inReview: true with the same status. For a refund through the API, a provider that can be asked for the status is asked again for three days after its decline, after an employee decision up to 90 days after the refund was created and at least three days after the decision, and later too when it reports on the refund. Such a review is not lifted by itself: do not return the same money with a new refund or any other way, and ask support, quoting the refund id. A refund.updated notification tells you about it; before returning the same money another way, re-read the refund anyway.
Test data
In the test environment a stand-in provider carries out the refund, and a label in the refund's metadata.sandbox sets the outcome. Without a label the refund is accepted and goes through at the first check. Labels: paid, pending, declined, declined_later, declined_then_paid, not_sent, timeout_paid, timeout_declined, timeout_unknown, unparsed, wrong_amount. An unknown label gives FAILED with the reason technical_failure.