openapi: 3.0.1
info:
  title: Global Api Accounts
  version: 1.0.0
  description: |-
    ## API idempotency 
    Each `POST` request creating a resource (for example a transaction) requires to send a unique idempotency key. It is included in the `Idempotency-Key` HTTP header. Idempotency key helps prevent duplicates in your `POST` requests. We recommend using an **UUID** for the key, however you may use any other unique identifier you choose.

    #### Preventing duplicates 
    If we have already processed the request and you send a request using the same idempotency key, it will fail with an error, returning a ```409 Conflict``` response.

    ## Case-sensitivity
    All properties/keys within request's/response's payload are case-sensitive.

    HTTP headers' names are case-insensitive.

    ## API base URL
    **Sandbox: [https://accounts.sandbox.volt.io]()**

    **Production: [https://accounts.volt.io]()**
  contact:
    email: support@volt.io
    name: Volt Support
    url: 'https://www.volt.io/contact/'
servers:
  - url: 'https://accounts.sandbox.volt.io'
    description: Sandbox
  - url: 'https://accounts.volt.io'
    description: Production
tags:
  - name: Transactions
    description: 'Operations related to movement of funds, including payouts, settlements, and internal transactions.'
  - name: Accounts
    description: Management of accounts.
  - name: Aliases
    description: Issuance and management of account aliases for global reconciliation.
  - name: Account Holder Verification
    description: Verification services for ensuring beneficiary account ownership.
  - name: Trusted accounts
    description: Operations related to trusted accounts.
  - name: Named Accounts
    description: Named account order operations.
  - name: Sandbox
    description: Operations related to sandbox operations.
security:
  - BearerAuth: []
paths:
  #
  # Operations related to Transactions
  #
  /transactions:
    get:
      summary: List of transactions
      operationId: get-transactions
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/PageParam'
        - in: query
          name: 'status[]'
          description: 'Filter by transaction status (e.g. COMPLETED, REJECTED).'
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TransactionStatusEnum'
            example:
              - CREATED
        - in: query
          name: 'createdAt[gte]'
          description: Filter for transactions created on or after this date.
          schema:
            type: string
            format: date-time
            description: 'ISO 8601 format (YYYY-MM-DDThh:mm:ssZ)'
            example: '2025-07-01T10:00:00Z'
        - in: query
          name: 'operation[]'
          description: Filter by operation direction (INCOMING or OUTGOING).
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TransactionOperationEnum'
            example:
              - OUTGOING
        - in: query
          name: 'type[]'
          description: Filter by transaction type.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TransactionTypeEnum'
            example:
              - PAYOUT
        - in: query
          name: accountId
          description: Filter by account.
          schema:
            type: string
            format: uuid
            example: 2f5e48b7-235a-4ba4-ad10-8aa981a73d03
        - in: query
          name: sourceTransactionId
          description: Filter by source transaction id (e.g. for refunds).
          schema:
            type: string
            format: uuid
            example: 2f5e48b7-235a-4ba4-ad10-8aa981a73d03
        - in: query
          name: aliasId
          description: Filter transactions by alias UUID.
          schema:
            type: string
            format: uuid
            example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        - in: query
          name: gatewayPaymentId
          description: Filter transactions by linked gateway payment UUID.
          schema:
            type: string
            format: uuid
            example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        - in: query
          name: iban
          description: 'Filter by exact IBAN. Matches the beneficiary, beneficiary alias or sender identification.'
          schema:
            type: string
            example: DE07500105176551562526
        - in: query
          name: accountNumber
          description: 'Filter by exact account number. Matches the beneficiary, beneficiary alias or sender identification.'
          schema:
            type: string
            example: '12345678'
        - in: query
          name: 'order[createdAt]'
          description: Sort order by createdAt field (desc by default).
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
      responses:
        '200':
          description: Paginated list of transactions.
          headers:
            limit:
              $ref: '#/components/headers/PaginationLimit'
            page:
              $ref: '#/components/headers/PaginationPage'
            page-count:
              $ref: '#/components/headers/PaginationPageCount'
            total-items:
              $ref: '#/components/headers/PaginationTotalItems'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionMinimalDetails'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/transactions/{transactionId}':
    get:
      summary: Get transaction details
      operationId: get-transaction-details
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: transactionId
          in: path
          description: Unique UUID of the transaction.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Full details of the specified transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDetails'
              examples:
                Outgoing:
                  $ref: '#/components/examples/OutgoingResponseExample'
                Incoming:
                  $ref: '#/components/examples/IncomingResponseExample'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/accounts/{accountId}/transactions':
    post:
      summary: Create a transaction
      operationId: create-transaction
      tags:
        - Transactions
      parameters:
        - name: accountId
          in: path
          description: Unique identifier of the account.
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XVoltApiVersion'
        - $ref: '#/components/parameters/XJWSSignature'
        - $ref: '#/components/parameters/XVoltTestingScenario'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - type
              properties:
                type:
                  type: string
                  description: 'The transaction type discriminator (PAYOUT, SETTLEMENT, INTERNAL, or REFUND).'
              oneOf:
                - $ref: '#/components/schemas/SettlementTransactionRequest'
                - $ref: '#/components/schemas/PayoutTransactionRequest'
                - $ref: '#/components/schemas/InternalTransactionRequest'
                - $ref: '#/components/schemas/RefundTransactionRequest'
              discriminator:
                propertyName: type
                mapping:
                  PAYOUT: '#/components/schemas/PayoutTransactionRequest'
                  SETTLEMENT: '#/components/schemas/SettlementTransactionRequest'
                  INTERNAL: '#/components/schemas/InternalTransactionRequest'
                  REFUND: '#/components/schemas/RefundTransactionRequest'
            examples:
              payoutRequestEURExample:
                $ref: '#/components/examples/PayoutRequestEURExample'
              payoutRequestGBPExample:
                $ref: '#/components/examples/PayoutRequestGBPExample'
              settlementRequestEURExample:
                $ref: '#/components/examples/SettlementRequestEURExample'
              internalRequestEURExample:
                $ref: '#/components/examples/InternalRequestEURExample'
              refundRequestExample:
                $ref: '#/components/examples/RefundRequestExample'
      responses:
        '201':
          description: Transaction created successfully.
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: Location of created transaction
          content:
            application/json:
              schema:
                type: object
                description: Response containing the identifier of the created transaction.
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique ID of the transaction.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  #
  # Operations related to Account Holder Verifications
  #
  '/account-holder-verifications/{id}':
    get:
      summary: Get account holder verification details
      operationId: get-account-holder-verification-details
      tags:
        - Account Holder Verification
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: id
          in: path
          description: The unique identifier of the account holder verification.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Verification status and name-matching results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderVerificationDetails'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account-holder-verifications/{id}/approve':
    post:
      summary: Approve account holder verification
      operationId: approve-account-holder-verification
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - $ref: '#/components/parameters/XVoltTestingScenario'
        - name: id
          in: path
          description: Identifier of the account holder verification.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Account Holder Verification
      responses:
        '202':
          description: Accepted approval of account holder verification with the matching ID.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account-holder-verifications/{id}/reject':
    post:
      summary: Reject account holder verification
      operationId: reject-account-holder-verification
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: id
          in: path
          description: Identifier of the account holder verification.
          required: true
          schema:
            type: string
            format: uuid
      tags:
        - Account Holder Verification
      responses:
        '202':
          description: Accepted rejection request of account holder verification with the matching ID.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  #
  # Operations related to Accounts
  #
  /accounts:
    get:
      summary: List of accounts
      operationId: get-accounts
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/PageParam'
        - in: query
          name: 'currency[]'
          schema:
            type: array
            description: Filter by Currency.
            items:
              $ref: '#/components/schemas/CurrencyCode'
            example:
              - EUR
        - in: query
          name: active
          description: Filter by Active.
          schema:
            type: boolean
      responses:
        '200':
          description: Retrieve accounts list.
          headers:
            limit:
              $ref: '#/components/headers/PaginationLimit'
            page:
              $ref: '#/components/headers/PaginationPage'
            page-count:
              $ref: '#/components/headers/PaginationPageCount'
            total-items:
              $ref: '#/components/headers/PaginationTotalItems'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountMinimalDetails'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/accounts/{accountId}':
    get:
      tags:
        - Accounts
      summary: Get account details
      operationId: get-account-details
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the account.
      responses:
        '200':
          description: Successful account details response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountDetails'
              example:
                id: 7523a8d3-70a9-4448-822a-ba1a38e0b715
                currency: EUR
                identifications:
                  - iban: DE33500105173822933531
                    bic: ALBPPLPW
                name: My EUR account
                active: true
                country: DK
                balance:
                  available: 123
                  timestamp: '2023-10-16T16:52:37+00:00'
                type: VOLT_ACCOUNT
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/accounts/{accountId}/close':
    post:
      tags:
        - Accounts
      summary: Close account
      operationId: close-account
      description: Immediately closes the specified account. A closed account cannot be reopened or used for further transactions. Only Named Accounts can be closed.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the account to be closed.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCloseRequest'
      responses:
        '200':
          description: Account successfully closed.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/accounts/{accountId}/beneficiaries':
    get:
      summary: List of transaction beneficiaries
      operationId: get-account-beneficiaries
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/PageParam'
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the account
        - in: query
          name: iban
          schema:
            type: string
            example: DE07500105176551562526
            description: Filter by IBAN.
        - in: query
          name: sortCode
          schema:
            type: string
            example: 12345678
          description: Filter by SortCode number.
        - in: query
          name: accountNumber
          schema:
            type: string
            example: 12345678
          description: Filter by Account number.
        - in: query
          name: 'order[createdAt]'
          description: Sort order by createdAt field.
          schema:
            allOf:
              - $ref: '#/components/schemas/SortOrder'
            default: desc
      responses:
        '200':
          description: List of account beneficiaries
          headers:
            limit:
              $ref: '#/components/headers/PaginationLimit'
            page:
              $ref: '#/components/headers/PaginationPage'
            page-count:
              $ref: '#/components/headers/PaginationPageCount'
            total-items:
              $ref: '#/components/headers/PaginationTotalItems'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccountBeneficiaryMinimalDetails'
              example:
                - name: John Doe
                  accountIdentifiers:
                    iban: DE07500105176551562526
                    swiftBic: '123456'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  #
  # Operations related to Aliases
  #
  '/accounts/{accountId}/aliases':
    get:
      tags:
        - Aliases
      summary: List of aliases for an account
      operationId: get-aliases
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/PageParam'
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the account
        - name: orderId
          in: query
          description: Filter aliases by the order id they were created with.
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of aliases for the account
          headers:
            limit:
              $ref: '#/components/headers/PaginationLimit'
            page:
              $ref: '#/components/headers/PaginationPage'
            page-count:
              $ref: '#/components/headers/PaginationPageCount'
            total-items:
              $ref: '#/components/headers/PaginationTotalItems'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AliasMinimalDetails'
              example:
                - id: 06949674-d65c-4266-a2c6-23bce4a80a81
                  currency: EUR
                  identifications:
                    - iban: DE33500105173822933531
                      bic: ALBPPLPW
                  name: Virtual account
                  customerId: dab4dd0c-d63b-439c-9c47-722ce7a01b60
                  accountId: ca52ea87-a0e3-4371-b301-63309d2e0aa3
                  active: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /orders/account-aliases:
    post:
      tags:
        - Aliases
      operationId: order-aliases
      summary: Order aliases
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XVoltApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AliasesOrderRequest'
      responses:
        '201':
          description: Order for issuing account aliases created successfully.
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: Location of created aliases order.
          content:
            application/json:
              schema:
                type: object
                description: Response containing the identifier of the created aliases order.
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique ID of the aliases order.
                    example: 57ad1a6b-95ac-4b33-8c92-311cda8f3c99
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/orders/account-aliases/{id}':
    get:
      tags:
        - Aliases
      operationId: get-alias-order-status
      summary: Get alias order status
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the alias order
      responses:
        '200':
          description: Alias order details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AliasOrderDetails'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  '/account-aliases/{aliasId}':
    get:
      tags:
        - Aliases
      summary: Get alias details
      operationId: get-alias-details
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: aliasId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the alias
      responses:
        '200':
          description: Details of alias
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AliasDetails'
              example:
                id: 06949674-d65c-4266-a2c6-23bce4a80a81
                currency: EUR
                identifications:
                  - iban: DE33500105173822933531
                    bic: ALBPPLPW
                name: Virtual account
                customerId: dab4dd0c-d63b-439c-9c47-722ce7a01b60
                accountId: ca52ea87-a0e3-4371-b301-63309d2e0aa3
                orderId: 22cb500c-fe26-47ec-bd62-2023d674a8e3
                active: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
    patch:
      tags:
        - Aliases
      summary: Change state of alias
      operationId: change-alias-state
      description: Marks the specified alias as active or inactive.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: aliasId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the alias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeAliasStateRequest'
      responses:
        '200':
          description: alias successfully updated
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account-aliases/{aliasId}/close':
    post:
      tags:
        - Aliases
      summary: Close alias
      operationId: close-alias
      description: Permanently closes the specified alias. A closed alias cannot be reopened or used for further transactions.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: aliasId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the alias to be closed.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AliasCloseRequest'
      responses:
        '200':
          description: Alias successfully closed.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  #
  # Operations related to Trusted Accounts
  #
  /trusted-accounts:
    get:
      tags:
        - Trusted accounts
      summary: List of trusted accounts
      operationId: list-trusted-accounts
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/PageParam'
        - name: active
          in: query
          required: false
          description: Find only active/inactive trusted accounts.
          schema:
            type: boolean
        - name: accountHolderEntityIds
          description: Find trusted accounts for specific account holder entity
          in: query
          required: false
          schema:
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/AccountHolderEntityId'
        - name: groups
          description: Find trusted accounts for specific group
          in: query
          required: false
          schema:
            type: array
            minItems: 0
            items:
              $ref: '#/components/schemas/TrustedAccountCustomerGroup'
      responses:
        '200':
          description: Retrieve trusted accounts list.
          headers:
            limit:
              $ref: '#/components/headers/PaginationLimit'
            page:
              $ref: '#/components/headers/PaginationPage'
            page-count:
              $ref: '#/components/headers/PaginationPageCount'
            total-items:
              $ref: '#/components/headers/PaginationTotalItems'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrustedAccountMinimalDetails'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  #
  # Operations related to Named Accounts
  #
  /orders/named-accounts:
    post:
      tags:
        - Named Accounts
      summary: Create named account order
      operationId: create-named-account-order
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/XVoltApiVersion'
        - $ref: '#/components/parameters/XVoltTestingScenario'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedAccountOrderRequest'
            example:
              onboardingEntityId: a1b2c3d4-5678-90ab-cdef-1234567890ab
              currency: EUR
              communication:
                notifications:
                  url: 'https://mywebsite.com/webhooks'
      responses:
        '202':
          description: Named account order has been accepted
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: Location of the named account order resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedAccountOrderDetails'
              example:
                id: order-5678-90ab-cdef-1234567890ab
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/orders/named-accounts/{id}':
    get:
      tags:
        - Named Accounts
      summary: Get named account order status
      operationId: get-named-account-order-status
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Unique identifier of the named account order
      responses:
        '200':
          description: Named account order details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedAccountOrderDetails'
              examples:
                processingExample:
                  $ref: '#/components/examples/NamedAccountOrderProcessingExample'
                completedExample:
                  $ref: '#/components/examples/NamedAccountOrderCompletedExample'
                failedExample:
                  $ref: '#/components/examples/NamedAccountOrderFailedExample'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /payin:
    post:
      summary: Process an simulated incoming transaction
      description: This endpoint receives and processes a simulated incoming transaction.
      servers:
        - url: 'https://accounts.sandbox.volt.io'
          description: Sandbox
      operationId: process-incoming-payment
      tags:
        - Sandbox
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
      requestBody:
        description: Payload of the `SimulatedIncomingTransaction` event.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulatedIncomingTransaction'
            example:
              externalPaymentId: a1b2c3d4-e5f6-7890-1234-567890abcdef
              paymentReference: TXNREF-20251001-XYZ-987
              amount:
                amount: 123
                currency: PLN
              sender:
                name: John Doe
                accountIdentifiers:
                  iban: DE89370400440532013000
              beneficiary:
                accountIdentifiers:
                  iban: DE89370400440532013000
      responses:
        '200':
          description: The simulated incoming transaction was successfully received for processing.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/transactions/{id}/reverse':
    post:
      summary: Trigger a reversal for an incoming transaction
      description: |
        Simulates a banking provider reversal notification for the specified incoming transaction. Only available in the sandbox environment.
      servers:
        - url: 'https://accounts.sandbox.volt.io'
          description: Sandbox
      operationId: reverse-incoming-transaction
      tags:
        - Sandbox
      parameters:
        - $ref: '#/components/parameters/XVoltApiVersion'
        - name: id
          in: path
          required: true
          description: ID of the incoming transaction to reverse.
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Reversal successfully triggered.
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    #
    # Sandbox response objects schemas
    #
    SimulatedIncomingTransaction:
      type: object
      description: The main object representing a processed incoming payment event.
      required:
        - externalPaymentId
        - paymentReference
        - beneficiary
        - sender
      properties:
        externalPaymentId:
          type: string
          format: uuid
          description: Unique identifier for the transaction.
          example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        paymentReference:
          $ref: '#/components/schemas/PaymentReference'
        beneficiary:
          $ref: '#/components/schemas/SimulatedBeneficiary'
        sender:
          $ref: '#/components/schemas/SimulatedSender'
        amount:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              $ref: "accounts-common.yaml#/components/schemas/Amount"
            currency:
              $ref: '#/components/schemas/CurrencyCode'
    SimulatedBeneficiary:
      type: object
      required:
        - accountIdentifiers
      properties:
        accountIdentifiers:
          $ref: "accounts-common.yaml#/components/schemas/AccountIdentifier"
    SimulatedSender:
      type: object
      required:
        - accountIdentifiers
      properties:
        name:
          type: string
        accountIdentifiers:
          $ref: "accounts-common.yaml#/components/schemas/AccountIdentifier"
    #
    # Main response objects schemas
    #
    AccountDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/AccountMinimalDetails'
        - type: object
          properties:
            _links:
              type: object
              properties:
                self:
                  $ref: '#/components/schemas/LinkObject'
    AccountMinimalDetails:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of Account.
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        identifications:
          $ref: '#/components/schemas/Identifications'
        name:
          type: string
          description: User-defined account alias.
        active:
          type: boolean
          description: Boolean flag indicating if the account is currently enabled for processing transactions.
        status:
          $ref: '#/components/schemas/AccountStatusEnum'
        country:
          $ref: '#/components/schemas/CountryCode'
        balance:
          $ref: '#/components/schemas/AccountBalance'
        type:
          $ref: '#/components/schemas/AccountType'
        subType:
          $ref: '#/components/schemas/AccountSubType'
        accountHolder:
          $ref: '#/components/schemas/AccountHolderMinimalDetails'
    TransactionDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/TransactionMinimalDetails'
        - type: object
          properties:
            _links:
              $ref: '#/components/schemas/TransactionLinks'
    TransactionMinimalDetails:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique UUID of the transaction generated by Volt.
        status:
          $ref: '#/components/schemas/TransactionStatusEnum'
        failure:
          $ref: '#/components/schemas/Failure'
        operation:
          $ref: '#/components/schemas/TransactionOperationEnum'
        type:
          $ref: '#/components/schemas/TransactionTypeEnum'
        subtype:
          $ref: '#/components/schemas/TransactionSubTypeEnum'
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the transaction was initially created (ISO 8601).
        updatedAt:
          type: string
          format: date-time
          description: The timestamp of the last status update (ISO 8601).
        amount:
          $ref: "accounts-common.yaml#/components/schemas/Amount"
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        paymentReference:
          $ref: '#/components/schemas/PaymentReference'
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        paymentRail:
          type: string
          nullable: true
          description: 'The specific infrastructure used to move the funds (e.g. SEPA_INSTANT, FPS).'
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        sender:
          $ref: '#/components/schemas/Sender'
        initiatedBy:
          $ref: '#/components/schemas/InitiatedBy'
        gatewayPaymentId:
          type: string
          format: uuid
          nullable: true
          description: 'UUID of the linked gateway payment, if transaction was matched with a Volt Connect payment.'
        sourceTransactionId:
          type: string
          format: uuid
          nullable: true
          description: 'UUID of the source transaction (e.g. the original transaction being refunded, reversed, or returned).'
        decisions:
          type: array
          items:
            $ref: '#/components/schemas/Decision'
        verifications:
          type: object
          description: Group of verification results.
          properties:
            accountHolderVerification:
              allOf:
                - $ref: '#/components/schemas/AccountHolderVerification'
              nullable: true
    AliasDetails:
      type: object
      allOf:
        - $ref: '#/components/schemas/AliasMinimalDetails'
        - type: object
          properties:
            _links:
              type: object
              properties:
                self:
                  $ref: '#/components/schemas/LinkObject'
    AliasMinimalDetails:
      type: object
      properties:
        id:
          type: string
          format: uuid
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        identifications:
          $ref: '#/components/schemas/Identifications'
        name:
          type: string
        customerId:
          type: string
          format: uuid
        accountId:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        active:
          type: boolean
    AccountHolderVerificationDetails:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of Account Holder Verification Process.
        transactionId:
          type: string
          format: uuid
          description: Id of Transaction.
        status:
          type: string
          description: Status of Account Holder Verification Process.
          enum:
            - COMPLETED
            - PROCESSING #Volt system is processing AHV
            - FAILED
        accountHolderName:
          type: object
          properties:
            requested:
              type: string
              description: The name provided by the merchant for verification.
            returned:
              type: string
              description: The actual name retrieved from the bank's records.
        result:
          $ref: '#/components/schemas/VerificationResult'
        executedAt:
          type: string
          format: date-time
          description: Timestamp of Account Holder Verification Execution.
        decision:
          $ref: '#/components/schemas/Decision'
        _links:
          $ref: '#/components/schemas/VerificationLink'
    AccountBeneficiaryMinimalDetails:
      type: object
      properties:
        name:
          type: string
          description: Name of the beneficiary
          example: John Doe
        accountIdentifiers:
          $ref: "accounts-common.yaml#/components/schemas/AccountIdentifier"
    TrustedAccountMinimalDetails:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of trusted account.
          example: 3400e469-5892-4f51-8e5f-6f2ad7b6f345
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        accountName:
          type: string
          description: Name of the trusted account.
          example: my_gbp_trusted_account
        customerId:
          type: string
          format: uuid
          description: Identifier of the customer within Fuzebox.
          example: 40bb9716-fb00-484e-b4a2-eb3a220b3906
        identifications:
          $ref: '#/components/schemas/Identifications'
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        country:
          $ref: '#/components/schemas/CountryCode'
        active:
          type: boolean
          description: Boolean flag indicating if the trusted account is currently enabled for processing transactions.
    PaymentReference:
      type: string
      pattern: '^(?=.*\S)[a-zA-Z0-9\/\-?:().,''+ ]*$'
      minLength: 1
      maxLength: 35
      description: 'The reconciliation reference that appears on the bank statement. This is crucial for matching the transaction with external banking records. Maximum length: 35 (EU) or 18 (UK).'
    NamedAccountOrderDetails:
      type: object
      description: Named account order status and details.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the named account order
        onboardingEntityId:
          type: string
          format: uuid
          description: ID of the associated onboarding entity
        accountId:
          type: string
          format: uuid
          nullable: true
          description: ID of the created account (only present when status is COMPLETED)
        status:
          $ref: '#/components/schemas/NamedAccountOrderStatusEnum'
        statusReason:
          type: string
          description: 'Reason for the current status (e.g., failure reason)'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the order was created
        completedAt:
          type: string
          format: date-time
          description: Timestamp when the account was created
    #
    # Request objects schemas
    #
    PayoutTransactionRequest:
      type: object
      required:
        - type
        - amount
        - currency
        - beneficiary
        - paymentReference
      properties:
        type:
          type: string
          description: Must be set to PAYOUT.
        amount:
          $ref: "accounts-common.yaml#/components/schemas/Amount"
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        paymentReference:
          $ref: '#/components/schemas/PaymentReference'
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        beneficiary:
          $ref: '#/components/schemas/OutgoingTransactionRequestBeneficiary'
        communication:
          $ref: '#/components/schemas/Communication'
    InternalTransactionRequest:
      type: object
      required:
        - type
        - amount
        - currency
        - beneficiary
        - paymentReference
      properties:
        type:
          type: string
          description: Must be set to INTERNAL.
        amount:
          $ref: "accounts-common.yaml#/components/schemas/Amount"
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        paymentReference:
          $ref: '#/components/schemas/PaymentReference'
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        beneficiary:
          type: object
          description: The unique UUID of the  account receiving the funds.
          required:
            - accountId
          properties:
            accountId:
              type: string
              format: uuid
              description: Target internal account ID.
        communication:
          $ref: '#/components/schemas/Communication'
    RefundTransactionRequest:
      type: object
      required:
        - type
        - sourceTransactionId
        - amount
        - currency
        - paymentReference
      properties:
        type:
          type: string
          description: Must be set to REFUND.
        sourceTransactionId:
          type: string
          format: uuid
          description: The ID of the incoming transaction to refund.
        amount:
          $ref: "accounts-common.yaml#/components/schemas/Amount"
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        paymentReference:
          $ref: '#/components/schemas/PaymentReference'
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        communication:
          $ref: '#/components/schemas/Communication'
    SettlementTransactionRequest:
      type: object
      required:
        - type
        - amount
        - currency
        - paymentReference
        - beneficiary
      properties:
        type:
          type: string
        amount:
          $ref: "accounts-common.yaml#/components/schemas/Amount"
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        paymentReference:
          $ref: '#/components/schemas/PaymentReference'
        internalReference:
          $ref: '#/components/schemas/InternalReference'
        beneficiary:
          $ref: '#/components/schemas/OutgoingTransactionRequestBeneficiaryTrustedAccount'
        communication:
          $ref: '#/components/schemas/Communication'
    AliasOrderDetails:
      type: object
      description: Alias order status and details.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the alias order
        accountId:
          type: string
          format: uuid
          description: Unique identifier of the account the aliases are assigned to
        status:
          $ref: '#/components/schemas/AliasOrderStatusEnum'
        requested:
          type: integer
          description: Total number of aliases requested
        completed:
          type: integer
          description: Number of aliases successfully created so far
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the order was created
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the order reached a terminal state
        _links:
          $ref: '#/components/schemas/AliasOrderLinks'
    AliasOrderLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/LinkObject'
        aliases:
          $ref: '#/components/schemas/LinkObject'
    AliasOrderStatusEnum:
      type: string
      description: Current status of the alias order
      enum:
        - PROCESSING
        - COMPLETED
        - FAILED
    AliasesOrderRequest:
      type: object
      properties:
        accountId:
          type: string
          format: uuid
          description: The unique identifier of the account.
        count:
          type: integer
          minimum: 1
          maximum: 1000
          description: Number of aliases to create.
        communication:
          $ref: '#/components/schemas/Communication'
      required:
        - accountId
        - count
    ChangeAliasStateRequest:
      type: object
      properties:
        active:
          type: boolean
      required:
        - active
    NamedAccountOrderRequest:
      type: object
      description: Request to create a named account from an approved onboarding.
      required:
        - onboardingEntityId
        - currency
      properties:
        onboardingEntityId:
          type: string
          format: uuid
          description: ID of the approved onboarding entity
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        communication:
          $ref: '#/components/schemas/Communication'
    #
    # Internal objects schemas
    #
    Failure:
      type: object
      description: Details regarding why a transaction was not successful.
      properties:
        code:
          type: string
          description: A standardized machine-readable error code indicating why the transaction failed.
    AccountHolderVerification:
      type: object
      description: Account Holder Verification basic information.
      properties:
        id:
          type: string
          format: uuid
          description: Unique verification ID.
        result:
          $ref: '#/components/schemas/VerificationResult'
        executedAt:
          type: string
          format: date-time
          description: Timestamp of  Account Holder Verification Execution.
    VerificationResult:
      type: string
      description: The outcome of the Account Holder Verification (AHV) process. This indicates  the degree of similarity between the provided beneficiary name and the name  registered at the destination bank.
      enum:
        - MATCH
        - CLOSE_MATCH
        - NO_MATCH
        - ERROR
    Beneficiary:
      type: object
      description: The recipient of the funds.
      properties:
        customerId:
          type: string
          format: uuid
          description: Identifier of the customer within Fuzebox.
        accountId:
          type: string
          format: uuid
          description: Target account ID.
        alias:
          $ref: '#/components/schemas/Alias'
        name:
          type: string
          description: Name of the individual or entity.
        email:
          type: string
          format: email
        country:
          $ref: '#/components/schemas/CountryCode'
        accountIdentifiers:
          $ref: "accounts-common.yaml#/components/schemas/AccountIdentifier"
        address:
          $ref: '#/components/schemas/Address'
    TransactionStatusEnum:
      type: string
      enum:
        - CREATED
        - PROCESSING
        - COMPLETED
        - REJECTED
    TransactionOperationEnum:
      type: string
      enum:
        - OUTGOING
        - INCOMING
    TransactionTypeEnum:
      type: string
      enum:
        - PAYOUT
        - SETTLEMENT
        - REFUND
        - INTERNAL
        - GATEWAY_PAYMENT
        - MANUAL_CREDIT
        - TOP_UP
        - BOUNCE_BACK
        - REVERSAL
    TransactionSubTypeEnum:
      type: string
      enum:
        - OPEN_LOOP
        - CLOSE_LOOP
        - VERIFIED
        - PARTIAL
        - FULL
    Alias:
      type: object
      description: Account alias details associated with the transaction.
      properties:
        id:
          type: string
          format: uuid
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    Identifications:
      description: A list of one or more account identifiers.
      type: array
      items:
        $ref: "accounts-common.yaml#/components/schemas/AccountIdentifier"
      minItems: 1
    Address:
      type: object
      description: Physical address of the beneficiary or sender.
      properties:
        addressLine1:
          type: string
          description: 'Primary address line, typically containing the street name and building number.'
        addressLine2:
          type: string
          description: 'Additional address details such as suite, apartment number, or floor level.'
        city:
          type: string
          description: The city or locality of the beneficiary's registered address.
        postalCode:
          description: The ZIP or Postal code
          type: string
        country:
          $ref: '#/components/schemas/CountryCode'
    Sender:
      type: object
      properties:
        name:
          type: string
          description: Full name or legal entity name of the sender as registered with the bank.
        customerId:
          type: string
          format: uuid
          description: The unique identifier of the customer in Volt.
        accountId:
          type: string
          format: uuid
          description: The unique identifier of the sender's account
        accountIdentifiers:
          $ref: "accounts-common.yaml#/components/schemas/AccountIdentifier"
    InitiatedBy:
      type: object
      properties:
        performer:
          $ref: '#/components/schemas/Performer'
    Decision:
      type: object
      description: Records of manual approvals or rejections.
      properties:
        performer:
          $ref: '#/components/schemas/Performer'
        type:
          type: string
          description: Type of performer's decision.
          enum:
            - APPROVED
            - REJECTED
        subject:
          type: string
          enum:
            - ACCOUNT_HOLDER_VERIFICATION
            - TRANSACTION
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the decision was initially created (ISO 8601).
    Performer:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique UUID of the action's performer.
        name:
          type: string
          description: The full name of the performer.
        type:
          type: string
          description: The type of the performer.
          enum:
            - USER
            - API_CLIENT
    AccountType:
      type: string
      enum:
        - VOLT_ACCOUNT
        - NAMED_ACCOUNT
        - CONNECTED_ACCOUNT
    AccountSubType:
      type: string
      enum:
        - BUSINESS
        - INDIVIDUAL
    AccountStatusEnum:
      type: string
      description: The current status of the account.
      enum:
        - ACTIVE
        - SUSPENDED
        - CLOSED
    AccountBalance:
      type: object
      description: The account balance in minor units.
      properties:
        available:
          type: integer
          format: int64
        timestamp:
          type: string
          format: date-time
    AccountHolderMinimalDetails:
      type: object
      required:
        - entityId
        - legalName
      properties:
        entityId:
          $ref: '#/components/schemas/AccountHolderEntityId'
        legalName:
          type: string
          description: Full name or legal entity name of the account holder as registered with the bank.
    AccountHolder:
      type: object
      required:
        - entityId
        - legalName
        - address
        - beneficiaries
      properties:
        entityId:
          $ref: '#/components/schemas/AccountHolderEntityId'
        legalName:
          type: string
          description: Full name or legal entity name of the account holder as registered with the bank.
        address:
          $ref: '#/components/schemas/Address'
        ultimateBeneficialOwners:
          type: array
          description: List of ultimate beneficial owners of the account.
          uniqueItems: true
          minItems: 1
          items:
            $ref: '#/components/schemas/UltimateBeneficialOwner'
    UltimateBeneficialOwner:
      type: object
      required:
        - firstName
        - lastName
      properties:
        firstName:
          type: string
          description: First name of ultimate beneficial owner.
        lastName:
          type: string
          description: Last name of ultimate beneficial owner.
    AccountHolderEntityId:
      type: string
      format: uuid
      description: |
        The unique identifier of the account holder entity depends on the entity type:
        * Volt Business Customer: customer identifier
        * Merchant Clients (Business/Individual): unique identifier issued during the client onboarding process
      example: 40bb9716-fb00-484e-b4a2-eb3a220b3906
    AccountCloseRequest:
      type: object
      properties:
        communication:
          $ref: '#/components/schemas/Communication'
    AliasCloseRequest:
      type: object
      properties:
        communication:
          $ref: '#/components/schemas/Communication'
    Communication:
      type: object
      properties:
        notifications:
          type: object
          description: Settings for webhook notifications delivery.
          properties:
            url:
              type: string
              pattern: '^https?://[^ ]+$'
              description: 'URL where the notifications (webhooks) are going to be sent when the transaction status changes. This value will take precedence over Fuzebox configuration. Provide a value here only if you need to overwrite it. Note that a default notifications URL must be configured in Fuzebox for notifications to be delivered; if it is not configured, no notification will be sent even when this overwrite URL is provided.'
              example: 'https://mywebsite.com/webhooks'
    OutgoingTransactionRequestBeneficiary:
      type: object
      required:
        - name
        - accountIdentifiers
      properties:
        name:
          type: string
          description: The name of the beneficiary.
          minLength: 1
          maxLength: 35
          pattern: '^(?=.*\S)[a-zA-Z0-9\/\-?:().,''+ ]*$'
        email:
          type: string
          description: The email address of the beneficiary.
          format: email
          pattern: '^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$'
        accountIdentifiers:
          $ref: "accounts-common.yaml#/components/schemas/AccountIdentifier"
        address:
          type: object
          description: Optional additional address information
          required:
            - addressLine1
            - city
            - country
          properties:
            addressLine1:
              type: string
              maxLength: 35
              pattern: '^(?! *$)(?!.*\/\/)(?![:\-\/])[0-9A-Za-z\/\-?:().,''+_ ]+(?<!\/)$'
              description: 'Primary address line, typically containing the street name and building number.'
            addressLine2:
              type: string
              maxLength: 35
              pattern: '^(?:[0-9A-Za-z\/\-?:().,''+_ ]*(?<!\/))?$'
              description: 'Additional address details such as suite, apartment number, or floor level.'
            city:
              type: string
              maxLength: 35
              pattern: '^(?! *$)(?!.*\/\/)(?![:\-\/])[0-9A-Za-z\/\-?:().,''+_ ]+(?<!\/)$'
              description: The city or locality of the beneficiary's registered address.
            postalCode:
              type: string
              maxLength: 16
              pattern: '^[A-Za-z0-9 \-]*$'
              description: The ZIP or Postal code.
            country:
              $ref: '#/components/schemas/CountryCode'
    OutgoingTransactionRequestBeneficiaryTrustedAccount:
      type: object
      required:
        - trustedAccountId
      properties:
        trustedAccountId:
          type: string
          format: uuid
          description: ID of a pre-approved trusted account.
    VerificationLink:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/LinkObject'
        transaction:
          $ref: '#/components/schemas/LinkObject'
      additionalProperties: false
    TransactionLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/LinkObject'
        reversalOf:
          $ref: '#/components/schemas/LinkObject'
        reversedBy:
          $ref: '#/components/schemas/LinkObject'
        refundOf:
          $ref: '#/components/schemas/LinkObject'
        refundedBy:
          $ref: '#/components/schemas/LinkObjectArray'
        gatewayPayment:
          $ref: '#/components/schemas/LinkObject'
        correspondingInternal:
          $ref: '#/components/schemas/LinkObject'
        accountHolderVerification:
          $ref: '#/components/schemas/LinkObject'
      additionalProperties: false
    LinkObjectArray:
      type: array
      description: List of links
      items:
        $ref: '#/components/schemas/LinkObject'
    LinkObject:
      type: object
      properties:
        href:
          type: string
          format: uri
        method:
          type: string
          enum:
            - GET
            - POST
            - PATCH
            - DELETE
      required:
        - href
    SortOrder:
      description: Sorting direction
      type: string
      enum:
        - asc
        - desc
    CurrencyCode:
      type: string
      description: Three-letter ISO 4217 currency code.
      example: EUR
      pattern: '^[A-Z]{3}$'
    CountryCode:
      description: Alpha-2 country code
      example: DE
      pattern: '^[A-Z]{2}$'
      type: string
    InternalReference:
      type: string
      maxLength: 100
      pattern: '^[a-zA-Z0-9!@#$%^&*()_+={\[\]};:?|\-]*$'
      description: Unique identifier of the transaction in the partner's system. Useful for automated reconciliation and logging.
      nullable: true
    NamedAccountOrderStatusEnum:
      type: string
      description: Current status of the named account order
      enum:
        - PROCESSING
        - COMPLETED
        - FAILED
    TrustedAccountCustomerGroup:
      type: string
      enum:
        - CUSTOMERS
        - CUSTOMER_INDIVIDUAL_CLIENTS
      description: |
        * `CUSTOMERS` - List direct trusted accounts of customers in the hierarchy
        * `CUSTOMER_INDIVIDUAL_CLIENTS` - List trusted accounts of merchant individual clients only
    XVoltTestingScenario:
      type: string
      enum:
        - PAYOUT_REJECTED
        - ACCOUNT_HOLDER_VERIFICATION_CLOSE_MATCH
        - ACCOUNT_HOLDER_VERIFICATION_NO_MATCH
        - ACCOUNT_HOLDER_VERIFICATION_ERROR
        - ONBOARDING_REJECTED
        - ONBOARDING_ADDITIONAL_INFO_REQUIRED
        - ONBOARDING_ADDITIONAL_INFO_REQUIRED_NAME_MISMATCH
        - ONBOARDING_EXPIRED
        - ORDER_NAMED_ACCOUNTS_FAILED
      #
      # Error and validation objects schemas
      #
    Error400Response:
      type: object
      description: Error response for HTTP 400 Bad Request.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - BAD_REQUEST
            - INVALID_PATH_VARIABLE
            - MISSING_HTTP_HEADER
            - INVALID_HTTP_HEADER
            - MALFORMED_PATH_PARAM
            - MISSING_QUERY_PARAM
            - INVALID_QUERY_PARAM
            - MALFORMED_QUERY_PARAM
            - CONFIGURATION_ERROR
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    Error401Response:
      type: object
      description: Error response for HTTP 401 Unauthorized.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - UNAUTHORISED
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    Error403Response:
      type: object
      description: Error response for HTTP 403 Forbidden.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - ACCESS_DENIED
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    Error404Response:
      type: object
      description: Error response for HTTP 404 Not Found.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - RESOURCE_NOT_FOUND
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    Error405Response:
      type: object
      description: HTTP method is not supported for this URL.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - METHOD_NOT_SUPPORTED
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    Error406Response:
      type: object
      description: API is not able to generate a response in the format defined in the Accept HTTP request header.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - MEDIA_TYPE_NOT_ACCEPTABLE
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    Error409Response:
      type: object
      description: Error response for HTTP 409 Conflict.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - CONFLICT
            - IDEMPOTENCY_CONFLICT
            - RESOURCE_NOT_MODIFIABLE
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    Error415Response:
      type: object
      description: Request contains data in an unsupported content type.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - UNSUPPORTED_MEDIA_TYPE
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    Error422Response:
      type: object
      description: Error response for HTTP 422 Unprocessable Entity.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - VALIDATION_FAILURE
        message:
          type: string
          description: Error message.
        errors:
          type: array
          description: Field validation errors.
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
      required:
        - code
        - message
        - errors
    Error500Response:
      type: object
      description: Error response for HTTP 500 Internal Server Error.
      properties:
        code:
          type: string
          description: Error code.
          enum:
            - INTERNAL_SERVER_ERROR
        message:
          type: string
          description: Error message.
      required:
        - code
        - message
    ValidationErrorDetail:
      type: object
      description: Details about a specific validation error.
      properties:
        type:
          $ref: '#/components/schemas/ValidationErrorType'
        propertyPath:
          type: string
          description: Points to the specific field or property in the incoming request that violated the validation rule.
        message:
          type: string
          description: Human-readable message about constraint violation.
    ValidationErrorType:
      $ref: "./error-common.yaml#/components/schemas/ValidationErrorType"
  examples:
    IncomingResponseExample:
      value:
        id: efffed42-40f7-4bd2-840d-908aae9a33ad
        status: COMPLETED
        failure: null
        operation: INCOMING
        type: MANUAL_CREDIT
        subtype: null
        createdAt: '2025-07-01T10:00:00Z'
        updatedAt: '2025-07-01T10:05:00Z'
        amount: 500
        currency: EUR
        paymentReference: Payin
        paymentRail: SEPA
        beneficiary:
          name: Your Company Name
          country: DE
          customerId: 2f5e48b7-235a-4ba4-ad10-8aa981a73d03
          accountId: 7523a8d3-70a9-4448-822a-ba1a38e0b715
          alias:
            aliasId: f47ac10b-58cc-4372-a567-0e02b2c3d479
            accountIdentifiers:
              iban: DE33500105173822933531
        sender:
          name: John Doe
          country: LT
          accountIdentifiers:
            iban: DE07500105176551562526
            swiftBic: '123456'
          address:
            addressLine1: '123, Main Street'
            addressLine2: ''
            city: New York City
            postalCode: '12332'
            country: US
        _links:
          self:
            href: 'https://accounts.volt.io/transactions/efffed42-40f7-4bd2-840d-908aae9a33ad'
            method: GET
    OutgoingResponseExample:
      value:
        id: efffed42-40f7-4bd2-840d-908aae9a33ad
        status: COMPLETED
        failure: null
        operation: OUTGOING
        type: PAYOUT
        subtype: OPEN_LOOP
        createdAt: '2019-08-24T14:15:22Z'
        updatedAt: '2019-08-25T14:15:22Z'
        amount: 500
        currency: EUR
        paymentReference: Payout123456
        internalReference: H35X48Y4FWOD6G3S
        paymentRail: SEPA
        beneficiary:
          name: John Doe
          country: GB
          email: email@email.com
          accountIdentifiers:
            iban: DE07500105176551562526
          address:
            addressLine1: '123, Main Street'
            addressLine2: ''
            city: London
            postalCode: '12332'
            country: GB
        sender:
          name: Account Holding
          customerId: efffed42-40f7-4bd2-840d-908aae9a33ad
          accountId: efffed42-40f7-4bd2-840d-908aae9a33ad
          accountIdentifiers:
            iban: DE07500105176551562526
            swiftBic: '123456'
        initiatedBy:
          user:
            id: efffed42-40f7-4bd2-840d-908aae9a33ad
            name: Robert Robertson
            type: USER
        decisions:
          - user:
              id: efffed42-40f7-4bd2-840d-908aae9a33ad
              name: Robert Robertson
              type: USER
            type: APPROVED
            createdAt: '2019-08-24T14:15:22Z'
        _links:
          self:
            href: 'https://accounts.volt.io/transactions/efffed42-40f7-4bd2-840d-908aae9a33ad'
            method: GET
    PayoutRequestEURExample:
      value:
        type: PAYOUT
        amount: 1000
        currency: EUR
        paymentReference: Reconciliation-1
        internalReference: INT-99
        beneficiary:
          name: John Doe
          email: email@email.com
          accountIdentifiers:
            iban: DE07500105176551562526
            swiftBic: '123456'
          address:
            addressLine1: '123, Main Street'
            addressLine2: ''
            city: Berlin
            postalCode: '12332'
            country: DE
        communication:
          notifications:
            url: 'https://mywebsite.com/webhooks'
    PayoutRequestGBPExample:
      value:
        type: PAYOUT
        amount: 5000
        currency: GBP
        paymentReference: UK-Payout
        internalReference: INT-101
        beneficiary:
          name: John Doe
          country: GBP
          email: email@email.com
          accountIdentifiers:
            accountNumber: '12345678'
            sortCode: '123456'
          address:
            addressLine1: '123, Main Street'
            addressLine2: ''
            city: London
            postalCode: '12332'
            country: GB
        communication:
          notifications:
            url: 'https://mywebsite.com/webhooks'
    SettlementRequestEURExample:
      value:
        type: SETTLEMENT
        amount: 25000
        currency: EUR
        paymentReference: Weekly-Settlement
        internalReference: SETTLE-01
        beneficiary:
          trustedAccountId: efffed42-40f7-4bd2-840d-908aae9a33ad
        communication:
          notifications:
            url: 'https://mywebsite.com/webhooks'
    InternalRequestEURExample:
      value:
        type: INTERNAL
        amount: 100
        currency: EUR
        paymentReference: REBALANCE-EUR-01
        internalReference: LIQUIDITY-MOVE-2025
        beneficiary:
          accountId: 998275d3-70a9-4448-822a-ba1a38e0b715
        communication:
          notifications:
            url: 'https://mywebsite.com/webhooks'
    RefundRequestExample:
      value:
        type: REFUND
        sourceTransactionId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        amount: 1000
        currency: EUR
        paymentReference: Refund-Order-42
        internalReference: REFUND-INT-01
        communication:
          notifications:
            url: 'https://mywebsite.com/webhooks'
    NamedAccountOrderProcessingExample:
      value:
        id: order-5678-90ab-cdef-1234567890ab
        onboardingEntityId: a1b2c3d4-5678-90ab-cdef-1234567890ab
        status: PROCESSING
        statusReason: null
        createdAt: '2025-12-03T15:00:00Z'
        completedAt: null
    NamedAccountOrderCompletedExample:
      value:
        id: order-5678-90ab-cdef-1234567890ab
        onboardingEntityId: a1b2c3d4-5678-90ab-cdef-1234567890ab
        accountId: 7523a8d3-70a9-4448-822a-ba1a38e0b715
        status: COMPLETED
        statusReason: null
        createdAt: '2025-12-03T15:00:00Z'
        completedAt: '2025-12-03T15:05:00Z'
    NamedAccountOrderFailedExample:
      value:
        id: order-5678-90ab-cdef-1234567890ab
        onboardingEntityId: a1b2c3d4-5678-90ab-cdef-1234567890ab
        status: FAILED
        statusReason: Account creation failed due to banking provider error
        createdAt: '2025-12-03T15:00:00Z'
        completedAt: null
  parameters:
    XJWSSignature:
      name: X-JWS-Signature
      in: header
      description: Detached JWS signature for request integrity and authenticity.
      required: true
      schema:
        type: string
        example: eyJhbGciOXXXXX
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: 'It helps preventing duplicates in your `POST` requests. It is recommend using a **UUID** for the key, however you may use any other unique identifier you choose.'
      required: true
      schema:
        type: string
        maxLength: 160
        example: 85136c79cbf9fe36bb9d05d0639c70c265c18d37
    XVoltApiVersion:
      name: X-Volt-Api-Version
      in: header
      description: 'Version of the API used. Currently, version `1` is the only version.'
      required: true
      schema:
        type: integer
        example: 1
        enum:
          - 1
    XVoltTestingScenario:
      name: X-Volt-Testing-Scenario
      in: header
      description: '[SANDBOX ONLY] used to trigger specific transaction failure or verification mocks.'
      required: false
      schema:
        $ref: '#/components/schemas/XVoltTestingScenario'
    LimitParam:
      name: limit
      in: query
      description: Number of items to return per page (max 100).
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    PageParam:
      name: page
      in: query
      description: Page index for pagination.
      schema:
        type: integer
        minimum: 1
        default: 1
  responses:
    '400':
      description: '**Bad request** - Request you sent is invalid or malformed. Response will contain a description of the actual problem.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error400Response'
    '401':
      description: '**Unauthorized** - Your credentials were invalid. It may be that the token you''ve used has expired. Try re-authenticating with valid or updated credentials and retry this request.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error401Response'
    '403':
      description: '**Access denied** - Although your credentials are correct, your access to this section of the API has been disabled or limited. Subsequent requests to this endpoint will not be processed.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error403Response'
    '404':
      description: '**Not found** - The resource that you are requesting cannot be found.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404Response'
    '405':
      description: '**Method not supported** - HTTP method is not supported for this URL.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error405Response'
    '406':
      description: '**Media-type not acceptable** - API is not able to generate a response in the format defined in the Accept HTTP request header.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error406Response'
    '409':
      description: '**Conflict** - Modification of a resource is not possible, because current state of it does not allow it. Or `Idempotency-Key` was already used.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error409Response'
    '415':
      description: '**Unsupported media-type** - Request contains data in an unsupported content type.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error415Response'
    '422':
      description: '**Unprocessable** - Request''s payload validation fails.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error422Response'
    '500':
      description: '**Internal server error** - Something went wrong and request cannot be processed due to server error. Message will contain trace ID and timestamp, which allows to investigate what went wrong.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error500Response'
  headers:
    PaginationLimit:
      description: Number of items per page.
      schema:
        type: integer
        example: 25
    PaginationPage:
      description: The current page number.
      schema:
        type: integer
        example: 1
    PaginationPageCount:
      description: Total number of available pages.
      schema:
        type: integer
        example: 6
    PaginationTotalItems:
      description: The absolute count of items matching the query.
      schema:
        type: integer
        example: 150