Super Payments Payments API

openapi: 3.2.0
info:
  title: Super 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:
    PaymentIntentAirlineDto:
      description: Airline line item with type and data fields
      type: object
      properties:
        type:
          description: The line item type
          type: string
          const: AIRLINE
        data:
          description: Airline data for enhanced scheme data
          type: object
          properties:
            flightNumber:
              description: The flight identifier
              type: string
            flightDate:
              description: Date of the flight, either as a date (YYYY-MM-DD) or datetime with timezone (e.g., 2026-03-15T10:30:00+00:00)
              oneOf:
              - type: string
                format: date
              - type: string
                format: date-time
            travellers:
              description: List of travellers
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                required:
                - name
            totalPrice:
              description: Total price in minor units (e.g., pence for GBP)
              type: number
              minimum: 0
            currency:
              description: Currency code
              type: string
              const: GBP
      required:
      - type
      - data
    GetPaymentTransactionOutput:
      type: object
      properties:
        transactionId:
          description: Unique identifier for the payment transaction
          type: string
        transactionReference:
          description: Reference code for the transaction
          type: string
        externalReference:
          description: External Reference, usually the order identifier associated with the transaction
          type:
          - string
          - 'null'
        transactionStatus:
          description: Current status of the payment transaction
          allOf:
          - $ref: '#/components/schemas/PaymentOutputStatus'
        transactionAmount:
          description: Amount of the transaction
          type: number
        metadata:
          description: Additional metadata associated with the transaction
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
        brandId:
          description: Brand identifier associated with the transaction
          type:
          - string
          - 'null'
          format: uuid
        fees:
          description: Fees associated with the transaction
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PaymentIntentFeeDto'
        funding:
          description: Funding sources for the transaction
          type: array
          items:
            $ref: '#/components/schemas/PaymentFunding'
      required:
      - transactionId
      - transactionReference
      - transactionStatus
      - transactionAmount
      - metadata
      - brandId
      - fees
      - funding
    DisputeDto:
      type: object
      properties:
        disputeId:
          type: string
        fundingAttemptId:
          type: string
        provider:
          type: string
        providerRef:
          type: string
        disputeReason:
          type: string
        disputeStatus:
          type: string
          enum:
          - lost
          - needs_response
          - under_review
          - warning_closed
          - warning_needs_response
          - warning_under_review
          - won
        disputedAmount:
          $ref: '#/components/schemas/TransactionCurrencyAmount'
        feeAmount:
          $ref: '#/components/schemas/TransactionCurrencyAmount'
        hasEvidence:
          type: boolean
        submissionDeadline:
          type:
          - string
          - 'null'
        submissionCount:
          type: number
        resolved:
          type: boolean
        isRefundable:
          type: boolean
        createdAt:
          type: string
        updatedAt:
          type: string
        stripeDestinationPaymentId:
          type:
          - string
          - 'null'
      required:
      - disputeId
      - fundingAttemptId
      - provider
      - providerRef
      - disputeReason
      - disputeStatus
      - disputedAmount
      - feeAmount
      - hasEvidence
      - submissionDeadline
      - submissionCount
      - resolved
      - isRefundable
      - createdAt
      - updatedAt
      - stripeDestinationPaymentId
    PaymentOutputStatus:
      description: Current status of the payment transaction
      type: string
      enum:
      - PaymentAbandoned
      - PaymentCancelled
      - PaymentDelayed
      - PaymentFailed
      - PaymentPending
      - PaymentSuccess
    OpenBankingPaymentFundingDetailsDto:
      type: object
      properties:
        type:
          description: Type identifier for open banking payment funding details. Open Banking payments allow customers to pay directly from their bank account through secure bank APIs without using cards.
          example: OPEN_BANKING
          allOf:
          - $ref: '#/components/schemas/OpenBankingPaymentType'
        institutionId:
          description: Identifier of the financial institution used for the open banking payment
          type:
          - string
          - 'null'
          examples:
          - barclays_uk
        institutionName:
          description: Display name of the financial institution used for the open banking payment
          type:
          - string
          - 'null'
          examples:
          - Barclays Bank
      required:
      

# --- 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