Super Payments Settlements API

openapi: 3.2.0
info:
  title: Super Payments Settlements 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.
  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: Settlements
  description: Settlement batches, details, and reconciliation
paths:
  /settlements/{settlementId}:
    get:
      operationId: get-settlement-detail-2025-11-01
      summary: Get settlement detail
      description: Fetch a single settlement and its payments/statistics. Provide Accept
      parameters:
      - name: settlementId
        in: path
        description: Settlement identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: Accept
        in: header
        description: Optional. Omit or specify application/json to receive JSON (default) or provide text/csv (or application/csv) to download CSV.
        required: false
        schema:
          type: string
          examples:
          - application/json
      responses:
        '200':
          description: Settlement detail response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementDetailResponse'
            text/csv:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - api_key: []
      tags:
      - Settlements
  /settlements/{settlementId}/reconciliation:
    get:
      operationId: get-settlement-reconciliation-2025-11-01
      summary: Get settlement reconciliation rows
      description: Return ledger reconciliation items for a settlement, with pagination. Provide Accept
      parameters:
      - name: settlementId
        in: path
        description: Settlement identifier.
        required: true
        schema:
          type: string
          format: uuid
      - name: pageSize
        in: query
        description: Number of reconciliation rows per page.
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
      - name: page
        in: query
        description: Opaque cursor returned by previous responses.
        required: false
        schema:
          type: string
      - name: Accept
        in: header
        description: Optional. Omit or specify application/json to receive JSON (default) or provide text/csv (or application/csv) to download CSV.
        required: false
        schema:
          type: string
          examples:
          - application/json
      responses:
        '200':
          description: Settlement reconciliation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementReconciliationResponse'
            text/csv:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - api_key: []
      tags:
      - Settlements
  /settlements:
    get:
      operationId: list-settlements-2025-11-01
      summary: List settlements
      description: Retrieve paginated settlement batches for the current merchant. Provide Accept
      parameters:
      - name: settlementReference
        in: query
        description: Filter by prefix of settlement reference (case-insensitive).
        required: false
        schema:
          type: string
          maxLength: 64
      - name: pageSize
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
      - name: page
        in: query
        description: Opaque cursor returned by previous responses.
        required: false
        schema:
          type: string
      - name: Accept
        in: header
        description: Optional. Omit or specify application/json to receive JSON (default) or provide text/csv (or application/csv) to download CSV.
        required: false
        schema:
          type: string
          examples:
          - application/json
      responses:
        '200':
          description: List settlements response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementListResponse'
            text/csv:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - api_key: []
      tags:
      - Settlements
components:
  schemas:
    SettlementListResponse:
      type: object
      properties:
        pageSize:
          description: Number of items per page.
          type: integer
        nextPage:
          description: Token for the next page of results.
          type:
          - string
          - 'null'
        hasNext:
          description: Whether there are more pages of results.
          type: boolean
        items:
          description: List of settlements.
          type: array
          items:
            $ref: '#/components/schemas/SettlementListItem'
      required:
      - pageSize
      - hasNext
      - items
    SettlementStatus:
      description: Current status of the settlement batch.
      type: string
      enum:
      - CREATED
      - ERRORED
      - SETTLED
      - SETTLED_AFTER_RETRY
    SettlementDetailResponse:
      type: object
      properties:
        settlementId:
          description: Unique identifier for the settlement.
          type: string
        settlementReference:
          description: External reference for the settlement, if provided.
          type:
          - string
          - 'null'
        settlementTs:
          description: ISO timestamp when the settlement was processed. Same timestamp as settledAt in list responses.
          type:
          - string
          - 'null'
          format: date-time
        status:
          description: Current status of the settlement.
          allOf:
          - $ref: '#/components/schemas/SettlementStatus'
        minorUnitAmount:
          description: Amount in minor units (integer).
          type: integer
        currency:
          description: Currency code.
          type: string
        payments:
          description: List of payments included in this settlement.
          type: array
          items:
            $ref: '#/components/schemas/SettlementPayment'
        settlementStatistics:
          description: Statistical information for the settlement.
          $ref: '#/components/schemas/SettlementStatistics'
        createdAt:
          description: ISO timestamp when the settlement row was created.
          type: string
          format: date-time
      required:
      - settlementId
      - settlementReference
      - settlementTs
      - status
      - minorUnitAmount
      - currency
      - payments
      - settlementStatistics
      - createdAt
    ProblemDetails:
      type: object
      properties:
        status:
          description: The HTTP status code.
          type: integer
          examples:
          - 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'
    SettlementPaymentStatus:
      description: Status of an individual payment included in a settlement.
      type: string
      enum:
      - CREATED
      - FAILED
      - PENDING
      - SETTLED
    SettlementStatistics:
      type: object
      properties:
        openingBalanceAmount:
          description: Opening balance as an integer. Interpret using amountScale.
          type: integer
        reservedFeesAmount:
          description: Reserved fees amount as an integer. Interpret using amountScale.
          type: integer
        amountScale:
          description: Scale (number of decimal places) shared by the statistics amounts.
          type: integer
          examples:
          - 2
      required:
      - openingBalanceAmount
      - reservedFeesAmount
      - amountScale
    SettlementReconciliationItem:
      type: object
      properties:
        reconciliationItemId:
          description: Unique identifier for the reconciliation item.
          type: string
        transactionId:
          description: Identifier of the transaction associated with this reconciliation item.
          type: string
        transactionType:
          description: Type of transaction represented by this reconciliation row.
          type: string
          enum:
          - ABOUND_REFUND_HOLD
          - ABOUND_REFUND_HOLD_RELEASE
          - DISPUTE_AMOUNT_COLLECTION
          - DISPUTE_AMOUNT_RETURN
          - FEE_COLLECTION
          - FEE_LIABILITY_HOLD
          - FLOAT_HOLD
          - MANUAL_ADJUSTMENT_CREDIT
          - MANUAL_ADJUSTMENT_DEBIT
          - MANUAL_ALLOCATION
          - PAYMENT
          - PAYOUT
          - PUBLISHER_COMMISSION_PAYOUT
          - REFUND
          - REFUND_RESERVATION_RELEASE
          - REFUND_TOPUP_TRANSFER_CLAWBACK
          - REWARD_SETTLEMENT
          - ROUNDING_ADJUSTMENT
          - TOPUP_TRANSFER
        paymentIntentId:
          description: Payment intent identifier associated with the transaction. Will be null when not applicable to the transaction type.
          type:
          - string
          - 'null'
        paymentIntentReference:
          description: Payment intent reference associated with the transaction. Will be null when not applicable to the transaction type.
          type:
          - string
          - 'null'
        paymentIntentExternalReference:
          description: Payment intent external reference provided when the payment intent was created. Will be null when not applicable.
          type:
          - string
          - 'null'
        refundId:
          description: Refund identifier associated with the transaction. Will be null when not applicable to the transaction type.
          type:
          - string
          - 'null'
        refundReference:
          description: Refund reference associated with the transaction. Will be null when not applicable to the transaction type.
          type:
          - string
          - 'null'
        refundExternalReference:
          description: Refund external reference provided when the refund was created. Will be null when not applicable.
          type:
          - string
          - 'null'
        amountSettled:
          description: Amount settled as an integer. Interpret using amountScale.
          type: integer
        amountScale:
          description: Scale (number of decimal places) applied to amountSettled.
          type: integer
          examples:
          - 2
        currency:
          description: Currency code.
          type: string
        isCredit:
          description: True when the row represents a credit, false for a debit.
          type: boolean
      required:
      - reconciliationItemId
      - transactionId
      - transactionType
      - paymentIntentId
      - paymentIntentReference
      - paymentIntentExternalReference
      - refundId
      - refundReference
      - refundExternalReference
      - amountSettled
      - amountScale
      - currency
      - isCredit
    SettlementPayment:
      type: object
      properties:
        paymentReference:
          description: Reference for the payment or payout included in the settlement.
          type: string
        status:
          description: Payment status within the settlement.
          allOf:
          - $ref: '#/components/schemas/SettlementPaymentStatus'
        minorUnitAmount:
          description: Amount in minor units (integer).
          type: integer
        currency:
          description: Currency code for the payment.
          type: string
      required:
      - paymentReference
      - status
      - minorUnitAmount
      - currency
    SettlementListItem:
      type: object
      properties:
        settlementId:
          description: Unique identifier for the settlement.
          type: string
        settlementReference:
          description: Settlement reference supplied by the merchant, when available.
          type:
          - string
          - 'null'
        settledAt:
          description: ISO timestamp when the settlement was completed.
          type:
          - string
          - 'null'
          format: date-time
        status:
          description: Current status of the settlement.
          allOf:
          - $ref: '#/components/schemas/SettlementStatus'
        minorUnitAmount:
          description: Amount in minor units (integer).
          type: integer
        currency:
          description: Currency code.
          type: string
        createdAt:
          description: ISO timestamp when the settlement row was created.
          type: string
          format: date-time
      required:
      - settlementId
      - settlementReference
      - settledAt
      - status
      - minorUnitAmount
      - currency
      - createdAt
    SettlementReconciliationResponse:
      type: object
      properties:
        pageSize:
          description: Number of reconciliation rows per page.
          type: integer
        nextPage:
          description: Opaque cursor returned by previous responses.
          type:
          - string
          - 'null'
        hasNext:
          description: Whether there are more pages of results.
          type: boolean
        items:
          description: Reconciliation items for the settlement.
          type: array
          items:
            $ref: '#/components/schemas/SettlementReconciliationItem'
      required:
      - pageSize
      - hasNext
      - items
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: Authorization
      description: Merchant API key
    HMAC:
      type: apiKey
      in: header
      name: super-signature
      description: Header used to validate the webhook request