openapi: 3.2.0
info:
  version: '2.0'
  title: Virtual Accounts Virtual Account Endpoints API
  description: The virtual accounts API allows you to manage virtual accounts.
  contact:
    name: API Support
    email: help@vopay.com
servers:
- url: https://earthnode-dev.vopay.com/api/v2
tags:
- name: Virtual Account Endpoints
paths:
  /virtual-account:
    get:
      description: Retrieve information about virtual accounts associated with your account.
      summary: virtual-account
      tags:
      - Virtual Account Endpoints
      operationId: VirtualAccountGET
      deprecated: false
      parameters:
      - name: AccountID
        in: query
        required: true
        description: Your account ID
        schema:
          type: string
      - name: Key
        in: query
        required: true
        description: API key for the account
        schema:
          type: string
      - name: Signature
        in: query
        required: true
        description: Hashed signature for the request
        schema:
          type: string
      - name: Status
        in: query
        required: false
        description: The status of the virtual account
        schema:
          type: string
          enum:
          - Active
          - Pending
          - Inactive
      - name: Currency
        in: query
        required: false
        description: Currency abbreviation (e.g., USD, CAD, EUR)
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: 'true'
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  VirtualAccounts:
                    type: object
                    description: Collection of all your virtual accounts
                    properties:
                      '0':
                        type: object
                        description: Virtual account records
                        properties:
                          VirtualAccountID:
                            type: string
                            description: Unique ID of the virtual account
                            example: '370'
                          VirtualAccountNumber:
                            type: string
                            description: The virtual account number
                            example: '1241221312'
                          Type:
                            type: string
                            description: Type of virtual account
                            example: ''
                          Status:
                            type: string
                            description: The status of the virtual account
                            example: Active
                          Currency:
                            type: string
                            description: Currency of the virtual account
                            example: GBP
                          AccountHolderName:
                            type: string
                            description: Name of the account holder
                            example: John Doe
                          FinancialInstitutionNumber:
                            type: string
                            description: Financial institution number
                            example: '001'
                          BranchTransitNumber:
                            type: string
                            description: Branch transit number
                            example: '12345'
                          AccountNumber:
                            type: string
                            description: Account number
                            example: '123456789'
                          IBAN:
                            type: string
                            description: International Bank Account Number
                            example: GB82WEST12345698765432
                          ABARoutingNumber:
                            type: string
                            description: ABA routing number (US)
                            example: '021000021'
                          BicSwift:
                            type: string
                            description: BIC/SWIFT code
                            example: DEUTDEFF
    post:
      description: Create a new virtual account.
      summary: virtual-account
      tags:
      - Virtual Account Endpoints
      operationId: VirtualAccountCreatePOST
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                AccountID:
                  description: Your account ID
                  type: string
                Key:
                  description: API key for the account
                  type: string
                Signature:
                  description: Hashed signature for the request
                  type: string
                Currency:
                  description: Currency abbreviation for the virtual account (e.g., USD, CAD, EUR, GBP)
                  type: string
              required:
              - AccountID
              - Key
              - Signature
              - Currency
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: 'true'
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  VirtualAccountID:
                    type: string
                    description: The ID of the newly created virtual account
                    example: '450'
  /virtual-account/close:
    post:
      description: Close (deactivate) a virtual account. The virtual account balance must be zero (both the available balance and any pending balance) before it can be closed.
      summary: virtual-account/close
      tags:
      - Virtual Account Endpoints
      operationId: VirtualAccountClosePOST
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                AccountID:
                  description: Your account ID
                  type: string
                Key:
                  description: API key for the account
                  type: string
                Signature:
                  description: Hashed signature for the request
                  type: string
                VirtualAccountID:
                  description: The ID of the virtual account to close
                  type: string
              required:
              - AccountID
              - Key
              - Signature
              - VirtualAccountID
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: 'true'
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  VirtualAccountID:
                    type: string
                    description: The ID of the virtual account that was closed
                    example: '450'
  /virtual-account/balance:
    get:
      description: Retrieve the balance for a specific virtual account.
      summary: virtual-account/balance
      tags:
      - Virtual Account Endpoints
      operationId: VirtualAccountBalanceGET
      deprecated: false
      parameters:
      - name: AccountID
        in: query
        required: true
        description: Your account ID
        schema:
          type: string
      - name: Key
        in: query
        required: true
        description: API key for the account
        schema:
          type: string
      - name: Signature
        in: query
        required: true
        description: Hashed signature for the request
        schema:
          type: string
      - name: VirtualAccountID
        in: query
        required: false
        description: The ID of the virtual account to retrieve the balance for
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: 'true'
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  VirtualAccountBalance:
                    type: array
                    description: Balance details for the virtual account by currency
                    items:
                      type: object
                      properties:
                        Balance:
                          type: string
                          description: Current balance of the virtual account
                          example: '1000.00'
                        ShortForm:
                          type: string
                          description: Currency code
                          example: GBP
  /virtual-account/transactions:
    get:
      description: Retrieve the transaction history for a specific virtual account.
      summary: virtual-account/transactions
      tags:
      - Virtual Account Endpoints
      operationId: VirtualAccountTransactionsGET
      deprecated: false
      parameters:
      - name: AccountID
        in: query
        required: true
        description: Your account ID
        schema:
          type: string
      - name: Key
        in: query
        required: true
        description: API key for the account
        schema:
          type: string
      - name: Signature
        in: query
        required: true
        description: Hashed signature for the request
        schema:
          type: string
      - name: VirtualAccountID
        in: query
        required: true
        description: The ID of the virtual account to retrieve transactions for
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: 'true'
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  VirtualAccountTransactions:
                    type: array
                    description: List of transactions for the virtual account
                    items:
                      type: object
                      properties:
                        FullName:
                          type: string
                          description: Full name associated with the transaction
                          example: John Doe
                        Amount:
                          type: string
                          description: Transaction amount (credit or debit)
                          example: '100.00'
                        ShortForm:
                          type: string
                          description: Currency code
                          example: GBP
                        IBAN:
                          type: string
                          description: IBAN associated with the transaction
                          example: DK9289000000708623
                        TransactionType:
                          type: string
                          description: Type of transaction
                          example: credit
                        TransactionDate:
                          type: string
                          description: Date of the transaction (YYYY-MM-DD)
                          example: '2026-02-03'
  /virtual-account/simulate-credit:
    post:
      description: Simulate a credit to a virtual account. This endpoint is used for testing purposes to add funds to a virtual account.
      summary: virtual-account/simulate-credit
      tags:
      - Virtual Account Endpoints
      operationId: VirtualAccountSimulateCreditPOST
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                AccountID:
                  description: Your account ID
                  type: string
                Key:
                  description: API key for the account
                  type: string
                Signature:
                  description: Hashed signature for the request
                  type: string
                VirtualAccountID:
                  description: The ID of the virtual account to credit
                  type: string
                Amount:
                  description: The amount to credit to the virtual account
                  type: string
              required:
              - AccountID
              - Key
              - Signature
              - VirtualAccountID
              - Amount
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: 'true'
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''