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

  1. Create a refund with a retry key and an amount:

    curl -sS -X POST https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \
      -H "Authorization: Bearer $PAYDEX_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.

  2. Wait for the outcome: a refund.updated notification (Notifications) or reading the refund. Read a PENDING refund yourself as well, even if you wait for notifications: an undelivered notification is never resent.

    curl -sS https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds/rf_5n7q2w8x4k3m9t6v2b8c4d \
      -H "Authorization: Bearer $PAYDEX_API_KEY"
  3. GET /api/v1/payments/:id/refunds returns 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: true header, 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 is request_in_progress: the request with this key is still running, retry it with the same key and the same body. refund_in_progress means 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, 403 merchant_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 with Idempotency-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_unavailable response 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_reused on 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

StatusWhat it means
PENDINGThe refund is in progress or its outcome is unknown
SUCCEEDEDThe money has gone to the payer
FAILEDThere 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 Paydex 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.

API v1 · built 2026-11-18 · release f13e6bf

The API reference is built from the server code: it never describes an endpoint that does not exist.