openapi: 3.0.4
info:
  title: Norce Checkout - Avarda Checkout Adapter API
  description: >-
    Build 2026-01-09 07:29:55


    The Avarda Checkout Adapter API is used to create and manage a Avarda
    Checkout Order.
  version: 1.0.0
servers:
  - url: https://checkout-avarda-adapter.test.norce.tech
    description: Test server
paths:
  /api/checkout/v1/orders/{order_id}/payments:
    post:
      tags:
        - Payments
      summary: Initialize a new Avarda Checkout Session
      description: Requires an existing Norce order.
      operationId: InitializeAvardaCheckoutOrderPayment
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvardaCheckoutOrder'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json: {}
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - Bearer: []
  /api/checkout/v1/orders/{order_id}/payments/{payment_id}:
    get:
      tags:
        - Payments
      summary: Get Avarda Checkout Session
      description: >-
        Used to get the html snippet, for example after the Avarda Checkout
        Order has been confirmed.
      operationId: GetAvardaCheckoutOrderPayment
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvardaCheckoutOrder'
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/orders/{order_id}/payments/{payment_id}/remove:
    post:
      tags:
        - Payments
      summary: Remove an Avarda Checkout order
      description: >-
        Requires an existing Norce order. Will soft delete any payments and/or
        shipping by setting their respective state to removed. Will delete any
        hooks added when creating a Avarda Checkout order.
      operationId: RemoveAvardaCheckoutOrder
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/notification:
    post:
      tags:
        - Avarda Checkout Callbacks
      summary: Notification
      description: >-
        Consumes notification when a Avarda Checkout Order is completed or
        Invoice Status is updated
      operationId: Notification
      parameters:
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: merchant
          in: query
          description: Merchant identifier
          required: true
          schema:
            type: string
        - name: channel
          in: query
          description: Merchant channel
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/process:
    post:
      tags:
        - Avarda 'Client-side events' Callbacks
      summary: Process
      operationId: Process
      parameters:
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
        - name: x-merchant
          in: header
          description: Merchant identifier
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: Merchant channel
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvardaCheckoutValidationCustomError'
  /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/customer-update:
    post:
      tags:
        - Avarda 'Client-side events' Callbacks
      summary: Refresh customer information on norce order from Avarda order
      description: >-
        Updates customer information on norce order with latest customer
        information from Avarda
      operationId: UpdateCustomerFromAvarda
      parameters:
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: merchant
          in: query
          description: Merchant identifier
          required: true
          schema:
            type: string
        - name: channel
          in: query
          description: Merchant channel
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/shipping-option-update:
    post:
      tags:
        - Avarda 'Client-side events' Callbacks
      summary: >-
        Shipping option update. The norce order will be updated with the latest
        selected delivery information from Avarda
      description: >-
        Shipping option updated notifications. Will update the norce order with
        latest shipping selection from Avarda
      operationId: ShippingOptionUpdate
      parameters:
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: merchant
          in: query
          description: Merchant identifier
          required: true
          schema:
            type: string
        - name: channel
          in: query
          description: Merchant channel
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/cart-changed:
    post:
      tags:
        - Norce Callbacks
      summary: Handle Cart changed
      description: Cart changed.
      operationId: CartChanged
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      requestBody:
        description: Updated order
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/NorceOrder'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PatchOperation'
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/state-changed:
    post:
      tags:
        - Norce Callbacks
      summary: Handle State changed
      description: State changed.
      operationId: StateChanged
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      requestBody:
        description: Updated order
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/NorceOrder'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PatchOperation'
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/validate:
    post:
      tags:
        - Norce Callbacks
      summary: Validate
      operationId: Validate
      parameters:
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
        - name: x-merchant
          in: header
          description: Merchant identifier
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: Merchant channel
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - Bearer: []
  /api/order/v1/orders/{order_id}/payments/{payment_id}/refresh:
    post:
      tags:
        - Order Management
      summary: Refresh the list of available PaymentActions for an order
      description: >-
        Refreshes the list of available payment actions on the payment to
        reflect the current payment state
      operationId: Refresh
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/order/v1/orders/{order_id}/payments/{payment_id}/capture:
    post:
      tags:
        - Order Management
      summary: Capture order
      description: Used to capture order
      operationId: CaptureOrder
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/order/v1/orders/{order_id}/payments/{payment_id}/cancel:
    post:
      tags:
        - Order Management
      summary: Cancel order
      description: Used to cancel order
      operationId: CancelOrder
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/order/v1/orders/{order_id}/payments/{payment_id}/refund:
    post:
      tags:
        - Order Management
      summary: Refund order
      description: Used to refund order
      operationId: RefundOrder
      parameters:
        - name: x-merchant
          in: header
          description: |-
            Merchant identifier.
            <example>norce</example>
          required: true
          schema:
            type: string
        - name: x-channel
          in: header
          description: |-
            Channel identifier.
            <example>1</example>
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
        - name: payment_id
          in: path
          description: Payment identifier
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
components:
  schemas:
    Addon:
      type: object
      properties:
        reference:
          type: string
        price:
          type: number
          format: double
      additionalProperties: false
    Address:
      type: object
      properties:
        customerType:
          allOf:
            - $ref: '#/components/schemas/CustomerType'
        givenName:
          type: string
        familyName:
          type: string
        careOf:
          type: string
        reference:
          type: string
        organizationName:
          type: string
        streetAddress:
          type: string
        streetAddress2:
          type: string
        postalCode:
          type: string
        city:
          type: string
        region:
          type: string
        country:
          type: string
        phone:
          type: string
        email:
          type: string
        nationalIdentificationNumber:
          type: string
        organizationIdentificationNumber:
          type: string
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    AvardaCheckoutOrder:
      type: object
      properties:
        paymentId:
          type: string
        purchaseJwt:
          type: string
        javascriptUrl:
          type: string
        styles:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    AvardaCheckoutValidationCustomError:
      type: object
      properties:
        title:
          type: string
          description: >-
            The title of the validation failure displayed in the Checkout.
            Truncated to max 512 chars.
        message:
          type: string
          description: >-
            The message with a more descriptive text why the validation failed,
            and how the customer should proceed. Truncated to max 512 chars.
      additionalProperties: false
    Callback:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        adapterId:
          type: string
        event:
          allOf:
            - $ref: '#/components/schemas/CallbackEvent'
        url:
          type: string
      additionalProperties: false
    CallbackEvent:
      enum:
        - validate
        - accept
        - complete
      type: string
    Cart:
      type: object
      properties:
        reference:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        total:
          allOf:
            - $ref: '#/components/schemas/Price'
      additionalProperties: false
    Consent:
      type: object
      properties:
        id:
          type: string
        checked:
          type: boolean
        text:
          type: string
        required:
          type: boolean
      additionalProperties: false
    Customer:
      required:
        - type
      type: object
      properties:
        billing:
          allOf:
            - $ref: '#/components/schemas/Address'
        shipping:
          allOf:
            - $ref: '#/components/schemas/Address'
        type:
          allOf:
            - $ref: '#/components/schemas/CustomerType'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    CustomerType:
      enum:
        - person
        - organization
      type: string
    DeliveryDetails:
      type: object
      properties:
        carrier:
          type: string
        class:
          type: string
        product:
          allOf:
            - $ref: '#/components/schemas/Product'
        pickupLocation:
          allOf:
            - $ref: '#/components/schemas/PickupLocation'
      additionalProperties: false
    Discount:
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/DiscountType'
        name:
          type: string
        code:
          type: string
        value:
          allOf:
            - $ref: '#/components/schemas/Price'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    DiscountType:
      enum:
        - item
        - shipping
      type: string
    Error:
      type: object
      properties:
        code:
          enum:
            - internal-server-error
            - unauthorized
            - configuration-error
            - configuration-not-found
            - order-not-found
            - order-error
            - order-bad-request
            - order-conflict
            - order-validation
            - order-unknown-validation-error
            - shipping-not-found
            - shipping-error
            - payment-not-found
            - payment-error
            - avarda-error
            - avarda-order-expired
            - avarda-bad-request
            - avarda-validation
            - avarda-business-error
            - avarda-configuration
            - avarda-conflict
            - translation-not-found
            - translation-error
          type: string
          description: Error code
          example: cart-not-found
        message:
          type: string
          description: Detailed error information
          example: Cart with id:{id} now found.
      additionalProperties: false
    Hook:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        adapterId:
          type: string
        subscribeTo:
          type: string
        target:
          type: string
        invoke:
          type: string
      additionalProperties: false
    Item:
      type: object
      properties:
        id:
          type: string
        reference:
          type: string
        name:
          type: string
        sku:
          type: string
        url:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
          format: int32
        unit:
          type: string
        price:
          allOf:
            - $ref: '#/components/schemas/Price'
        total:
          allOf:
            - $ref: '#/components/schemas/Price'
        originalTotal:
          allOf:
            - $ref: '#/components/schemas/Price'
        vatRate:
          type: number
          format: double
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    NorceOrder:
      type: object
      properties:
        id:
          type: string
        merchant:
          type: string
        channel:
          type: string
        reference:
          type: string
        created:
          type: string
          format: date-time
        lastModified:
          type: string
          format: date-time
        state:
          allOf:
            - $ref: '#/components/schemas/State'
        culture:
          type: string
        currency:
          type: string
        country:
          type: string
        cart:
          allOf:
            - $ref: '#/components/schemas/Cart'
        shippings:
          type: array
          items:
            $ref: '#/components/schemas/Shipping'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        customer:
          allOf:
            - $ref: '#/components/schemas/Customer'
        consents:
          type: array
          items:
            $ref: '#/components/schemas/Consent'
        validations:
          type: array
          items:
            $ref: '#/components/schemas/Callback'
        hooks:
          type: array
          items:
            $ref: '#/components/schemas/Hook'
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/Notification'
        total:
          allOf:
            - $ref: '#/components/schemas/Price'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    Notification:
      type: object
      properties:
        id:
          type: string
        adapterId:
          type: string
        reference:
          type: string
        description:
          type: string
        scope:
          type: string
        schema:
          type: object
          additionalProperties:
            nullable: true
        invoke:
          type: string
      additionalProperties: false
    OrderStatus:
      enum:
        - checkout
        - processing
        - accepted
        - completed
        - declined
      type: string
    PatchOperation:
      type: object
      properties:
        op:
          type: string
        path:
          type: string
        value: {}
      additionalProperties: false
    Payment:
      type: object
      properties:
        id:
          type: string
        adapterId:
          type: string
        name:
          type: string
        merchant:
          type: string
        channel:
          type: string
        currency:
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/PaymentType'
        orderId:
          type: string
        amount:
          type: number
          format: double
        upperLimitAmount:
          type: number
          format: double
        state:
          allOf:
            - $ref: '#/components/schemas/PaymentState'
        reference:
          type: string
        attributes:
          type: object
          additionalProperties:
            nullable: true
        actions:
          type: array
          items:
            $ref: '#/components/schemas/PaymentAction'
      additionalProperties: false
    PaymentAction:
      type: object
      properties:
        id:
          type: string
        adapterId:
          type: string
        type:
          type: string
        url:
          type: string
      additionalProperties: false
    PaymentState:
      enum:
        - intent
        - removed
        - processing
        - failed
        - confirmed
        - pending
        - declined
        - reserved
        - credited
        - captured
        - cancelled
        - refunded
      type: string
    PaymentType:
      enum:
        - default
        - prepaid
        - voucher
      type: string
    PickupLocation:
      type: object
      properties:
        reference:
          type: string
        name:
          type: string
        address:
          allOf:
            - $ref: '#/components/schemas/ShippingAddress'
      additionalProperties: false
    Price:
      type: object
      properties:
        includingVat:
          type: number
          format: double
        excludingVat:
          type: number
          format: double
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
      additionalProperties: {}
    Product:
      type: object
      properties:
        reference:
          type: string
        name:
          type: string
      additionalProperties: false
    Shipping:
      type: object
      properties:
        id:
          type: string
        merchant:
          type: string
        channel:
          type: string
        reference:
          type: string
        tmsReference:
          type: string
        orderId:
          type: string
        adapterId:
          type: string
        name:
          type: string
        total:
          allOf:
            - $ref: '#/components/schemas/Price'
        vatRate:
          type: number
          format: double
        deliveryDetails:
          allOf:
            - $ref: '#/components/schemas/DeliveryDetails'
        addons:
          type: array
          items:
            $ref: '#/components/schemas/Addon'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    ShippingAddress:
      type: object
      properties:
        streetAddress:
          type: string
        city:
          type: string
        postalCode:
          type: string
        country:
          type: string
      additionalProperties: false
    State:
      type: object
      properties:
        currentStatus:
          allOf:
            - $ref: '#/components/schemas/OrderStatus'
        transitions:
          type: array
          items:
            $ref: '#/components/schemas/Transition'
          readOnly: true
      additionalProperties: false
    Transition:
      type: object
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/OrderStatus'
          readOnly: true
        timeStamp:
          type: string
          format: date-time
          readOnly: true
      additionalProperties: false
    ValidationError:
      type: object
      properties:
        code:
          type: string
        adapterId:
          type: string
      additionalProperties: false
  securitySchemes:
    Bearer:
      type: apiKey
      description: >-
        Authorization header using the bearer scheme. Example: 'Bearer
        a3bcdABCaB12abc3AbCDAB5AbcABCaBcABC5ab3c5A0='
      name: Authorization
      in: header
