openapi: 3.1.0
info:
  title: Scan & Pay API
  version: '2026-09-28'
  summary: Create a QR Pass session and read payment status.
  description: |
    Scan & Pay's merchant-facing HTTPS API. This specification covers
    creating a QR Pass session at checkout and reading its status.
    Your API Secret, sent in the `X-Scanpay-Key` header, identifies
    your merchant account on every request.

    All amounts are integers in cents (e.g. `1990` = $19.90). The
    legacy `amount` field (float dollars) is still accepted on
    `createPaymentSession` for backwards compatibility but deprecated.

    Only AUD is supported. Session expiry is 5 minutes from creation.
  contact:
    name: Scan & Pay
    email: hi@scanandpay.com.au
    url: https://docs.scanandpay.com.au
  license:
    name: Proprietary
    url: https://scanandpay.com.au/terms

servers:
  - url: https://api.scanandpay.com.au
    description: Production

security:
  - apiKey: []

tags:
  - name: Payments
    description: Create and read payment sessions.

paths:
  /createPaymentSession:
    post:
      tags: [Payments]
      operationId: createPaymentSession
      summary: Create a payment session
      description: |
        Create a payment session and return its QR Pass and payment URL.
        Sessions are unique per order: sending the same `platformOrderId`
        again returns the existing session unchanged. The business name
        customers see always comes from your Business Portal profile; no
        PayTo PayID is needed.
      parameters:
        - $ref: '#/components/parameters/ScanpayVersion'
        - $ref: '#/components/parameters/ScanpaySdk'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
            examples:
              cents:
                summary: Cents (preferred)
                value:
                  platformOrderId: order_456
                  amountCents: 1990
                  metadata:
                    cart: c_789
              dollars:
                summary: Float dollars (deprecated)
                value:
                  platformOrderId: order_456
                  amount: 19.90
      responses:
        '200':
          description: Session created (or existing returned on idempotent replay).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSession'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'

  /getPaymentStatus:
    get:
      tags: [Payments]
      operationId: getPaymentStatus
      summary: Read payment session status
      description: |
        Return the current state of one of your sessions. Use it to poll,
        or to confirm a payment when a webhook has not arrived.
      parameters:
        - in: query
          name: sessionId
          required: true
          schema:
            type: string
            example: SP_SESS_abc123def456
          description: Session identifier returned from createPaymentSession.
        - $ref: '#/components/parameters/ScanpayVersion'
        - $ref: '#/components/parameters/ScanpaySdk'
      responses:
        '200':
          description: Session found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSessionStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No session with that ID belongs to your merchant account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Scanpay-Key
      description: |
        Your Scan & Pay API Secret, issued from the Business Portal.

  parameters:
    ScanpayVersion:
      in: header
      name: Scanpay-Version
      schema:
        type: string
        example: '2026-05-11'
      description: Date-stamped API contract version the caller targets.
    ScanpaySdk:
      in: header
      name: X-Scanpay-Sdk
      schema:
        type: string
        example: scanandpay-node/0.4.0
      description: SDK identifier for support correlation.

  schemas:
    CreateSessionRequest:
      type: object
      required: [platformOrderId]
      description: One of `amountCents` or `amount` is also required.
      properties:
        merchantId:
          type: string
          description: |
            Optional. Your API Secret already identifies your merchant
            account; if you send this field, it must match.
        platformOrderId:
          type: string
          description: |
            Your unique order reference. Sending it again returns the
            existing session.
        amountCents:
          type: integer
          minimum: 1
          maximum: 100000000
          description: |
            Total in cents (e.g. `1990` for $19.90). Preferred over
            `amount`. One of `amountCents` or `amount` is required.
        amount:
          type: number
          format: float
          deprecated: true
          description: |
            Total in AUD dollars (e.g. `19.90`). Deprecated — use
            `amountCents`. Kept for backwards compat.
        payId:
          type: string
          deprecated: true
          description: Ignored. No merchant PayID is needed.
        merchantName:
          type: string
          deprecated: true
          description: Optional. Ignored by the server — the business name comes from your Business Portal profile, and no PayTo PayID is needed.
        currency:
          type: string
          enum: [AUD]
          default: AUD
        reference:
          type: string
          description: Customer-visible label.
        source:
          type: string
          enum: [api, woocommerce, pos, kiosk]
          default: api
          description: Used for reporting only.
        metadata:
          type: object
          additionalProperties:
            type: string
          maxProperties: 50
          description: |
            Up to 50 string key-value pairs (each key and value at most
            500 characters), returned in every response and webhook for
            the session.

    PaymentSession:
      type: object
      properties:
        success:
          type: boolean
        sessionId:
          type: string
          example: SP_SESS_abc123def456
        payUrl:
          type: string
          format: uri
          example: https://pay.scanandpay.com.au/p/SP_SESS_abc123def456
        qrUrl:
          type: string
          description: Base64 PNG data URI of the QR Pass — render directly in `<img src=...>`.
          example: 'data:image/png;base64,iVBORw0KGgo...'
        payId:
          type: [string, 'null']
          description: null for online payments.
          example: null
        amountCents:
          type: integer
        amount:
          type: number
          deprecated: true
        currency:
          type: string
          example: AUD
        reference:
          type: string
        status:
          $ref: '#/components/schemas/SessionStatus'
        ui_state:
          $ref: '#/components/schemas/UIState'
        expiresAt:
          type: string
          format: date-time
        metadata:
          type: object
          additionalProperties:
            type: string

    PaymentSessionStatus:
      allOf:
        - $ref: '#/components/schemas/PaymentSession'
        - type: object
          properties:
            createdAt:
              type: string
              format: date-time
              nullable: true
            paidAt:
              type: string
              format: date-time
              nullable: true
            merchantName:
              type: string

    SessionStatus:
      type: string
      enum: [WAITING, PAID, EXPIRED, FAILED]
      description: |
        - WAITING — customer hasn't paid yet
        - PAID — funds confirmed (terminal)
        - EXPIRED — 5-minute window elapsed (terminal)
        - FAILED — bank rejected or session aborted (terminal)

    UIState:
      type: string
      enum: [AMBER, GREEN, RED]

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string

  responses:
    BadRequest:
      description: Validation error — missing field, bad type, or out-of-range value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: |
        The X-Scanpay-Key header is missing, is not an API Secret, or
        holds a Secret that is no longer active.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: |
        The request names a different merchant from the one the API
        Secret belongs to, or the merchant subscription is not active.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MethodNotAllowed:
      description: Wrong HTTP method.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
