openapi: 3.0.4
info:
  title: Norce Checkout - Awardit Adapter API
  description: >-
    Build 2026-01-09 08:52:28


    The Awardit Adapter API is used to create and manage a Awardit Checkout
    Order.
  version: 1.0.0
servers:
  - url: >-
      https://awardit-adapter.checkout.playground.norce.tech/checkout/awardit-adapter
    description: Public
  - url: https://awardit-adapter.checkout.test.internal.norce.tech
    description: Internal Test
  - url: https://awardit-adapter.checkout.playground.internal.norce.tech
    description: Internal Playground
  - url: https://awardit-adapter.checkout.stage.internal.norce.tech
    description: Internal Stage
  - url: https://awardit-adapter.checkout.prod.internal.norce.tech
    description: Internal Production
paths:
  /api/checkout/v1/orders/{order_id}/payments:
    post:
      tags:
        - Payments
      summary: Create a new Awardit giftcard
      description: Requires an existing Norce order.
      operationId: CreateAwarditPayment
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - name: order_id
          in: path
          description: Order identifier
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/GiftCard'
        required: true
      responses:
        '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}/remove:
    post:
      tags:
        - Payments
      summary: Remove a Awardit giftcard
      description: >-
        Requires an existing Norce order. Will do soft delete on any payments or
        shippings by setting state to removed. Will delete any hooks added when
        creating an Awardit payment.
      operationId: RemoveAwarditPayment
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - 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:
        '204':
          description: No Content
        '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}/state-changed:
    post:
      tags:
        - Norce Callbacks
      summary: Handle state changed
      description: State changed.
      operationId: StateChanged
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - 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'
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/callback/orders/{order_id}/payments/{payment_id}/update-payment:
    post:
      tags:
        - Norce Callbacks
      summary: Update payment amount in response to changes
      description: Hook on changes to update payment.
      operationId: UpdatePayment
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - 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'
        '400':
          description: Bad Request
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
      security:
        - Bearer: []
  /api/checkout/v1/orders/{order_id}/payments/{payment_id}/commit:
    post:
      tags:
        - Norce Notifications
      summary: Commit awardit transaction on authorized gift card
      description: Notification registered on order. Triggered by order status Completed.
      operationId: CommitAwarditPayment
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - 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: Completed order
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/NorceOrder'
      responses:
        '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}/cancel:
    post:
      tags:
        - Norce Notifications
      summary: >-
        Cancel awardit transaction on order changing back to "checkout" state
        with an authorized gift card
      description: Notification registered on order. Triggered by order status Checkout.
      operationId: CancelAwarditPayment
      parameters:
        - name: x-merchant
          in: header
          description: Merchant identifier.
          required: true
          schema:
            type: string
            example: norce
          example: norce
        - name: x-channel
          in: header
          description: Channel identifier
          required: true
          schema:
            type: string
            example: '1'
          example: '1'
        - 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: Order in checkout state
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/NorceOrder'
      responses:
        '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: []
components:
  schemas:
    Addon:
      type: object
      properties:
        reference:
          type: string
        price:
          type: number
          format: double
      additionalProperties: false
    Address:
      type: object
      properties:
        type:
          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
    AwarditError:
      type: object
      properties:
        errorCode:
          type: string
        errorMessages:
          type: array
          items:
            type: string
        correlationId:
          type: string
      additionalProperties: false
    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'
        attributes:
          type: object
          additionalProperties:
            nullable: true
      additionalProperties: false
    Consent:
      type: object
      properties:
        id:
          type: string
        checked:
          type: boolean
        text:
          type: string
        required:
          type: boolean
      additionalProperties: false
    Customer:
      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
            - payment-conflict
            - awardit-error
            - awardit-bad-request
            - awardit-validation
            - awardit-card-not-found
            - awardit-missing-pin
            - awardit-card-empty
            - translation-not-found
          type: string
          description: Error code
          example: cart-not-found
        message:
          type: string
          description: Detailed error information
          example: Cart with id:{id} now found.
        awarditError:
          allOf:
            - $ref: '#/components/schemas/AwarditError'
          description: Error if originating from Resurs Bank
      additionalProperties: false
    GiftCard:
      type: object
      properties:
        cardId:
          type: string
        code:
          type: string
      additionalProperties: false
    Hook:
      type: object
      properties:
        id:
          type: string
        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'
        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
        delay:
          type: integer
          format: int32
      additionalProperties: false
    OrderStatus:
      enum:
        - checkout
        - processing
        - accepted
        - completed
        - declined
        - removed
      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
      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/PickupLocationAddress'
      additionalProperties: false
    PickupLocationAddress:
      type: object
      properties:
        streetAddress:
          type: string
        city:
          type: string
        postalCode:
          type: string
        country:
          type: string
      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
        state:
          allOf:
            - $ref: '#/components/schemas/ShippingState'
        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
    ShippingState:
      enum:
        - intent
        - removed
        - processing
        - failed
        - confirmed
      type: string
    State:
      type: object
      properties:
        currentStatus:
          allOf:
            - $ref: '#/components/schemas/OrderStatus'
        transitions:
          type: array
          items:
            $ref: '#/components/schemas/Transition'
      additionalProperties: false
    Transition:
      type: object
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/OrderStatus'
        timeStamp:
          type: string
          format: date-time
      additionalProperties: false
  securitySchemes:
    Bearer:
      type: apiKey
      description: >-
        Authorization header using the bearer scheme. Example: 'Bearer
        a3bcdABCaB12abc3AbCDAB5AbcABCaBcABC5ab3c5A0='
      name: Authorization
      in: header
