Refund a Payment

How Refunds Are Funded

Refunds are debited immediately from your account's Available balance. If your Available balance does not cover the refund, your float is used. If neither covers it, the refund cannot be processed and the request is declined.

You can view your balance in the Business Portal under Balances, and top it up from the same screen.

Without a float, check your Available balance before issuing a batch of refunds. Each one is debited as it is processed, so a batch can succeed partway through and then start failing once the balance runs out.

Funding Summary

The fundingSummary object provides a detailed breakdown of the financial components of a transaction. Use this data to determine the total funds available for a refund.

Full Refunds

A full refund returns the total transaction amount to the customer.

• Request Logic: Submit a POST request to the refund endpoint with the unique transactionId, amount, and currency. externalReference and brandId are optional.
• Response Outcome: The fundingSummary will reflect a zero balance across all funded fields, indicating a full refund.
• Webhooks: We will trigger a Refund Status Webhook to notify your system once the refund is successfully processed.

Request Example

curl --location 'https://api.superpayments.com/2026-08-01/refunds' \
--header 'Authorization: YOUR_SUPER_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transactionId":"33afc4e4-6f61-4171-9acd-8c9694fe1dff",
    "amount":5000,
    "currency":"GBP",
    "externalReference":"Full Refund",
    "brandId":"YOUR_BRAND_ID"
}'

curl --location 'https://api.test.superpayments.com/2026-08-01/refunds' \
--header 'Authorization: YOUR_SUPER_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transactionId":"33afc4e4-6f61-4171-9acd-8c9694fe1dff",
    "amount":5000,
    "currency":"GBP",
    "externalReference":"Full Refund",
    "brandId":"YOUR_BRAND_ID"
}'

Response Example

{
  "fundingSummary": {
      "cashPayableToMerchant": {
          "amount": 0,
          "currency": "GBP"
      },
      "customerFundedAmount": {
          "amount": 0,
          "currency": "GBP"
      },
      "merchantFundedAmount": {
          "amount": 0,
          "currency": "GBP"
      },
      "superFundedAmount": {
          "amount": 0,
          "currency": "GBP"
      }
  },
  "transactionId": "1445174f-8e93-4bc2-848b-90cf683ad4a9",
  "transactionReference": "RELUEM65AUC0G4AJ3"
}

Partial Refunds

Partial refunds allow you to return a specific portion of the total transaction value. This is typically used for multi-item orders where only one item is being returned.

• Request Logic: Submit a POST request to the refund endpoint with the unique transactionId, amount, and currency. externalReference and brandId are optional.
• Response Outcome: The fundingSummary will reflect the remaining balance across specific funded fields, indicating the funds still available for future refunds.
• Webhooks: We will trigger a Refund Status Webhook to provide real-time updates on the status of the partial refund.

Request Example

curl --location 'https://api.superpayments.com/2026-08-01/refunds' \
--header 'Authorization: YOUR_SUPER_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transactionId":"33afc4e4-1234-4171-9acd-8c9694fe1abc",
    "amount":2500,
    "currency":"GBP",
    "externalReference":"Partial Refund",
    "brandId":"YOUR_BRAND_ID"
}'

curl --location 'https://api.test.superpayments.com/2026-08-01/refunds' \
--header 'Authorization: YOUR_SUPER_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "transactionId":"33afc4e4-1234-4171-9acd-8c9694fe1abc",
    "amount":2500,
    "currency":"GBP",
    "externalReference":"Partial Refund",
    "brandId":"YOUR_BRAND_ID"
}'

Response Example

{
  "fundingSummary": {
      "cashPayableToMerchant": {
          "amount": 2500,
          "currency": "GBP"
      },
      "customerFundedAmount": {
          "amount": 2500,
          "currency": "GBP"
      },
      "merchantFundedAmount": {
          "amount": 0,
          "currency": "GBP"
      },
      "superFundedAmount": {
          "amount": 0,
          "currency": "GBP"
      }
  },
  "transactionId": "152254f-8e93-4bc2-848b-90cf683ad4a9",
  "transactionReference": "RELUEM65AUC0G6M89"
}

Check Refund Status

Use our GET Refund Transaction endpoint to manually verify the state of a specific refund at any time.

Refund Status Definitions

The transactionStatus field returned by the GET Refund Transaction endpoint will be one of the following values:

📘

Webhook statuses

The Refund Status webhook sends RefundSuccess, RefundFailed or RefundAbandoned. It does not send RefundPending, so poll the endpoint above if you need to observe a refund while it is still processing.

Request Example

To check a refund status, provide the unique transactionId generated during the Create Refund request. This ID is found in the initial refund response and serves as the primary reference for manual verification.

curl --location 'https://api.superpayments.com/2026-08-01/refunds/YOUR_TRANSACTION_ID' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_SECRET_KEY'

curl --location 'https://api.test.superpayments.com/2026-08-01/refunds/YOUR_TRANSACTION_ID' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_SECRET_KEY'

Response Example

{
  "brandId": "YOUR_BRAND_ID",
  "payments": [
      {
          "amountInMinorUnits": 1000,
          "fundingCard": {
              "brand": "visa",
              "lastFourDigits": "4242"
          },
          "fundingDetails": {
              "brand": "visa",
              "last4": "4242",
              "reference": "123456789",
              "referenceStatus": "available",
              "referenceType": "acquirer_reference_number",
              "type": "CARD"
          },
          "fundingInstitution": null,
          "reference": "123456789",
          "referenceStatus": "available",
          "referenceType": "acquirer_reference_number"
      }
  ],
  "transactionId": "1edc0640-337b-47ef-970d-0aef5e41234",
  "transactionReference": "REGDAEM3NCS97SABC",
  "transactionStatus": "RefundSuccess",
  "paymentMethodId": "pm_123"
}

Why a Refund Was Declined

The most common reason a refund is declined is that neither your Available balance nor your float covers it. When that happens the API returns a 422 using the application/problem+json format:

{
  "status": 422,
  "type": "https://api.superpayments.com/errors/insufficient_balance",
  "title": "Unprocessable Entity",
  "detail": "Insufficient balance in merchant account"
}

Top up your balance in the Business Portal and retry the refund.

All errors follow this same shape - type identifies the problem and detail explains it - so you can branch on type to handle other failures. See Errors for the full response format and the status codes the API returns.

Search Refunds

Use the Search Refund Transactions endpoint to find refunds across a date range, by status, or against an original payment. All query parameters are optional.

Request Example

curl --location 'https://api.superpayments.com/2026-08-01/refunds/search?startDate=2026-03-01&endDate=2026-03-31&transactionStatus=RefundSuccess' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_SUPER_SECRET_KEY'

curl --location 'https://api.test.superpayments.com/2026-08-01/refunds/search?startDate=2026-03-01&endDate=2026-03-31&transactionStatus=RefundSuccess' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_SUPER_SECRET_KEY'

Response Example

{
  "pageSize": 25,
  "nextPage": "eyJwYWdlIjoyfQ",
  "hasNext": true,
  "items": [
    {
      "transactionId": "123-123-123-123",
      "paymentTransactionId": "123-123-123-123",
      "paymentExternalReference": "Order-123",
      "transactionReference": "RFND123",
      "minorUnitAmount": 5000,
      "currency": "GBP",
      "transactionStatus": "RefundSuccess",
      "transactionStatusChangedAt": "2026-03-15T10:20:28.000Z",
      "brandId": "YOUR_BRAND_ID",
      "paymentMethodId": "pm_123"
    }
  ]
}

📘

Paging through results

Use hasNext to decide whether to request another page, passing nextPage as the page parameter on your next request. This is the standard cursor paging used across our list endpoints - see Pagination.

Handle Post-Payment Events

Automate your backend processes by listening for real-time transaction updates.

Automate Order Fulfillment

Set up a webhook to handle post-payment events sent by Super. These notifications ensure your system is updated with the final payment status even if the customer closes their browser or leaves the page before the frontend callback completes.

Refund Webhook Events

Super sends refund.success when a refund completes and refund.failed when it does not. Handle both to capture every outcome.

Both events share the same payload shape:

{
  "data": {
    "brandId": "YOUR_BRAND_ID",
    "refundId": "123-123-123-123",
    "status": "RefundSuccess",
    "refundReference": "RFND123",
    "externalReference": "Refund-123",
    "originatingPaymentId": "123-123-123-123",
    "originatingPaymentExternalReference": "Order-123",
    "originatingPaymentSource": "paymentLink",
    "amount": {
      "amount": 5000,
      "amountMultiplier": 100,
      "currency": "GBP"
    },
    "refundComponents": {
      "merchantAmount": {
        "amount": 5000,
        "amountMultiplier": 100,
        "currency": "GBP"
      },
      "customerAmount": {
        "amount": 0,
        "amountMultiplier": 100,
        "currency": "GBP"
      },
      "superAmount": {
        "amount": 0,
        "amountMultiplier": 100,
        "currency": "GBP"
      }
    }
  },
  "eventId": "evt_123",
  "eventType": "refund.success",
  "eventDatetime": "2026-03-15T10:20:28.000Z"
}

📘

Reconciling a refund

refundComponents splits the refund across the parties who funded the original payment, mirroring the fundingSummary returned when the refund was created. Use it to reconcile what is returned to the customer against what is deducted from you.

Why Use Webhooks?

Listening to these asynchronous events is essential for a robust integration. It ensures your system stays in sync for all payment methods - including those that require external authentication.

Tip: For more details on setting up webhooks, check out our Webhook Documentation.