Super Payments Checkout Sessions API

openapi: 3.1.0
info:
  title: Super Payments Checkout Sessions 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: Checkout Sessions
  description: Checkout Session management
paths:
  /checkout-sessions:
    post:
      operationId: create-checkout-session
      summary: Create a new checkout session
      description: Creates a new checkout session for a payment initiator.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutSessionRequestDto'
      responses:
        '200':
          description: Checkout session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCheckoutSessionResponseDto'
        '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'
        '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: NotFound
          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: {}
        '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:
      - Checkout Sessions
  /checkout-sessions/{checkoutSessionId}:
    get:
      operationId: get-checkout-session
      summary: Retrieve a checkout session by ID
      description: Fetches the details of a checkout session using its ID.
      parameters:
      - name: checkoutSessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Checkout session details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCheckoutSessionResponseDto'
        '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'
        '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: NotFound
          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: {}
        '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:
      - Checkout Sessions
  /checkout-sessions/{checkoutSessionId}/proceed:
    post:
      operationId: proceed-payment-via-checkout-session
      summary: Proceed with payment via checkout session
      description: Processes a payment using an existing checkout session. Requires the payment initiator ID and session details.
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      - name: checkoutSessionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProceedPaymentViaCheckoutSessionRequestDto'
      responses:
        '200':
          description: Payment processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProceedPaymentViaCheckoutSessionResponseDto'
        '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:
                            - UNRESTRICTED
                            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: NotFound
          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: {}
        '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:
      - Checkout Sessions
  /checkout-sessions/{checkoutSessionId}/order-details:
    post:
      operationId: upsert-order-details
      summary: Upsert order details for a checkout session
      description: Updates or inserts order details (shipping address, billing address, and/or line items) for an existing checkout session. At least one of the three fields must be provided.
      parameters:
      - name: checkoutSessionId
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertOrderDetailsRequestDto'
      responses:
        '200':
          description: Order details updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertOrderDetailsResponseDto'
        '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'
        '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: NotFound
          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
               

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/super-payments/refs/heads/main/openapi/super-payments-checkout-sessions-api-openapi.yml