openapi: 3.1.0
info:
  title: Sendico Payment API Contract
  version: 3.0.0
  summary: Minimal client contract for payment execution flows via BFF.
  description: |
    OpenAPI 3.1 contract focused on flows required to perform payments:
    authentication, verification, recipients, payment methods and payments.
servers:
  - url: /api/v1
    description: Main HTTP API base path

tags:
  - name: Auth
    description: Authentication and token lifecycle
  - name: Accounts
    description: Account auth responses used by login/verification
  - name: Verification
    description: Pending-account code verification
  - name: Organizations
    description: Organization selection for payment operations
  - name: Recipients
    description: Recipient CRUD and archive flows
  - name: Payment Methods
    description: Payment method CRUD and archive flows
  - name: Callbacks
    description: Webhook callback subscription CRUD and signing secret rotation
  - name: Payments
    description: Quotation and payment orchestration

paths:
  /accounts/login:
    $ref: ./api/accounts/auth_login.yaml
  /accounts/login/api:
    $ref: ./api/accounts/auth_login_api.yaml
  /accounts/rotate:
    $ref: ./api/accounts/auth_rotate.yaml
  /accounts/refresh:
    $ref: ./api/accounts/auth_refresh.yaml

  /verification:
    $ref: ./api/verification/create.yaml
  /verification/resend:
    $ref: ./api/verification/resend.yaml
  /verification/verify:
    $ref: ./api/verification/verify.yaml

  /organizations:
    $ref: ./api/organizations/root.yaml
  /organizations/{org_ref}:
    $ref: ./api/organizations/get.yaml

  /recipients/list/{org_ref}/{organizations_ref}:
    $ref: ./api/recipients/list.yaml
  /recipients/{org_ref}:
    $ref: ./api/recipients/create.yaml
  /recipients/{recipients_ref}:
    $ref: ./api/recipients/object.yaml
  /recipients:
    $ref: ./api/recipients/update.yaml
  /recipients/archive/{org_ref}/{recipients_ref}:
    $ref: ./api/recipients/archive.yaml

  /payment_methods/list/{organizations_ref}/{recipients_ref}:
    $ref: ./api/payment_methods/list.yaml
  /payment_methods/{organizations_ref}:
    $ref: ./api/payment_methods/create.yaml
  /payment_methods/{payment_methods_ref}:
    $ref: ./api/payment_methods/object.yaml
  /payment_methods:
    $ref: ./api/payment_methods/update.yaml
  /payment_methods/archive/{organizations_ref}/{payment_methods_ref}:
    $ref: ./api/payment_methods/archive.yaml

  /callbacks/list/{org_ref}/{organizations_ref}:
    $ref: ./api/callbacks/list.yaml
  /callbacks/{org_ref}:
    $ref: ./api/callbacks/create.yaml
  /callbacks/{callbacks_ref}:
    $ref: ./api/callbacks/object.yaml
  /callbacks:
    $ref: ./api/callbacks/update.yaml
  /callbacks/archive/{org_ref}/{callbacks_ref}:
    $ref: ./api/callbacks/archive.yaml
  /callbacks/rotate-secret/{callbacks_ref}:
    $ref: ./api/callbacks/rotate_secret.yaml

  /payments/quote/{organizations_ref}:
    $ref: ./api/payments/quote.yaml
  /payments/multiquote/{organizations_ref}:
    $ref: ./api/payments/multiquote.yaml
  /payments/by-quote/{organizations_ref}:
    $ref: ./api/payments/by_quote.yaml
  /payments/by-multiquote/{organizations_ref}:
    $ref: ./api/payments/by_multiquote.yaml
  /payments/{organizations_ref}:
    $ref: ./api/payments/list.yaml

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT