openapi: 3.0.3
info:
  title: Order Connector Contract - Add Payment
  description:
    Recommended pattern for building the add payment flow of a connector between a ecommerce software and the Fluent platform.
  version: 1.0.0
paths:
  /api/v4.1/event/async:
    post:
      summary: Add Payment Event
      tags:
        - Fluent Commerce
      security:
        - BearerAuth: [admin]   # Use OAuth with a different scope
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/add-payment-request'
      responses:
        200:
          description: "Successful Operation"
        401:
          description: "Authorization Error - Invalid Bearer Token / No permission"
        400:
          description: "Client Error - Bad Request"
      servers:
        - description: Fluent Commerce Sandbox
          url: https://{account}.sandbox.api.fluentretail.com
          variables:
            account:
              default: fluent
              description: The name of the Fluent account
        - description: Fluent Commerce Production
          url: https://{account}.api.fluentretail.com
          variables:
            account:
              default: fluent
              description: The name of the Fluent account
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    event-base:
      title: Event
      type: object
      required: [name, retailerId, entityType, entityId, entityRef, rootEntityType, rootEntityId, rootEntityRef]
      properties:
        name:
          type: string
        retailerId:
          type: string
        entityType:
          type: string
          pattern: 'PRODUCT_CATALOGUE'
        entityId:
          type: string
        entityRef:
          type: string
        rootEntityType:
          type: string
          pattern: 'PRODUCT_CATALOGUE'
        rootEntityId:
          type: string
        rootEntityRef:
          type: string
    add-payment-request:
      type: object
      title: Add Payment Request
      description: Describes the payload of an add payment event
      allOf:
        - $ref: '#/components/schemas/event-base'
      properties:
        name:
          type: string
          pattern: fc\.connect\.order\.add-payment
        attributes:
          type: object
          properties:
            financialTransaction:
              $ref: '#/components/schemas/financial-transaction'

    financial-transaction:
      title: Financial Transaction
      description: Order Financial Transaction
      required: [
        "ref", "amount", "payment-service-provider-ref", "payment-method"
      ]
      properties:
        ref:
          type: string
          description: The reference identifier used to identify the payment transaction
          nullable: false
        type:
          type: string
          description: Type of the payment
          nullable: false
        status:
          type: string
          description: Status of the payment
          nullable: true
        amount:
          type: number
          format: double
          description: Transaction Amount
          nullable: true
        currencyCode:
          type: string
          description: Transaction currency in ISO format
          nullable: true
        paymentRef:
          type: string
          description: TODO
          nullable: true
        paymentServiceProviderRef:
          type: string
          description: Payment provider ID
          nullable: true
        authorizationKey:
          type: string
          description: TODO
          nullable: true
        cardType:
          type: string
          description: Cart type
          nullable: true
        paymentMethod:
          type: string
          nullable: true
