Super Payments Payments API
Payment processing and management
OpenAPI Specification
openapi: 3.1.0
info:
title: Super Checkout Sessions Payments 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: Payments
description: Payment processing and management
paths:
/payments:
post:
operationId: create-payment-intent
summary: Create Payment Intent
description: This endpoint is used to create a payment intent for e-commerce transactions. It requires the merchant integration to be set up and will return a payment intent object upon successful creation.
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentIntentInput'
responses:
'200':
description: Initiate a payment intent
content:
application/json:
schema:
discriminator:
propertyName: offSession
mapping:
'true': '#/components/schemas/CreateOffSessionPaymentIntentOutput'
'false': '#/components/schemas/CreateOnSessionPaymentIntentOutput'
oneOf:
- $ref: '#/components/schemas/CreateOnSessionPaymentIntentOutput'
- $ref: '#/components/schemas/CreateOffSessionPaymentIntentOutput'
'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'
'402':
description: Payment Required
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 402
const: 402
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/payment_required
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Payment Required
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Payment details provided by customer could not be used
instance:
description: A unique identifier for the error
type: string
examples:
- '4186980260999334757'
extensions:
description: Extensions to the standard error response structure that may contain additional error details.
type: object
properties:
issues:
description: Information about the issues with the payment attempt that resulted in the error.
type: object
properties:
declineReason:
description: A customer-friendly description of the reason their payment method was declined for payment.
type: string
examples:
- The CVC number is incorrect.
declineCode:
description: A code that identifies the reason why a card was declined, sourced from the card provider.
type: string
examples:
- AUTHENTICATION_REQUIRED
enum:
- AUTHENTICATION_REQUIRED
- DUPLICATE_SUSPECTED
- FRAUD_SUSPECTED
- GENERIC_DECLINE
- INSUFFICIENT_FUNDS
- INVALID_ADDRESS
- INVALID_AMOUNT
- INVALID_CVC
- INVALID_EXPIRY_MONTH
- INVALID_EXPIRY_YEAR
- INVALID_NUMBER
- INVALID_PIN
- MERCHANT_BLACKLIST
- PAYMENT_METHOD_ATTEMPTS_EXCEEDED
- PAYMENT_METHOD_EXPIRED
- PAYMENT_METHOD_NOT_SUPPORTED
- PAYMENT_METHOD_REVOKED
- PROCESSING_ERROR
declineClassification:
description: The classification of the decline code. If the decline code is "RESTRICTED" then the decline code must not be shown to the customer. Instead replace the decline code value with "GENERIC_DECLINE"
type: string
examples:
- RESTRICTED
enum:
- RESTRICTED
- UNRESTRICTED
'403':
description: Forbidden
content:
application/problem+json:
schema:
type: object
properties:
status:
description: The HTTP status code.
type: integer
examples:
- 403
const: 403
type:
description: A URI reference that identifies the problem type
type: string
examples:
- https://api.superpayments.com/errors/forbidden
title:
description: A short, human-readable summary of the problem type
type: string
examples:
- Forbidden
detail:
description: A human-readable explanation specific to this occurrence of the problem
type: string
examples:
- Action not allowed
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'
'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: []
- merchant_authorization_header_api_key: []
tags:
- Payments
/payments/{transactionId}:
get:
operationId: get-payment-transaction-2025-11-01
summary: Get payment transaction
description: Poll for an individual payment transaction status to check its current state. Returns detailed information about the payment including its status, amount, and funding details with associated card metadata. This endpoint includes detailed information about payment intent funding attempts and their associated card metadata. Use this endpoint if your integration has not been configured to use webhooks. Payment transactions are returned in real-time as they update in our system.
parameters:
- name: transactionId
in: path
description: Id of the payment transaction
required: true
schema:
type: string
format: uuid
examples:
- 9eb0ee73-3922-4be3-bdbb-1404b38cca86
responses:
'200':
description: Payment transaction details
content:
application/json:
schema:
$ref: '#/components/schemas/GetPaymentTransactionOutput'
'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:
- Payments
/payments/search:
get:
operationId: search-payment-transactions-2025-11-01
summary: Search payment transactions
description: Retrieve a list of payment transactions with filtering options. Results are paginated and can be filtered by various criteria including status, reference, and date range. Payment transactions are returned in reverse chronological order (newest first). If no filters are specified, all available payment transactions will be returned subject to pagination limits. Note that funding details and card metadata are not included in search results for performance reasons - use the individual payment transaction endpoint to access these details.
parameters:
- name: transactionStatus
in: query
description: Filter by transaction status. Can be a single status or an array of statuses.
required: false
schema:
description: Filter by transaction status. Can be a single status or an array of statuses.
type: array
items:
type: string
- name: transactionReference
in: query
description: Filter by transaction reference.
required: false
schema:
description: Filter by transaction reference.
type: string
- name: externalReference
in: query
description: Filter by external reference (e.g., order ID).
required: false
schema:
description: Filter by external reference (e.g., order ID).
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
responses:
'200':
description: List of payment transactions matching the search criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPaymentsListOutput'
'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:
- Payments
components:
schemas:
ThreeDSDto:
type: object
properties:
status:
description: Status of 3DS authentication (e.g., authenticated, attempted, failed)
type:
- string
- 'null'
version:
description: Version of 3DS used for authentication
type:
- string
- 'null'
authentication_flow:
description: Authentication flow (e.g., challenge, frictionless)
type:
- string
- 'null'
electronic_commerce_indicator:
description: Electronic commerce indicator
type:
- string
- 'null'
exemption_indicator:
description: Exemption indicator
type:
- string
- 'null'
result:
description: Authentication result
type:
- string
- 'null'
result_reason:
description: Reason for the authentication result
type:
- string
- 'null'
transaction_id:
description: Transaction ID for the 3DS authentication
type:
- string
- 'null'
required:
- status
- version
- authentication_flow
- electronic_commerce_indicator
- exemption_indicator
- result
- result_reason
- transaction_id
CashRewardPaymentFundingDetailsDto:
type: object
properties:
type:
description: Type identifier for cash reward payment funding details. Cash rewards payments use stored value from the customer's Super Payments account balance.
example: CASH_REWARD
allOf:
- $ref: '#/components/schemas/CashRewardPaymentType'
required:
- type
PaymentIntentAddressDto:
description: Address information for shipping or billing
type: object
properties:
addressLine1:
type:
- string
- 'null'
default: null
addressLine2:
type:
- string
- 'null'
default: null
addressLine3:
type:
- string
- 'null'
default: null
city:
type:
- string
- 'null'
default: null
country:
type:
- string
- 'null'
default: null
postCode:
type:
- string
- 'null'
default: null
firstName:
type:
- string
- 'null'
default: null
lastName:
type:
- string
- 'null'
default: null
phone:
type:
- string
- 'null'
default: null
email:
type:
- string
- 'null'
format: email
default: null
PaymentIntentProductDto:
description: Product line item with type and data fields
type: object
properties:
type:
description: The line item type
type: string
const: PRODUCT
data:
description: Product line item data
type: object
properties:
productDescription:
description: Description of the product
type: string
sku:
description: Stock Keeping Unit (SKU) identifier for the product
type: string
quantity:
description: Quantity of the product
type: number
minimum: 1
unitPrice:
description: Unit price in minor units (e.g., pence for GBP)
type: number
minimum: 0
currency:
description: Currency code
type: string
const: GBP
expectedDeliveryDate:
description: When delivery is expected to take place, either as a date (YYYY-MM-DD) or datetime with timezone
oneOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
required:
- type
- data
CreatePaymentIntentInput:
discriminator:
propertyName: offSession
mapping:
'true': '#/components/schemas/CreateOffSessionPaymentIntentInput'
'false': '#/components/schemas/CreateOnSessionPaymentIntentInput'
oneOf:
- $ref: '#/components/schemas/CreateOffSessionPaymentIntentInput'
- $ref: '#/components/schemas/CreateOnSessionPaymentIntentInput'
CreateOnSessionPaymentIntentInput:
type: object
properties:
externalReference:
description: External reference for the payment
type: string
examples:
- order-12345
maxLength: 255
amount:
description: Amount in minor units (pence for GBP)
type: integer
examples:
- 1234
maximum: 9999999
minimum: 1
currency:
description: Currency code
type: string
examples:
- GBP
const: GBP
metadata:
description: Additional metadata for the payment
type: object
examples:
- customerId: customer-123
orderId: '12345'
additionalProperties:
type: string
successUrl:
description: URL to redirect to on successful payment
type: string
examples:
- https://example.com/success
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/super-payments/refs/heads/main/openapi/super-payments-payments-api-openapi.yml