openapi: 3.0.3
info:
  title: GENERIC connector API
  version: "v0.1"

# ---------------------- PATHS ----------------------
paths:
  /accounts:
    get:
      summary: Get all accounts
      operationId: getAccounts
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/CreatedAtFrom'
      responses:
        200:
          $ref: '#/components/responses/Accounts'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /accounts/{accountId}/balances:
    get:
      summary: Get account balance
      operationId: getAccountBalances
      parameters:
        - $ref: '#/components/parameters/AccountId'
      responses:
        200:
          $ref: '#/components/responses/Balances'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /beneficiaries:
    get:
      summary: Get all beneficiaries
      operationId: getBeneficiaries
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/CreatedAtFrom'
      responses:
        200:
          $ref: '#/components/responses/Beneficiaries'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /transactions:
    get:
      summary: Get all transactions
      operationId: getTransactions
      parameters:
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/UpdatedAtFrom'
      responses:
        200:
          $ref: '#/components/responses/Transactions'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /payouts:
    post:
      summary: Create payout
      operationId: createPayout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutRequest'
      responses:
        201:
          $ref: '#/components/responses/PayoutResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /transfers:
    post:
      summary: Create transfer
      description: |
        Create an internal transfer between two accounts.
        The idempotencyKey should be used to prevent duplicate transfers on retries.
      operationId: createTransfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRequest'
      responses:
        201:
          $ref: '#/components/responses/TransferResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'

# ---------------------- COMPONENTS ----------------------
components:
  # ---------------------- PARAMETERS ----------------------
  parameters:
    AccountId:
      name: accountId
      in: path
      required: true
      schema:
        type: string
    PageSize:
      name: pageSize
      in: query
      description: Number of items per page
      example: 100
      schema:
        type: integer
        format: int64
        minimum: 1
        default: 100
    Page:
      name: page
      in: query
      description: Page number
      example: 1
      schema:
        type: integer
        format: int64
        minimum: 1
        default: 1
    Sort:
      name: sort
      in: query
      description: Sort order
      example: createdAt:asc
      schema:
        type: string
    CreatedAtFrom:
      name: createdAtFrom
      in: query
      description: Filter by created at date
      schema:
        type: string
        format: date-time
    UpdatedAtFrom:
      name: updatedAtFrom
      in: query
      description: Filter by updated at date
      schema:
        type: string
        format: date-time

  # ---------------------- RESPONSES ----------------------
  responses:
    NoContent:
      description: No content

    ErrorResponse:
      description: General error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    Accounts:
      description: List of accounts
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Account'

    Balances:
      description: Account balances
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Balances'

    Beneficiaries:
      description: List of beneficiaries
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Beneficiary'

    Transactions:
      description: List of transactions
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Transaction'

    PayoutResponse:
      description: Payout response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Payout'

    TransferResponse:
      description: Transfer response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Transfer'

  # ---------------------- SCHEMAS ----------------------
  schemas:
    Error:
      type: object
      required:
        - Title
        - Detail
      properties:
        Title:
          type: string
        Detail:
          type: string

    Account:
      type: object
      required:
        - id
        - accountName
        - createdAt
      properties:
        id:
          type: string
        accountName:
          type: string
        createdAt:
          type: string
          format: date-time
        metadata:
          $ref: '#/components/schemas/Metadata'

    Balances:
      type: object
      required:
        - id
        - accountID
        - at
        - balances
      properties:
        id:
          type: string
        accountID:
          type: string
        at:
          type: string
          format: date-time
        balances:
          type: array
          items:
            $ref: '#/components/schemas/Balance'

    Balance:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          description: Amount in minor units (integer string)
        currency:
          type: string
          description: Asset in UMN format with optional precision (e.g., "USD/2", "BTC/8", "COIN", "JPY")

    Beneficiary:
      type: object
      required:
        - id
        - createdAt
        - ownerName
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        ownerName:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'


    Transaction:
      type: object
      required:
        - id
        - createdAt
        - updatedAt
        - currency
        - type
        - status
        - amount
      properties:
        id:
          type: string
        relatedTransactionID:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        currency:
          type: string
          description: Asset in UMN format with optional precision (e.g., "USD/2", "BTC/8", "COIN", "JPY")
        scheme: 
          type: string
        type:
          $ref: '#/components/schemas/TransactionType'
        status:
          $ref: '#/components/schemas/TransactionStatus'
        amount:
          type: string
          description: Amount in minor units (integer string)
        sourceAccountID:
          type: string
        destinationAccountID:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'

    Metadata:
      type: object
      additionalProperties:
        type: string
      nullable: true

    TransactionType:
      type: string
      description: |
        Payment/transaction type. Core types are mapped to Formance payment types:
        - PAYIN: Incoming payment (maps to PAY-IN)
        - PAYOUT: Outgoing payment to external account (maps to PAYOUT)
        - TRANSFER: Internal transfer between accounts (maps to TRANSFER)
        - OTHER: Any other transaction type (maps to OTHER)
      enum:
        - PAYIN
        - PAYOUT
        - TRANSFER
        - OTHER

    TransactionStatus:
      type: string
      description: |
        Payment/transaction status. Mapped to Formance payment statuses:
        - PENDING: Payment is awaiting processing
        - SUCCEEDED: Payment completed successfully
        - FAILED: Payment failed
        - CANCELLED: Payment was cancelled
        - EXPIRED: Payment expired
        - REFUNDED: Payment was refunded
        - REFUNDED_FAILURE: Refund attempt failed
        - REFUND_REVERSED: Refund was reversed
        - DISPUTE: Payment is under dispute
        - DISPUTE_WON: Dispute resolved in merchant's favor
        - DISPUTE_LOST: Dispute resolved against merchant
        - AUTHORISATION: Payment authorized but not captured
        - CAPTURE: Payment captured
        - CAPTURE_FAILED: Capture attempt failed
        - OTHER: Other/unknown status
      enum:
        - PENDING
        - SUCCEEDED
        - FAILED
        - CANCELLED
        - EXPIRED
        - REFUNDED
        - REFUNDED_FAILURE
        - REFUND_REVERSED
        - DISPUTE
        - DISPUTE_WON
        - DISPUTE_LOST
        - AUTHORISATION
        - CAPTURE
        - CAPTURE_FAILED
        - OTHER

    PayoutRequest:
      type: object
      required:
        - idempotencyKey
        - amount
        - currency
        - sourceAccountId
        - destinationAccountId
      properties:
        idempotencyKey:
          type: string
          description: Unique identifier for the payout request
        amount:
          type: string
          description: Payout amount in minor units (integer string)
        currency:
          type: string
          description: Asset in UMN format (e.g., "USD/2", "BTC/8")
        sourceAccountId:
          type: string
          description: Source account identifier
        destinationAccountId:
          type: string
          description: Destination account identifier
        description:
          type: string
          description: Payout description
        metadata:
          $ref: '#/components/schemas/Metadata'

    Payout:
      type: object
      required:
        - id
        - idempotencyKey
        - amount
        - currency
        - sourceAccountId
        - destinationAccountId
        - status
        - createdAt
      properties:
        id:
          type: string
          description: Payout identifier
        idempotencyKey:
          type: string
          description: Unique identifier for the payout request
        amount:
          type: string
          description: Payout amount in minor units (integer string)
        currency:
          type: string
          description: Asset in UMN format (e.g., "USD/2", "BTC/8")
        sourceAccountId:
          type: string
          description: Source account identifier
        destinationAccountId:
          type: string
          description: Destination account identifier
        description:
          type: string
          description: Payout description
        status:
          $ref: '#/components/schemas/TransactionStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        metadata:
          $ref: '#/components/schemas/Metadata'

    TransferRequest:
      type: object
      required:
        - idempotencyKey
        - amount
        - currency
        - sourceAccountId
        - destinationAccountId
      properties:
        idempotencyKey:
          type: string
          description: |
            Client-provided unique identifier for this transfer request.
            Used for idempotency - if a transfer with this key already exists, return the existing transfer.
        amount:
          type: string
          description: Transfer amount in minor units (integer string)
        currency:
          type: string
          description: Asset in UMN format (e.g., "USD/2", "BTC/8")
        sourceAccountId:
          type: string
          description: Source account identifier (internal account)
        destinationAccountId:
          type: string
          description: Destination account identifier (internal account)
        description:
          type: string
          description: Transfer description/memo
        metadata:
          $ref: '#/components/schemas/Metadata'

    Transfer:
      type: object
      required:
        - id
        - idempotencyKey
        - amount
        - currency
        - sourceAccountId
        - destinationAccountId
        - status
        - createdAt
      properties:
        id:
          type: string
          description: PSP-generated unique transfer identifier
        idempotencyKey:
          type: string
          description: Client-provided unique identifier for this transfer request
        amount:
          type: string
          description: Transfer amount in minor units (integer string)
        currency:
          type: string
          description: Asset in UMN format (e.g., "USD/2", "BTC/8")
        sourceAccountId:
          type: string
          description: Source account identifier
        destinationAccountId:
          type: string
          description: Destination account identifier
        description:
          type: string
          description: Transfer description
        status:
          $ref: '#/components/schemas/TransactionStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        metadata:
          $ref: '#/components/schemas/Metadata'