openapi: 3.0.3
info:
  title: Payment Connector Contract - Capture
  description:
    Recommended pattern for building the capture flow of a connector between a Payment Service Providers and the Fluent platform.
  version: 1.0.0
paths:
  /connector:
    description: Webhooks recieved by the connector
    post:
      summary: Payment Connector webhook receiver
      tags:
        - Connector
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/payment-capture-request'
      responses:
        200:
          description: "Successful Operation"
        500:
          description: "Server-side error, please retry later"
      servers:
        - description: The custom connector instance (not a Fluent API URL)
          url: https://example.com
  /api/v4.1/event/async:
    post:
      summary: Payment Capture response event
      tags:
        - Fluent Commerce
      security:
        - BearerAuth: [admin]   # Use OAuth with a different scope
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/payment-capture-success'
                - $ref: '#/components/schemas/payment-capture-error'
      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: 'INVOICE'
        entityId:
          type: string
        entityRef:
          type: string
        rootEntityType:
          type: string
          pattern: 'BILLING_ACCOUNT'
        rootEntityId:
          type: string
        rootEntityRef:
          type: string
        attributes:
          type: object
          required: [transactionRef]
          properties:
            transactionRef:
              type: string
    payment-capture-request:
      type: object
      title: Payment Capture Request
      description: Describes the payload of payment authorise request
      allOf:
        - $ref: '#/components/schemas/event-base'
      properties:
        name:
          type: string
          pattern: fc\.connect\.payment\.capture
    payment-capture-success:
      type: object
      title: Payment Capture Response (Success)
      description: Register a payment capture success
      allOf:
        - $ref: '#/components/schemas/event-base'
      properties:
        name:
          type: string
          pattern: fc\.connect\.payment\.capture\.success
    payment-capture-error:
      type: object
      title: Payment Capture Response (Error)
      description: Register a payment capture error
      allOf:
        - $ref: '#/components/schemas/event-base'
      properties:
        name:
          type: string
          pattern: fc\.connect\.payment\.authorise\.error
        attributes:
          type: object
          required: [transactionRef, errorCode]
          properties:
            transactionRef:
              type: string
            errorCode:
              type: string
            errorMessage:
              type: string


