openapi: 3.1.0
info:
  title: Sendico API Contract
  version: 4.2.37
  summary: Minimal client contract for authenticated BFF flows.
  description: |
    OpenAPI 3.1 contract focused on authenticated client flows exposed by the BFF:
    authentication, verification, recipients, payment methods, payments, wallets,
    and ledger account history.
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 material rotation for HMAC and detached-JWS callbacks
  - name: Payments
    description: Quotation and payment orchestration
  - name: Wallets
    description: Managed wallet metadata and balances
  - name: Ledger Accounts
    description: Ledger account balances and account-history operations

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/accounts/{organizations_ref}/{accounts_ref}:
    $ref: ./api/payment_methods/accounts.yaml
  /payment_methods/recipients/{organizations_ref}/{recipients_ref}:
    $ref: ./api/payment_methods/recipients.yaml
  /payment_methods/{organizations_ref}/{payment_methods_ref}:
    $ref: ./api/payment_methods/object.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/immediate/{organizations_ref}:
    $ref: ./api/payments/immediate.yaml
  /payments/by-quote/{organizations_ref}:
    $ref: ./api/payments/by_quote.yaml
  /payments/by-multiquote/{organizations_ref}:
    $ref: ./api/payments/by_multiquote.yaml
  /payments/by-ref/{payments_ref}:
    $ref: ./api/payments/object.yaml
  /payments/{organizations_ref}:
    $ref: ./api/payments/list.yaml
  /payments/documents/certificate/{organizations_ref}:
    $ref: ./api/payments/documents_certificate.yaml
  /payments/registry/{organizations_ref}:
    $ref: ./api/payments/registry.yaml
  /payments/registry/refresh/{organizations_ref}:
    $ref: ./api/payments/registry_refresh.yaml
  /payments/fx/currencies/{organizations_ref}:
    $ref: ./api/payments/fx_currencies.yaml
  /payments/fx/directions/{organizations_ref}:
    $ref: ./api/payments/fx_directions.yaml
  /chain_wallets/{organizations_ref}/assets:
    $ref: ./api/wallets/assets.yaml
  /ledger_accounts/{organizations_ref}/{ledger_account_ref}/balance:
    $ref: ./api/ledger_accounts/balance.yaml
  /ledger_accounts/{organizations_ref}/{ledger_account_ref}/operations:
    $ref: ./api/ledger_accounts/operations.yaml
  /ledger_accounts/{organizations_ref}/{ledger_account_ref}/operations/{entry_ref}:
    $ref: ./api/ledger_accounts/operation.yaml

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