OpenAPI Specification
openapi: 3.1.0
info:
title: Super Payments Checkout Sessions Refunds API
description: Super Payments is empowering businesses with free payments, allowing them to offer customers a % Cash Reward, which is automatically deducted from their next purchase when they pay with Super. By rewarding customers in this way, they shop more often and buy more with a business. In addition, Cash Rewards boost customer loyalty and retention, with better conversion rates at typically higher average order values. Cash Rewards also increase adoption of Super Payments as the checkout method, meaning more free payments for your business.
version: '2026-04-01'
contact:
url: https://docs.superpayments.com
license:
name: Super Payments
identifier: https://www.superpayments.com/terms-and-conditions
servers:
- url: https://api.superpayments.com/2026-04-01
description: Live Environment
- url: https://api.test.superpayments.com/2026-04-01
description: Sandbox Environment
tags:
- name: Refunds
description: Refund management
paths:
/refunds/payouts:
post:
operationId: create-payout-refund
summary: Create Payout Refund (Restricted)
description: This endpoint is used to initiate a payout refund to a provided payment method. This is a restricted endpoint, contact customer support to request access.
parameters:
- name: authorization
in: header
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitiatePayoutRefundInputDto'
responses:
'200':
description: Successful payout refund initiation
content:
application/json:
schema:
$ref: '#/components/schemas/InitiatePayoutRefundOutputDto'
'400':
description: Bad Request
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 400
const: 400
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/request_validation_error
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Bad Request
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Request validation failed
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'401':
description: Unauthorized
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 401
const: 401
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/unauthorized
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Unauthorized
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Invalid credentials provided
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'404':
description: Not Found
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 404
const: 404
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/not_found
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Not Found
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Resource not found
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'409':
description: Conflict
content:
application/problem+json: {}
'422':
description: Unprocessable Entity
content:
application/problem+json: {}
'500':
description: Internal Server Error
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 500
const: 500
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/internal_server_error
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Internal Server Error
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- An unexpected error occurred
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
security:
- api_key: []
tags:
- Refunds
/refunds:
post:
operationId: create-refund
summary: Create Refund
description: This endpoint is used to initiate a refund for a payment transaction.
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateRefundInputDto'
responses:
'200':
description: Successful refund initiation
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateRefundOutputDto'
'400':
description: Bad Request
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 400
const: 400
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/request_validation_error
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Bad Request
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Request validation failed
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'401':
description: Unauthorized
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 401
const: 401
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/unauthorized
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Unauthorized
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Invalid credentials provided
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'404':
description: Not Found
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 404
const: 404
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/not_found
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Not Found
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Resource not found
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'409':
description: Conflict
content:
application/problem+json: {}
'422':
description: Unprocessable Entity
content:
application/problem+json: {}
'500':
description: Internal Server Error
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 500
const: 500
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/internal_server_error
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Internal Server Error
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- An unexpected error occurred
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
security:
- api_key: []
tags:
- Refunds
/refunds/{transactionId}:
get:
operationId: get-refund-transaction-2025-11-01
summary: Get refund transaction
description: Poll for an individual refund transaction status to check its current state. Returns detailed information about the refund transaction including its status and payment details.
parameters:
- name: transactionId
in: path
description: Id of the refund transaction
required: true
schema:
type: string
format: uuid
examples:
- 9eb0ee73-3922-4be3-bdbb-1404b38cca86
responses:
'200':
description: Refund transaction details
content:
application/json:
schema:
$ref: '#/components/schemas/GetRefundTransactionOutput'
'400':
description: Bad Request
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 400
const: 400
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/request_validation_error
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Bad Request
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Request validation failed
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'401':
description: Unauthorized
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 401
const: 401
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/unauthorized
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Unauthorized
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Invalid credentials provided
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'404':
description: Not Found
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 404
const: 404
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/not_found
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Not Found
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Resource not found
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'406':
description: Not Acceptable
content:
application/problem+json: {}
'500':
description: Internal Server Error
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 500
const: 500
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/internal_server_error
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Internal Server Error
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- An unexpected error occurred
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
security:
- api_key: []
tags:
- Refunds
/refunds/search:
get:
operationId: search-refund-transactions-2025-11-01
summary: Search refund transactions
description: Retrieve a list of refund transactions with filtering options. Results are paginated and can be filtered by various criteria including status, payment ID, and date range. Refund transactions are returned in reverse chronological order (newest first). If no filters are specified, all available refund transactions will be returned subject to pagination limits.
parameters:
- name: transactionStatus
in: query
description: Filter by refund transaction status. Can be a single status or an array of statuses.
required: false
schema:
description: Filter by refund transaction status. Can be a single status or an array of statuses.
type: array
items:
type: string
- name: startDate
in: query
description: Filter by start date (ISO 8601 format). Inclusive.
required: false
schema:
description: Filter by start date (ISO 8601 format). Inclusive.
type: string
format: date-time
- name: endDate
in: query
description: Filter by end date (ISO 8601 format). Inclusive.
required: false
schema:
description: Filter by end date (ISO 8601 format). Inclusive.
type: string
format: date-time
- name: pageSize
in: query
description: Number of items to return per page.
required: false
schema:
description: Number of items to return per page.
type: integer
- name: page
in: query
description: Page token for pagination (cursor).
required: false
schema:
description: Page token for pagination (cursor).
type: string
- name: paymentExternalReference
in: query
description: Filter by the external reference of the original payment.
required: false
schema:
description: Filter by the external reference of the original payment.
type: string
- name: paymentTransactionId
in: query
description: Filter by the original payment transaction ID.
required: false
schema:
description: Filter by the original payment transaction ID.
type: string
- name: transactionId
in: query
description: Filter by refund transaction ID.
required: false
schema:
description: Filter by refund transaction ID.
type: string
responses:
'200':
description: List of refund transactions
content:
application/json:
schema:
$ref: '#/components/schemas/GetRefundsListOutput'
'400':
description: Bad Request
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 400
const: 400
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/request_validation_error
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Bad Request
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Request validation failed
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'401':
description: Unauthorized
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 401
const: 401
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/unauthorized
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Unauthorized
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Invalid credentials provided
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'404':
description: Not Found
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 404
const: 404
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/not_found
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Not Found
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Resource not found
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
'406':
description: Not Acceptable
content:
application/problem+json: {}
'500':
description: Internal Server Error
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 500
const: 500
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/internal_server_error
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Internal Server Error
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- An unexpected error occurred
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
security:
- api_key: []
tags:
- Refunds
components:
schemas:
BuyNowPayLaterRefundType:
description: Type identifier for Buy Now, Pay Later refund funding details. Used when refunds are processed through a BNPL provider like Klarna or Afterpay, typically reducing or canceling the customer's outstanding balance.
type: string
const: BUY_NOW_PAY_LATER
RefundPaymentCard:
type: object
properties:
lastFourDigits:
description: The last four digits of the card used for the refund payment.
type: string
brand:
description: The brand of the card used for the refund payment (e.g., Visa, Mastercard).
type: string
required:
- lastFourDigits
- brand
OpenBankingRefundType:
description: Type identifier for open banking refund funding details. Used when refunds are processed directly to a customer's bank account using Open Banking payment rails.
type: string
const: OPEN_BANKING
InitiateRefundOutputDto:
type: object
properties:
transactionId:
description: The unique identifier of the refund
type: string
format: uuid
transactionReference:
description: The reference number for the refund
type: string
fundingSummary:
description: Summary of funding sources for the refund
type: object
properties:
cashPayableToMerchant:
description: Amount payable to merchant
type: object
properties:
amount:
description: Amount in minor units
type: integer
minimum: 0
currency:
description: Currency code
type: string
const: GBP
required:
- amount
- currency
customerFundedAmount:
description: Amount funded by customer
type: object
properties:
amount:
description: Amount in minor units
type: integer
minimum: 0
currency:
description: Currency code
type: string
const: GBP
required:
- amount
- currency
superFundedAmount:
description: Amount funded by Super
type: object
properties:
amount:
description: Amount in minor units
type: integer
minimum: 0
currency:
description: Currency code
type: string
const: GBP
required:
- amount
- currency
merchantFundedAmount:
description: Amount funded by merchant
type: object
properties:
amount:
description: Amount in minor units
type: integer
minimum: 0
currency:
description: Currency code
type: string
const: GBP
required:
- amount
- currency
required:
- cashPayableToMerchant
- customerFundedAmount
- superFundedAmount
- merchantFundedAmount
required:
- transactionId
- transactionReference
- fundingSummary
GetRefundTransactionOutput:
type: object
properties:
transactionId:
description: Unique identifier for the payment transaction
type: string
transactionReference:
description: Reference code for the transaction
type: string
transactionStatus:
description: Current status of the refund transaction
allOf:
- $ref: '#/components/schemas/RefundOutputStatus'
brandId:
description: Brand identifier associated with the transaction
type:
- string
- 'null'
format: uuid
payments:
description: List of refund payments
type: array
items:
$ref: '#/components/schemas/RefundPayment'
paymentMethodId:
description: Payment method identifier associated with the refund, if applicable
type:
- string
- 'null'
required:
- transactionId
- transactionReference
- transactionStatus
- brandId
- payments
InitiatePayoutRefundOutputDto:
type: object
properties:
transactionId:
description: The unique identifier of the refund
type: string
format: uuid
transactionReference:
description: The reference number for the refund
type: string
required:
- transactionId
- transactionReference
InitiateRefundInputDto:
type:
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/super-payments/refs/heads/main/openapi/super-payments-refunds-api-openapi.yml