openapi: 3.1.0
info:
  title: Axiym Account API
  version: 0.2.0
  description: >-
    API reference for organizations using the Account API. This API exposes a limited surface for authentication,
    account visibility, whitelisted own account visibility, outbound withdrawals, and webhook subscription
    management. `POST /withdrawals` addresses the destination by `destinationId` — the
    identifier of one of your registered whitelisted own accounts.
servers:
  - url: https://partner-api.sandbox.axiym.io/api/v1
    description: Sandbox
  - url: https://partner-api.axiym.io/api/v1
    description: Production
security:
  - Default: []
tags:
  - name: Auth
    description: OAuth 2.0 client credentials authentication.
  - name: Accounts
    description: Accessible accounts and balances.
  - name: Whitelisted Own Accounts
    description: Payment destinations (bank accounts, wallet addresses).
  - name: Withdrawals
    description: Outgoing payments to registered whitelisted own accounts.
  - name: Webhook Subscriptions
    description: Webhook subscription management and webhook public keys.
paths:
  /oauth/token:
    post:
      summary: Get new access token
      deprecated: false
      tags:
        - Auth
      parameters:
        - $ref: "#/components/parameters/RequestId"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  examples:
                    - eb81336d-378a-4ab8-8c0e-a2f39ac0e87a
                  example: eb81336d-378a-4ab8-8c0e-a2f39ac0e87a
                client_secret:
                  type: string
                  examples:
                    - >-
                      d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120
                  example: >-
                    d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120
                grant_type:
                  type: string
                  examples:
                    - client_credentials
                  example: client_credentials
                scope:
                  type: string
                  enum:
                    - WITHDRAWAL
                  examples:
                    - WITHDRAWAL
                  example: WITHDRAWAL
            example:
              client_id: eb81336d-378a-4ab8-8c0e-a2f39ac0e87a
              client_secret: >-
                d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120
              grant_type: client_credentials
              scope: WITHDRAWAL
        required: true
      responses:
        "201":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  token_type:
                    type: string
                  expires_in:
                    type: integer
                  access_token:
                    type: string
                  scope:
                    type: string
                required:
                  - token_type
                  - expires_in
                  - access_token
                  - scope
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: ""
        "500":
          $ref: "#/components/responses/InternalError"
          description: ""
      security: []
  /accounts:
    get:
      tags:
        - Accounts
      summary: List Accounts
      operationId: listAccounts
      parameters:
        - $ref: "#/components/parameters/RequestId"
        - name: first
          in: query
          description: Maximum number of accounts to return.
          required: false
          schema:
            type: integer
            default: 10
            maximum: 100
            examples:
              - 10
        - name: currency
          in: query
          schema:
            $ref: "#/components/schemas/Currency"
            examples:
              - USD
          description: Filter by currency.
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/AccountStatus"
            examples:
              - ACTIVE
          description: Filter by status.
      responses:
        "200":
          description: Accounts.
          content:
            application/json:
              schema:
                type: object
                required:
                  - nodes
                properties:
                  nodes:
                    type: array
                    items:
                      $ref: "#/components/schemas/Account"
              examples:
                Accounts:
                  summary: Accounts
                  value:
                    nodes:
                      - accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
                        currency: USD
                        paymentRails: SWIFT
                        balance: "48250.00"
                        status: ACTIVE
                      - accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
                        currency: USDT
                        paymentRails: TRON
                        balance: "12500.00"
                        status: ACTIVE
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /accounts/{accountId}:
    get:
      tags:
        - Accounts
      summary: Get an Account
      operationId: getAccount
      parameters:
        - $ref: "#/components/parameters/AccountId"
        - $ref: "#/components/parameters/RequestId"
      responses:
        "200":
          description: Account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
              examples:
                Account:
                  summary: Account
                  value:
                    accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
                    currency: USD
                    paymentRails: SWIFT
                    balance: "48250.00"
                    status: ACTIVE
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /accounts/{accountId}/statement:
    get:
      tags:
        - Accounts
      summary: Get an Account Statement
      operationId: getAccountStatement
      description: >-
        Period-scoped ledger statement for a single account: opening/closing aggregates plus the
        posted movements in posting order. The statement is self-checking —
        `openingBalance` plus `totalCredited` minus `totalDebited` equals `closingBalance`, and
        each entry carries the running balance. Without `from`/`to` the statement covers the whole
        account history.
      parameters:
        - $ref: "#/components/parameters/AccountId"
        - $ref: "#/components/parameters/RequestId"
        - $ref: "#/components/parameters/First"
        - $ref: "#/components/parameters/After"
        - name: from
          in: query
          required: false
          description: >-
            First calendar day of the period (UTC), inclusive. The period bounds apply to the
            posting time of the movement.
          schema:
            type: string
            format: date
            examples:
              - "2026-06-01"
        - name: to
          in: query
          required: false
          description: >-
            Last calendar day of the period (UTC), inclusive. Adjacent statements chain without
            gaps: June `to=2026-06-30` is followed by July `from=2026-07-01`.
          schema:
            type: string
            format: date
            examples:
              - "2026-06-30"
        - name: type
          in: query
          required: false
          description: Filter by credit or debit direction.
          schema:
            $ref: "#/components/schemas/StatementEntryType"
            examples:
              - DEBIT
      responses:
        "200":
          description: Account statement for the period.
          content:
            application/json:
              schema:
                type: object
                required:
                  - openingBalance
                  - closingBalance
                  - totalCredited
                  - totalDebited
                  - nodes
                  - pageInfo
                properties:
                  openingBalance:
                    allOf:
                      - $ref: "#/components/schemas/Decimal"
                    description: Balance as of the start of the period (`from`).
                    examples:
                      - "47750.00"
                  closingBalance:
                    allOf:
                      - $ref: "#/components/schemas/Decimal"
                    description: Balance as of the end of the period (`to`).
                    examples:
                      - "48250.00"
                  totalCredited:
                    allOf:
                      - $ref: "#/components/schemas/Decimal"
                    description: Sum of credits within the period.
                    examples:
                      - "1005.00"
                  totalDebited:
                    allOf:
                      - $ref: "#/components/schemas/Decimal"
                    description: Sum of debits within the period.
                    examples:
                      - "505.00"
                  nodes:
                    type: array
                    items:
                      $ref: "#/components/schemas/StatementEntry"
                  pageInfo:
                    $ref: "#/components/schemas/PageInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /whitelisted-own-accounts:
    get:
      tags:
        - Whitelisted Own Accounts
      summary: List Whitelisted Own Accounts
      operationId: listWhitelistedOwnAccounts
      parameters:
        - $ref: "#/components/parameters/RequestId"
        - $ref: "#/components/parameters/First"
        - $ref: "#/components/parameters/After"
        - name: currency
          in: query
          schema:
            $ref: "#/components/schemas/Currency"
            examples:
              - USD
          description: Filter by currency.
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/DestinationStatus"
            examples:
              - ACTIVE
          description: Filter by status.
      responses:
        "200":
          description: Page of whitelisted own accounts.
          content:
            application/json:
              schema:
                type: object
                required:
                  - nodes
                  - pageInfo
                properties:
                  nodes:
                    type: array
                    items:
                      $ref: "#/components/schemas/Destination"
                  pageInfo:
                    $ref: "#/components/schemas/PageInfo"
              examples:
                Whitelisted own accounts:
                  summary: A bank account and a wallet address
                  value:
                    nodes:
                      - destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        status: ACTIVE
                        currency: USD
                        accountNumber: "0123456789"
                        swiftBic: BOFAUS3NXXX
                        bankName: Bank of America
                        createdAt: "2026-06-12T14:05:00Z"
                      - destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
                        status: ACTIVE
                        currency: USDT
                        walletAddress: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL
                        network: TRON
                        createdAt: "2026-06-12T14:05:00Z"
                    pageInfo:
                      hasNextPage: false
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /whitelisted-own-accounts/bank:
    post:
      tags:
        - Whitelisted Own Accounts
      summary: Register a Bank Account
      operationId: createBankDestination
      description: >-
        Register an external bank account owned by the authenticated partner. Third-party accounts
        are not allowed. A newly registered account starts in `PENDING_REVIEW`; after it becomes
        `ACTIVE`, it can receive withdrawals. The `destination.activated` webhook reports this
        change.
      parameters:
        - $ref: "#/components/parameters/RequestId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BankDestinationRequest"
      responses:
        "201":
          description: Whitelisted own bank account registered and awaiting review.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Destination"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /whitelisted-own-accounts/wallet:
    post:
      tags:
        - Whitelisted Own Accounts
      summary: Register a Wallet Address
      operationId: createWalletDestination
      description: >-
        Register an external wallet owned by the authenticated partner. Third-party wallets are
        not allowed. A newly registered wallet starts in `PENDING_REVIEW`; after it becomes
        `ACTIVE`, it can receive withdrawals. The `destination.activated` webhook reports this
        change.
      parameters:
        - $ref: "#/components/parameters/RequestId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WalletDestinationRequest"
      responses:
        "201":
          description: Whitelisted own wallet registered and awaiting review.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Destination"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /whitelisted-own-accounts/{destinationId}:
    get:
      tags:
        - Whitelisted Own Accounts
      summary: Get a Whitelisted Own Account
      operationId: getWhitelistedOwnAccount
      parameters:
        - $ref: "#/components/parameters/DestinationId"
        - $ref: "#/components/parameters/RequestId"
      responses:
        "200":
          description: Whitelisted own account.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Destination"
              examples:
                Bank account:
                  summary: Bank account
                  value:
                    destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    status: ACTIVE
                    currency: USD
                    accountNumber: "0123456789"
                    swiftBic: BOFAUS3NXXX
                    bankName: Bank of America
                    createdAt: "2026-06-12T14:05:00Z"
                Wallet address:
                  summary: Wallet address
                  value:
                    destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
                    status: ACTIVE
                    currency: USDT
                    walletAddress: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL
                    network: TRON
                    createdAt: "2026-06-12T14:05:00Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /withdrawals:
    get:
      tags:
        - Withdrawals
      summary: List Withdrawals
      operationId: listWithdrawals
      parameters:
        - $ref: "#/components/parameters/RequestId"
        - $ref: "#/components/parameters/First"
        - $ref: "#/components/parameters/After"
        - name: accountId
          in: query
          description: Filter by account.
          schema:
            type: string
            format: uuid
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/WithdrawalStatus"
            examples:
              - PENDING
          description: Filter by status.
        - name: externalReference
          in: query
          description: Filter by your external reference.
          schema:
            type: string
            examples:
              - acme-ref-00417
      responses:
        "200":
          description: Page of withdrawals.
          content:
            application/json:
              schema:
                type: object
                required:
                  - nodes
                  - pageInfo
                properties:
                  nodes:
                    type: array
                    items:
                      $ref: "#/components/schemas/Withdrawal"
                  pageInfo:
                    $ref: "#/components/schemas/PageInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      tags:
        - Withdrawals
      summary: Create a Withdrawal
      operationId: createWithdrawal
      description: >-
        Create an outgoing payment from `sourceAccountId`. `destinationId` selects one of your
        registered whitelisted own accounts. It must be `ACTIVE` and in the source account's
        currency — an unknown destination or a whitelisted own account in any other status
        rejects the request. The response embeds the resolved whitelisted own account in full.
      parameters:
        - $ref: "#/components/parameters/RequestId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WithdrawalRequest"
            examples:
              Wallet:
                summary: Wallet
                value:
                  sourceAccountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
                  amount: "500.00"
                  destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
              Bank:
                summary: Bank
                value:
                  sourceAccountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
                  amount: "12500.00"
                  destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        "201":
          description: Withdrawal created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Withdrawal"
              examples:
                Wallet:
                  summary: Wallet
                  value:
                    withdrawalId: 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
                    status: PENDING
                    sourceAccount:
                      accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
                      currency: USDT
                      paymentRails: TRON
                    amount: "500.00"
                    feeAmount: "5.00"
                    currency: USDT
                    destination:
                      destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
                      status: ACTIVE
                      currency: USDT
                      walletAddress: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL
                      network: TRON
                      createdAt: "2026-06-12T14:05:00Z"
                    code: AXI00000418
                    purpose: Treasury sweep
                    externalReference: wd-2026-0714-01
                    createdAt: "2026-07-14T20:06:50Z"
                Bank:
                  summary: Bank
                  value:
                    withdrawalId: 1e7c5a3b-8d2f-4b6e-9a0c-3d5f7b9e1c2a
                    status: PENDING
                    sourceAccount:
                      accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
                      currency: USD
                      paymentRails: SWIFT
                    amount: "12500.00"
                    feeAmount: "25.00"
                    currency: USD
                    destination:
                      destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      status: ACTIVE
                      currency: USD
                      accountNumber: "0123456789"
                      swiftBic: BOFAUS3NXXX
                      bankName: Bank of America
                      createdAt: "2026-06-12T14:05:00Z"
                    code: AXI00000419
                    purpose: Invoice INV-20416
                    externalReference: wd-2026-0714-02
                    createdAt: "2026-07-14T20:06:50Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /withdrawals/{withdrawalId}:
    get:
      tags:
        - Withdrawals
      summary: Get a Withdrawal
      operationId: getWithdrawal
      parameters:
        - $ref: "#/components/parameters/WithdrawalId"
        - $ref: "#/components/parameters/RequestId"
      responses:
        "200":
          description: Withdrawal.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Withdrawal"
              examples:
                Wallet (completed):
                  summary: Wallet (completed)
                  value:
                    withdrawalId: 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
                    status: COMPLETED
                    sourceAccount:
                      accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
                      currency: USDT
                      paymentRails: TRON
                    amount: "500.00"
                    feeAmount: "5.00"
                    currency: USDT
                    destination:
                      destinationId: e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
                      status: ACTIVE
                      currency: USDT
                      walletAddress: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL
                      network: TRON
                      createdAt: "2026-06-12T14:05:00Z"
                    code: AXI00000418
                    transactionHash: "0x9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00"
                    externalReference: wd-2026-0714-01
                    createdAt: "2026-07-14T20:06:50Z"
                Bank (completed):
                  summary: Bank (completed)
                  value:
                    withdrawalId: 1e7c5a3b-8d2f-4b6e-9a0c-3d5f7b9e1c2a
                    status: COMPLETED
                    sourceAccount:
                      accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
                      currency: USD
                      paymentRails: SWIFT
                    amount: "12500.00"
                    feeAmount: "25.00"
                    currency: USD
                    destination:
                      destinationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      status: ACTIVE
                      currency: USD
                      accountNumber: "0123456789"
                      swiftBic: BOFAUS3NXXX
                      bankName: Bank of America
                      createdAt: "2026-06-12T14:05:00Z"
                    code: AXI00000419
                    externalReference: wd-2026-0714-02
                    createdAt: "2026-07-14T20:06:50Z"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/InvalidParams"
        "500":
          $ref: "#/components/responses/InternalError"
  /webhooks/subscriptions:
    get:
      summary: List all Subscriptions
      deprecated: false
      tags:
        - Webhook Subscriptions
      parameters:
        - $ref: "#/components/parameters/RequestId"
        - name: first
          in: query
          description: Maximum number of items to return (page size).
          required: false
          schema:
            type: integer
            default: 10
            maximum: 100
            examples:
              - 20
        - name: after
          in: query
          description: Cursor for the next page, from the previous response's pageInfo.endCursor.
          required: false
          schema:
            type: string
            examples:
              - eyJvZmZzZXQiOjI1fQ==
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodes:
                    type: array
                    items:
                      $ref: "#/components/schemas/Subscription"
                  pageInfo:
                    $ref: "#/components/schemas/PageInfo"
                required:
                  - nodes
                  - pageInfo
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: ""
        "403":
          $ref: "#/components/responses/Forbidden"
          description: Forbidden
        "422":
          $ref: "#/components/responses/InvalidParams"
          description: ""
        "500":
          $ref: "#/components/responses/InternalError"
          description: ""
      security:
        - Default: []
    post:
      summary: Create Subscription
      deprecated: false
      tags:
        - Webhook Subscriptions
      parameters:
        - $ref: "#/components/parameters/RequestId"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                endpoint:
                  type: string
                  title: ""
                  description: >-
                    URL of the endpoint to subscribe to notifications. Must be publicly accessible,
                    use HTTPS, and respond with a 2XX status to a POST request.
              required:
                - endpoint
      responses:
        "201":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: ""
        "403":
          $ref: "#/components/responses/Forbidden"
          description: Forbidden
        "422":
          $ref: "#/components/responses/InvalidParams"
          description: ""
        "500":
          $ref: "#/components/responses/InternalError"
          description: ""
      security:
        - Default: []
  /webhooks/subscriptions/{subscriptionId}/tests:
    post:
      summary: Test Subscription
      deprecated: false
      tags:
        - Webhook Subscriptions
      parameters:
        - name: subscriptionId
          in: path
          description: Subscription identifier (UUID).
          required: true
          schema:
            type: string
            examples:
              - ""
        - $ref: "#/components/parameters/RequestId"
      responses:
        "201":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestStatus"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: ""
        "403":
          $ref: "#/components/responses/Forbidden"
          description: Forbidden
        "404":
          $ref: "#/components/responses/NotFound"
          description: ""
        "422":
          $ref: "#/components/responses/InvalidParams"
          description: ""
        "500":
          $ref: "#/components/responses/InternalError"
          description: ""
      security:
        - Default: []
  /webhooks/subscriptions/{subscriptionId}:
    delete:
      summary: Disable Subscription
      deprecated: false
      tags:
        - Webhook Subscriptions
      parameters:
        - name: subscriptionId
          in: path
          description: Subscription identifier (UUID).
          required: true
          schema:
            type: string
            format: uuid
            examples:
              - ""
        - $ref: "#/components/parameters/RequestId"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: ""
        "403":
          $ref: "#/components/responses/Forbidden"
          description: Forbidden
        "404":
          $ref: "#/components/responses/NotFound"
          description: ""
        "422":
          $ref: "#/components/responses/InvalidParams"
          description: ""
        "500":
          $ref: "#/components/responses/InternalError"
          description: ""
      security:
        - Default: []
  /webhooks/public-keys/{publicKeyId}:
    get:
      summary: Get Webhook Public Key
      deprecated: false
      tags:
        - Webhook Subscriptions
      parameters:
        - name: publicKeyId
          in: path
          description: Public key identifier (UUID).
          required: true
          schema:
            type: string
            examples:
              - ""
        - $ref: "#/components/parameters/RequestId"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicKey"
          headers: {}
        "400":
          $ref: "#/components/responses/BadRequest"
          description: ""
        "401":
          $ref: "#/components/responses/Unauthorized"
          description: ""
        "403":
          $ref: "#/components/responses/Forbidden"
          description: Forbidden
        "404":
          $ref: "#/components/responses/NotFound"
          description: ""
        "422":
          $ref: "#/components/responses/InvalidParams"
          description: ""
        "500":
          $ref: "#/components/responses/InternalError"
          description: ""
      security:
        - Default: []
components:
  securitySchemes:
    Default:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      description: >
        Client-generated unique id for this request (UUID recommended), used for end-to-end tracing.
        Echoed back in the `X-Request-Id` response header and recorded in Axiym logs — quote it when
        contacting support. If omitted, Axiym generates one.
      schema:
        type: string
        format: uuid
        examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
    AccountId:
      name: accountId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
      description: Account identifier (UUID).
    First:
      name: first
      in: query
      description: Maximum number of items to return (page size).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
        examples:
          - 20
    After:
      name: after
      in: query
      description: Cursor for the next page, from the previous response's pageInfo.endCursor.
      schema:
        type: string
        examples:
          - eyJvZmZzZXQiOjI1fQ==
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        Unique client-generated key to safely retry a funds-moving request (e.g. a UUID, but any
        unique string works). Repeating a request with the same key returns the original result
        instead of creating a duplicate.
      schema:
        type: string
        maxLength: 255
        examples:
          - a1b2c3d4-e5f6-7890-abcd-ef1234567890
    DestinationId:
      name: destinationId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        examples:
          - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
      description: Destination identifier (UUID).
    WithdrawalId:
      name: withdrawalId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
      description: Withdrawal identifier (UUID).
  schemas:
    Currency:
      type: string
      description: Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC).
      examples:
        - USD
    AccountStatus:
      type: string
      enum:
        - ACTIVE
        - SUSPENDED
        - CLOSED
      examples:
        - ACTIVE
    Account:
      type: object
      description: Current summary of an account holding a currency balance.
      required:
        - accountId
        - currency
        - paymentRails
        - balance
        - status
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
        currency:
          $ref: "#/components/schemas/Currency"
          description: Account currency.
          examples:
            - USD
        paymentRails:
          type: string
          description: Payment rail associated with the account.
          examples:
            - SWIFT
        balance:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Current balance.
          examples:
            - "48250.00"
        status:
          $ref: "#/components/schemas/AccountStatus"
          description: Account status.
          examples:
            - ACTIVE
    AccountRef:
      type: object
      description: Compact account reference embedded in a withdrawal.
      required:
        - accountId
        - currency
        - paymentRails
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e
        currency:
          $ref: "#/components/schemas/Currency"
          description: Account currency.
          examples:
            - USD
        paymentRails:
          type: string
          description: Payment rail associated with the account.
          examples:
            - SWIFT
    StatementEntryType:
      type: string
      description: Direction of movement on the account.
      enum:
        - CREDIT
        - DEBIT
      examples:
        - DEBIT
    StatementEntry:
      type: object
      description: >-
        A posted ledger movement on an account. Entries are returned in posting order and carry
        the running balance, so consecutive entries reconcile against each other.
      required:
        - entryId
        - accountId
        - type
        - amount
        - currency
        - balanceAfter
        - occurredAt
      properties:
        entryId:
          type: string
          format: uuid
          description: Ledger entry identifier (UUID).
          examples:
            - 7f9a2d1c-8b31-4f59-9e2f-1d63c4a27b12
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
        type:
          $ref: "#/components/schemas/StatementEntryType"
          description: Credit or debit direction.
          examples:
            - DEBIT
        amount:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Positive movement amount in the account currency; direction is in `type`.
          examples:
            - "505.00"
        currency:
          $ref: "#/components/schemas/Currency"
          description: Account currency.
          examples:
            - USD
        balanceBefore:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Running balance before this movement.
          examples:
            - "48250.00"
        balanceAfter:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Running balance after this movement.
          examples:
            - "47745.00"
        relatedResourceType:
          type: string
          description: >-
            Type of the linked money movement; absent for ledger adjustments with no linked
            resource.
          enum:
            - DEPOSIT
            - WITHDRAWAL
            - CONVERSION
          examples:
            - WITHDRAWAL
        relatedResourceId:
          type: string
          format: uuid
          description: Identifier of the linked resource, where present.
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        occurredAt:
          type: string
          format: date-time
          description: When the movement occurred. Formatted in ISO 8601.
          examples:
            - "2026-06-14T20:07:31Z"
    DestinationStatus:
      type: string
      description: >
        `PENDING_REVIEW` awaiting compliance review, `ACTIVE` usable for withdrawals, `SUSPENDED`
        temporarily unusable, `CLOSED` permanently retired. Mirrors the account status vocabulary.
      enum:
        - PENDING_REVIEW
        - ACTIVE
        - SUSPENDED
        - CLOSED
      examples:
        - ACTIVE
    Destination:
      description: A registered withdrawal destination; the shape matches the destination type.
      oneOf:
        - $ref: "#/components/schemas/BankDestination"
        - $ref: "#/components/schemas/WalletDestination"
    BankDestination:
      type: object
      title: Bank account
      required:
        - destinationId
        - status
        - currency
        - accountNumber
        - swiftBic
        - bankName
      properties:
        destinationId:
          type: string
          format: uuid
          description: Destination identifier (UUID).
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        status:
          $ref: "#/components/schemas/DestinationStatus"
          description: Whitelisted own account status.
          examples:
            - ACTIVE
        currency:
          $ref: "#/components/schemas/Currency"
          description: Currency the destination is paid in.
          examples:
            - USD
        accountNumber:
          type: string
          description: Bank account number.
          examples:
            - "0123456789"
        swiftBic:
          type: string
          description: SWIFT/BIC code.
          examples:
            - BOFAUS3NXXX
        bankName:
          type: string
          description: Bank name.
          examples:
            - Bank of America
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp. Formatted in ISO 8601.
          examples:
            - "2026-06-12T14:05:00Z"
    BankDestinationRequest:
      type: object
      description: >-
        Register an owned external bank account as a whitelisted own account. The registered
        account starts in `PENDING_REVIEW`.
      required:
        - currency
        - accountNumber
        - swiftBic
        - bankName
      properties:
        currency:
          $ref: "#/components/schemas/Currency"
        accountNumber:
          type: string
          description: Bank account number.
          examples:
            - "0123456789"
        swiftBic:
          type: string
          description: SWIFT/BIC code.
          examples:
            - BOFAUS3NXXX
        bankName:
          type: string
          description: Bank name.
          examples:
            - Bank of America
    WalletDestinationRequest:
      type: object
      description: >-
        Register an owned external wallet as a whitelisted own account. The registered wallet
        starts in `PENDING_REVIEW`.
      required:
        - currency
        - walletAddress
        - network
      properties:
        currency:
          $ref: "#/components/schemas/Currency"
        walletAddress:
          type: string
          description: Wallet address to register.
          examples:
            - TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL
        network:
          $ref: "#/components/schemas/Network"
    WalletDestination:
      type: object
      title: Wallet address
      required:
        - destinationId
        - status
        - currency
        - walletAddress
        - network
      properties:
        destinationId:
          type: string
          format: uuid
          description: Destination identifier (UUID).
          examples:
            - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
        status:
          $ref: "#/components/schemas/DestinationStatus"
          description: Whitelisted own account status.
          examples:
            - ACTIVE
        currency:
          $ref: "#/components/schemas/Currency"
          description: Currency the destination is paid in.
          examples:
            - USDT
        walletAddress:
          type: string
          description: Destination wallet address; static and reusable.
          examples:
            - TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL
        network:
          $ref: "#/components/schemas/Network"
          description: Network of the wallet address.
          examples:
            - TRON
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp. Formatted in ISO 8601.
          examples:
            - "2026-06-12T14:05:00Z"
    PageInfo:
      type: object
      properties:
        hasNextPage:
          type: boolean
          description: When paginating forwards, are there more items?
          examples:
            - true
        endCursor:
          type: string
          description: When paginating forwards, the cursor to continue.
          examples:
            - eyJvZmZzZXQiOjI1fQ==
      required:
        - hasNextPage
    WithdrawalStatus:
      type: string
      description: >
        `PENDING` awaiting execution, `HELD` temporarily on hold — no action needed from you,
        `COMPLETED` done, `CANCELED`/`REJECTED` not completed (see `reasonCode`).
      enum:
        - PENDING
        - HELD
        - COMPLETED
        - CANCELED
        - REJECTED
      examples:
        - PENDING
    Withdrawal:
      type: object
      required:
        - withdrawalId
        - sourceAccount
        - amount
        - destination
        - status
        - createdAt
        - currency
      properties:
        withdrawalId:
          type: string
          format: uuid
          description: Withdrawal identifier (UUID).
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        sourceAccount:
          allOf:
            - $ref: "#/components/schemas/AccountRef"
          description: The source account, embedded as a compact reference.
        amount:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Amount sent to the whitelisted own account, before fee.
          examples:
            - "500.00"
        feeAmount:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Fee charged.
          examples:
            - "1.00"
        currency:
          $ref: "#/components/schemas/Currency"
          description: Currency code (ISO 4217 or a supported digital currency).
          examples:
            - USD
        destination:
          allOf:
            - $ref: "#/components/schemas/Destination"
          description: The whitelisted own account the destination resolved to, embedded in full.
        status:
          $ref: "#/components/schemas/WithdrawalStatus"
          description: Withdrawal status.
          examples:
            - COMPLETED
        code:
          type: string
          description: System-assigned payment code, shown on the payment.
          examples:
            - AXI00000418
        purpose:
          type: string
          description: Free-text purpose of the payment, as submitted.
          examples:
            - Invoice INV-20416
        externalReference:
          $ref: "#/components/schemas/ExternalReference"
          description: Your reference for correlation, echoed back on related objects.
          examples:
            - wd-2026-0614-01
        transactionHash:
          type: string
          description: >-
            The transaction hash on the network. Present for wallet withdrawals once the
            withdrawal is `COMPLETED`.
          examples:
            - "0x9f8e7d6c5b4a39281706f5e4d3c2b1a0998877665544332211ffeeddccbbaa00"
        reasonCode:
          type: string
          description: >-
            Present when `status` is `CANCELED` or `REJECTED` — the cancellation/rejection reason
            as reported by the bank, the network, or Axiym operations. Example:
            `INSUFFICIENT_BENEFICIARY_DETAILS`.
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp. Formatted in ISO 8601.
          examples:
            - "2026-06-14T20:06:50Z"
    WithdrawalRequest:
      type: object
      description: >
        An outgoing payment from `sourceAccountId`. `amount` is in the source account's currency.
        `destinationId` references one of your whitelisted own accounts; it must be `ACTIVE`
        and in the source Axiym account's currency.
      required:
        - sourceAccountId
        - amount
        - destinationId
      properties:
        sourceAccountId:
          type: string
          format: uuid
          description: Source account identifier (UUID).
          examples:
            - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
        amount:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Amount to send, before fee. In the source account's currency.
          examples:
            - "500.00"
        destinationId:
          type: string
          format: uuid
          description: Identifier of the registered whitelisted own account to pay. It must
            be `ACTIVE` and in the source Axiym account's currency.
          examples:
            - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
        purpose:
          type: string
          description: Free-text purpose of the payment.
          examples:
            - Invoice INV-20416
        externalReference:
          $ref: "#/components/schemas/ExternalReference"
          description: Your reference for correlation, echoed back on related objects.
          examples:
            - wd-2026-0614-01
    WithdrawalEventData:
      type: object
      description: >-
        Compact event payload: enough to route the event and correlate it with your records.
        Webhooks are notifications, not state transfer — fetch the authoritative withdrawal via
        `GET /withdrawals/{withdrawalId}` when you need amounts, fees, or the transaction hash.
      required:
        - withdrawalId
        - status
      properties:
        withdrawalId:
          type: string
          format: uuid
          description: Withdrawal identifier (UUID).
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        status:
          $ref: "#/components/schemas/WithdrawalStatus"
          description: Withdrawal status at the time the event was emitted.
          examples:
            - COMPLETED
        externalReference:
          $ref: "#/components/schemas/ExternalReference"
          description: Your reference submitted on creation, where present.
          examples:
            - wd-2026-0714-01
        reasonCode:
          type: string
          description: >-
            Present on `withdrawal.canceled` / `withdrawal.rejected` — the reason as reported by
            the bank, the network, or Axiym operations. Example:
            `INSUFFICIENT_BENEFICIARY_DETAILS`.
    AccountMovementEventData:
      type: object
      description: >-
        A posted ledger movement on an account. Movements are immutable facts, so the amount is
        carried in the event; the current balance is not — fetch it via `GET /accounts/{accountId}`.
      required:
        - accountId
        - amount
        - currency
        - occurredAt
      properties:
        accountId:
          type: string
          format: uuid
          description: Account identifier (UUID).
          examples:
            - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a
        amount:
          allOf:
            - $ref: "#/components/schemas/Decimal"
          description: Positive movement amount in the account currency; direction is in the event type.
          examples:
            - "1000.00"
        currency:
          $ref: "#/components/schemas/Currency"
          description: Account currency.
          examples:
            - USD
        relatedResourceType:
          type: string
          description: >-
            Type of the linked money movement; absent for movements with no linked API resource.
          enum:
            - DEPOSIT
            - WITHDRAWAL
            - CONVERSION
          examples:
            - WITHDRAWAL
        relatedResourceId:
          type: string
          format: uuid
          description: Identifier of the linked resource, where present.
          examples:
            - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e
        occurredAt:
          type: string
          format: date-time
          description: When the movement occurred. Formatted in ISO 8601.
          examples:
            - "2026-06-14T20:07:31Z"
    DestinationEventData:
      type: object
      description: Whitelisted own account lifecycle notification.
      required:
        - destinationId
        - status
      properties:
        destinationId:
          type: string
          format: uuid
          description: Destination identifier (UUID).
          examples:
            - e2c8a4f6-7b1d-4e3a-9c5f-8a0b2d4e6f1c
        status:
          $ref: "#/components/schemas/DestinationStatus"
          description: Whitelisted own account status at the time the event was emitted.
          examples:
            - ACTIVE
    Event:
      type: object
      description: Webhook event envelope delivered to your registered endpoint.
      required:
        - id
        - timestamp
        - data
      properties:
        id:
          type: string
          format: uuid
          description: Event ID. Use this for de-duplication.
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        timestamp:
          type: string
          format: date-time
          description: Event timestamp. Formatted in ISO 8601.
          examples:
            - "2026-06-23T14:05:09Z"
        type:
          type: string
          description: Event type.
          examples:
            - withdrawal.completed
        data:
          type: object
          properties: {}
          description: Event data.
    Subscription:
      type: object
      properties:
        subscriptionId:
          type: string
          description: Subscription identifier (UUID).
          format: uuid
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        endpoint:
          type: string
          description: >-
            URL of the endpoint to subscribe to notifications. Must be publicly accessible, use
            HTTPS, and respond with a 2XX status to a POST request.
          title: ""
          format: uri
          examples:
            - https://api.acme.example/webhooks
      required:
        - subscriptionId
        - endpoint
    RequestStatus:
      type: object
      properties:
        status:
          type: string
          description: Request status.
          examples:
            - OK
          default: OK
          enum:
            - OK
      required:
        - status
    PublicKey:
      type: object
      properties:
        publicKeyId:
          type: string
          description: Public key identifier (UUID).
          format: uuid
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        active:
          type: boolean
          description: Indicates whether the key is active
          examples:
            - true
        algorithm:
          type: string
          description: Encryption algorithm
          examples:
            - ED25519
        publicKey:
          type: string
          description: Public Key
          examples:
            - string
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp. Formatted in ISO 8601.
          examples:
            - "2026-06-23T14:05:09Z"
      required:
        - publicKeyId
        - algorithm
        - publicKey
        - createdAt
        - active
    Decimal:
      type: string
      description: Decimal number serialized as a string to preserve precision.
      examples:
        - "1000.00"
    ExternalReference:
      type: string
      maxLength: 255
      description: >
        Your own identifier for this object, for correlation with your system. Optional, echoed back
        on reads. This is for business correlation, not retry-safety — use the `Idempotency-Key`
        header to deduplicate retries.
      examples:
        - acme-cl-00417
    ValidationFieldErrors:
      description: >-
        Recursive structure: either an array of ValidationError records (leaf field), an object
        keyed by nested field names (Struct variant), or an object keyed by array indices (List
        variant).
      oneOf:
        - type: array
          items:
            $ref: "#/components/schemas/ValidationError"
        - type: object
          additionalProperties:
            $ref: "#/components/schemas/ValidationFieldErrors"
          properties: {}
    Network:
      type: string
      description: Wallet network.
      enum:
        - TRON
        - AVALANCHE
      examples:
        - TRON
    ValidationError:
      type: object
      description: Single validation error from the `validator` crate.
      properties:
        code:
          type: string
          description: >-
            Validation rule code (e.g. 'length', 'email', 'invalid_currency',
            'disbursement_account_required').
          examples:
            - AXI000221
        message:
          type:
            - string
            - "null"
          description: Human-readable message.
          examples:
            - string
        params:
          type: object
          description: >-
            Rule-specific parameters. Always includes `value` (the offending input). Additional keys
            depend on the rule (e.g. `min`, `max` for length).
          properties:
            value:
              description: The submitted value that failed validation.
              examples:
                - string
      required:
        - code
        - params
  responses:
    BadRequest:
      description: ""
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: HTTP status code, duplicated in the body.
              message:
                type: string
                description: Human-readable message describing the error.
              errors:
                type:
                  - object
                  - "null"
                properties:
                  message:
                    type: string
                description: Additional error details; null when there are none.
            required:
              - code
              - message
              - errors
          examples:
            Malformed JSON body:
              summary: Malformed JSON body
              value:
                code: 400
                message: Bad Request
                errors:
                  message: "Failed to parse the request body as JSON: expected value at line 1 column 5"
            Generic:
              summary: Generic
              value:
                code: 400
                message: Invalid cursor
                errors: null
      headers:
        X-Request-Id:
          description: >-
            Unique id of this request (echoed from the request, or generated when omitted). Recorded
            in Axiym logs — quote it when contacting support about a failed request.
          schema:
            type: string
            format: uuid
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
    Unauthorized:
      description: ""
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: HTTP status code, duplicated in the body.
              message:
                type: string
                description: Human-readable message describing the error.
              errors:
                type:
                  - object
                  - "null"
                description: Additional error details; null when there are none.
            required:
              - code
              - message
              - errors
          examples:
            Example 1:
              summary: Example 1
              value:
                code: 401
                message: Unauthorized
                errors: null
      headers:
        X-Request-Id:
          description: >-
            Unique id of this request (echoed from the request, or generated when omitted). Recorded
            in Axiym logs — quote it when contacting support about a failed request.
          schema:
            type: string
            format: uuid
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
    InternalError:
      description: ""
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: HTTP status code, duplicated in the body.
              message:
                type: string
                description: Human-readable message describing the error.
              errors:
                type:
                  - object
                  - "null"
                description: Additional error details; null when there are none.
            required:
              - code
              - message
              - errors
          examples:
            Example 1:
              summary: Example 1
              value:
                code: 500
                message: Internal Error
                errors: null
      headers:
        X-Request-Id:
          description: >-
            Unique id of this request (echoed from the request, or generated when omitted). Recorded
            in Axiym logs — quote it when contacting support about a failed request.
          schema:
            type: string
            format: uuid
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: HTTP status code, duplicated in the body.
              message:
                type: string
                description: Human-readable message describing the error.
              errors:
                type:
                  - object
                  - "null"
                description: Additional error details; null when there are none.
            required:
              - code
              - message
              - errors
          examples:
            Example 1:
              summary: Example 1
              value:
                code: 403
                message: Forbidden
                errors: null
      headers:
        X-Request-Id:
          description: >-
            Unique id of this request (echoed from the request, or generated when omitted). Recorded
            in Axiym logs — quote it when contacting support about a failed request.
          schema:
            type: string
            format: uuid
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
    NotFound:
      description: ""
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: HTTP status code, duplicated in the body.
              message:
                type: string
                description: >-
                  Human-readable message: either the generic 'Not Found' or a domain-specific one
                  such as 'Client Not Found'.
              errors:
                type:
                  - object
                  - "null"
                description: Additional error details; null when there are none.
            required:
              - code
              - message
              - errors
          examples:
            Generic:
              summary: Generic
              value:
                code: 404
                message: Not Found
                errors: null
            Client not found:
              summary: Client not found
              value:
                code: 404
                message: Client Not Found
                errors: null
      headers:
        X-Request-Id:
          description: >-
            Unique id of this request (echoed from the request, or generated when omitted). Recorded
            in Axiym logs — quote it when contacting support about a failed request.
          schema:
            type: string
            format: uuid
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
    InvalidParams:
      description: >-
        The request could not be processed. Two variants share this status: a validation failure,
        where `errors` is an object keyed by field name, and a business rejection, where `errors` is
        null and `message` states the reason (e.g. `Documents Not Accepted` when uploading to an
        already decided onboarding application, or the generic `Unprocessable Request`).
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: HTTP status code, duplicated in the body.
              message:
                type: string
                description: "`Invalid Parameters` for validation failures; the rejection reason otherwise."
              errors:
                type:
                  - object
                  - "null"
                description: >-
                  Validation failures: object keyed by field name (camelCase); each value is either
                  an array of ValidationError records (leaf), a nested object for struct fields, or
                  an object keyed by array index for list fields. Business rejections: null.
                additionalProperties:
                  $ref: "#/components/schemas/ValidationFieldErrors"
            required:
              - code
              - message
              - errors
          examples:
            Flat field errors:
              summary: Flat field errors
              value:
                code: 422
                message: Invalid Parameters
                errors:
                  legalEntityName:
                    - code: length
                      message: null
                      params:
                        value: ""
                        min: 1
                  currency:
                    - code: invalid_currency
                      message: null
                      params:
                        value: ZZZ
            Nested struct errors:
              summary: Nested struct errors
              value:
                code: 422
                message: Invalid Parameters
                errors:
                  legalAddress:
                    country:
                      - code: invalid_country
                        message: null
                        params:
                          value: INVALID
                    postalCode:
                      - code: length
                        message: null
                        params:
                          value: ""
                          min: 1
            List item errors:
              summary: List item errors
              value:
                code: 422
                message: Invalid Parameters
                errors:
                  authorizedDirectors:
                    "0":
                      firstName:
                        - code: length
                          message: null
                          params:
                            value: ""
                            min: 1
                      email:
                        - code: email
                          message: null
                          params:
                            value: not-an-email
            Custom validator:
              summary: Custom validator
              value:
                code: 422
                message: Invalid Parameters
                errors:
                  disbursementAccount:
                    - code: disbursement_account_required
                      message: null
                      params:
                        value: null
            Business rejection:
              summary: Business rejection
              value:
                code: 422
                message: Documents Not Accepted
                errors: null
      headers:
        X-Request-Id:
          description: >-
            Unique id of this request (echoed from the request, or generated when omitted). Recorded
            in Axiym logs — quote it when contacting support about a failed request.
          schema:
            type: string
            format: uuid
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
webhooks:
  withdrawal.created:
    post:
      tags:
        - Webhooks/Withdrawal
      summary: Created
      operationId: onWithdrawalCreated
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: withdrawal.created
                    data:
                      $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  withdrawal.held:
    post:
      tags:
        - Webhooks/Withdrawal
      summary: Held
      operationId: onWithdrawalHeld
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: withdrawal.held
                    data:
                      $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  withdrawal.completed:
    post:
      tags:
        - Webhooks/Withdrawal
      summary: Completed
      operationId: onWithdrawalCompleted
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: withdrawal.completed
                    data:
                      $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  withdrawal.canceled:
    post:
      tags:
        - Webhooks/Withdrawal
      summary: Canceled
      operationId: onWithdrawalCanceled
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: withdrawal.canceled
                    data:
                      $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  withdrawal.rejected:
    post:
      tags:
        - Webhooks/Withdrawal
      summary: Rejected
      operationId: onWithdrawalRejected
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: withdrawal.rejected
                    data:
                      $ref: "#/components/schemas/WithdrawalEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  account.credited:
    post:
      tags:
        - Webhooks/Account
      summary: Credited
      operationId: onAccountCredited
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: account.credited
                    data:
                      $ref: "#/components/schemas/AccountMovementEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  account.debited:
    post:
      tags:
        - Webhooks/Account
      summary: Debited
      operationId: onAccountDebited
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: account.debited
                    data:
                      $ref: "#/components/schemas/AccountMovementEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  subscription.test:
    post:
      tags:
        - Webhooks/Subscription
      summary: Test
      operationId: onSubscriptionTest
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: subscription.test
                    data:
                      type: object
                      required:
                        - test
                      properties:
                        test:
                          type: string
                          const: OK
      responses:
        "200":
          description: Acknowledged by your endpoint.
  destination.created:
    post:
      tags:
        - Webhooks/Whitelisted own account
      summary: Created
      operationId: onDestinationCreated
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: destination.created
                    data:
                      $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  destination.activated:
    post:
      tags:
        - Webhooks/Whitelisted own account
      summary: Activated
      operationId: onDestinationActivated
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: destination.activated
                    data:
                      $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  destination.suspended:
    post:
      tags:
        - Webhooks/Whitelisted own account
      summary: Suspended
      operationId: onDestinationSuspended
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: destination.suspended
                    data:
                      $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.
  destination.closed:
    post:
      tags:
        - Webhooks/Whitelisted own account
      summary: Closed
      operationId: onDestinationClosed
      security: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/Event"
                - type: object
                  properties:
                    type:
                      type: string
                      const: destination.closed
                    data:
                      $ref: "#/components/schemas/DestinationEventData"
      responses:
        "200":
          description: Acknowledged by your endpoint.