openapi: 3.2.0
info:
  version: '2.0'
  title: File Conversion Endpoints API
  description: The file conversion API allows you to convert files from one format to another programmatically as well as submitting files to banking partners directly. This API supports a variety of file types and conversion options to meet your needs.
  contact:
    name: API Support
    email: help@vopay.com
servers:
- url: https://earthnode-dev.vopay.com/api/v2
tags:
- name: File Conversion Endpoints
paths:
  /file-conversion/upload:
    post:
      description: Upload a file for conversion or submission to a banking partner.
      summary: file-conversion/upload
      tags:
      - File Conversion Endpoints
      operationId: FileConversionUploadPOST
      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
                SourceFileName:
                  description: The name of the source file to be uploaded for conversion
                  type: string
                SourceFile:
                  description: The source file content to be uploaded for conversion, base64 encoded
                  type: string
                Service:
                  description: 'Service type: Debit (Collect funds) or Credit (Send funds)'
                  type: string
                  enum:
                  - Debit
                  - Credit
              required:
              - AccountID
              - Key
              - Signature
              - SourceFileName
              - SourceFile
              - Service
        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: ''
                  FileConversionID:
                    type: string
                    description: The ID of the file conversion job
                    example: '450'
                  TransactionCount:
                    type: string
                    description: The number of transactions processed in the file
                    example: '23'
                  TotalAmount:
                    type: string
                    description: The total amount processed in the file
                    example: 1,000.00
                  Currency:
                    type: string
                    description: The currency of the total amount processed in the file
                    example: USD
  /file-conversion/submit:
    post:
      description: Submit an uploaded file for processing and transmission to a banking partner.
      summary: file-conversion/submit
      tags:
      - File Conversion Endpoints
      operationId: FileConversionSubmitPOST
      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
                FileConversionID:
                  description: The ID of the file conversion job returned from the upload endpoint
                  type: string
                FileConversionConfigurationID:
                  description: The ID of the file conversion configuration to use for processing
                  type: string
                ValueDate:
                  description: The value date for the transactions (YYYY-MM-DD). Defaults to current date if not provided
                  type: string
                  format: date
                PaymentRail:
                  description: The primary payment rail to use for processing
                  type: string
                  enum:
                  - interac
                  - eft
                  - vopayinstant
                  - ach
                  - rtp
                  - fednow
                  - fedwire
                  - aft
                  - oct
                  - creditcard
                  - debitcard
                AlternatePaymentRail:
                  description: An alternate payment rail to use if the primary rail is unavailable
                  type: string
                  enum:
                  - interac
                  - eft
                  - vopayinstant
                  - ach
                  - rtp
                  - fednow
                  - fedwire
                  - aft
                  - oct
                  - creditcard
                  - debitcard
              required:
              - AccountID
              - Key
              - Signature
              - FileConversionID
        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: ''
                  TotalTransactions:
                    type: integer
                    description: The total number of transactions submitted
                    example: '23'
                  TotalFailed:
                    type: integer
                    description: The number of transactions that failed to submit
                    example: '0'
                  TotalAmount:
                    type: string
                    description: The total amount submitted
                    example: 1,000.00
                  Currency:
                    type: string
                    description: The currency of the total amount
                    example: USD
  /file-conversion/download:
    get:
      description: Download the converted target file for a specific file conversion.
      summary: file-conversion/download
      tags:
      - File Conversion Endpoints
      operationId: FileConversionDownloadGET
      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: FileConversionID
        in: query
        required: true
        description: The ID of the file conversion job
        schema:
          type: string
      - name: FileConversionConfigurationID
        in: query
        required: true
        description: The ID of the file conversion configuration used for conversion
        schema:
          type: string
      - name: ValueDate
        in: query
        required: false
        description: The value date for the transactions (YYYY-MM-DD). Defaults to current date if not provided
        schema:
          type: string
          format: date
      - name: PaymentRail
        in: query
        required: false
        description: The payment rail used for conversion
        schema:
          type: string
          enum:
          - interac
          - eft
          - vopayinstant
          - ach
          - rtp
          - fednow
          - fedwire
          - aft
          - oct
          - creditcard
          - debitcard
      - name: AlternatePaymentRail
        in: query
        required: false
        description: An alternate payment rail used for conversion
        schema:
          type: string
          enum:
          - interac
          - eft
          - vopayinstant
          - ach
          - rtp
          - fednow
          - fedwire
          - aft
          - oct
          - creditcard
          - debitcard
      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: ''
                  FileConversionID:
                    type: string
                    description: The ID of the file conversion job
                    example: '450'
                  FileContent:
                    type: string
                    description: The converted file content, base64 encoded
                    example: SGVsbG8gV29ybGQ=
                  FileName:
                    type: string
                    description: The name of the converted file
                    example: output_20260114.txt
  /file-conversion/download-source:
    get:
      description: Download the original source file that was uploaded for conversion.
      summary: file-conversion/download-source
      tags:
      - File Conversion Endpoints
      operationId: FileConversionDownloadSourceGET
      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: FileConversionID
        in: query
        required: true
        description: The ID of the file conversion job
        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: ''
                  FileConversionID:
                    type: string
                    description: The ID of the file conversion job
                    example: '450'
                  FileContent:
                    type: string
                    description: The original source file content, base64 encoded
                    example: SGVsbG8gV29ybGQ=
                  FileName:
                    type: string
                    description: The name of the original source file
                    example: payments.csv
  /file-conversion/configurations:
    get:
      description: Get available file conversion configurations and supported payment rails for your account.
      summary: file-conversion/configurations
      tags:
      - File Conversion Endpoints
      operationId: FileConversionConfigurationsGET
      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
      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: ''
                  Configurations:
                    type: array
                    description: Array of available file conversion configurations
                    items:
                      type: object
                      properties:
                        ID:
                          type: string
                          description: The configuration ID
                        Name:
                          type: string
                          description: The configuration name
                        Processor:
                          type: string
                          description: The processor/banking partner
                        PaymentRails:
                          type: array
                          description: Supported payment rails
                          items:
                            type: string
  /file-conversion/history:
    get:
      description: Get file conversion history for your account with optional filtering and pagination.
      summary: file-conversion/history
      tags:
      - File Conversion Endpoints
      operationId: FileConversionHistoryGET
      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: Processor
        in: query
        required: false
        description: Filter by processor/banking partner
        schema:
          type: string
          enum:
          - bmo
          - crossriver
          - dc_bank
          - fiserv
          - globalpay
          - goldmansachs
          - mastercard
          - nuvei
          - peoples_trust_bank
          - scotia_bank
          - worldpay
          - bankofamerica
      - name: ConversionStatus
        in: query
        required: false
        description: Filter by conversion status
        schema:
          type: string
          enum:
          - Success
          - Failed
          - Processing
          - Uploaded
          - Submitted
          - Submission In Progress
      - name: PaymentRail
        in: query
        required: false
        description: Filter by payment rail
        schema:
          type: string
          enum:
          - interac
          - eft
          - vopayinstant
          - ach
          - rtp
          - fednow
          - fedwire
          - aft
          - oct
          - creditcard
          - debitcard
      - name: Service
        in: query
        required: false
        description: Filter by service type
        schema:
          type: string
          enum:
          - Debit
          - Credit
      - name: StartDate
        in: query
        required: false
        description: Filter by start date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: EndDate
        in: query
        required: false
        description: Filter by end date (YYYY-MM-DD)
        schema:
          type: string
          format: date
      - name: Limit
        in: query
        required: false
        description: Maximum number of records to return
        schema:
          type: integer
      - name: Offset
        in: query
        required: false
        description: Number of records to skip for pagination
        schema:
          type: integer
      - name: Timezone
        in: query
        required: false
        description: Timezone for date filtering (e.g., America/Toronto)
        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: ''
                  NumberOfRecords:
                    type: integer
                    description: Number of conversion records returned in this response
                    example: '20'
                  Conversions:
                    type: object
                    description: Collection of file conversion history records
                    properties:
                      '0':
                        type: object
                        description: File conversion record
                        properties:
                          FileConversionID:
                            type: string
                            description: Unique ID of the file conversion
                            example: '370'
                          Processor:
                            type: string
                            description: The processor/banking partner used for this conversion
                            example: goldmansachs
                          PaymentRail:
                            type: string
                            description: The payment rail used for this conversion
                            example: rtp
                          AlternatePaymentRail:
                            type: string
                            description: The alternate payment rail used for this conversion
                            example: ''
                          Service:
                            type: string
                            description: 'Service type: Debit or Credit'
                            example: Credit
                          SourceFileName:
                            type: string
                            description: Name of the uploaded source file
                            example: test_file.csv
                          TransactionCount:
                            type: string
                            description: Number of transactions in the file
                            example: '6'
                          TotalAmount:
                            type: string
                            description: Total amount of all transactions in the file
                            example: '11682.00'
                          Currency:
                            type: string
                            description: 3 character currency code
                            example: USD
                          TotalFailed:
                            type: string
                            description: Number of failed transactions
                            example: '0'
                          ConversionStatus:
                            type: string
                            description: Current status of the conversion
                            example: Uploaded
                          ErrorMessage:
                            type: string
                            description: Error message if the conversion failed
                            example: ''
                          IsSubmitted:
                            type: string
                            description: Whether the file has been submitted (1 = yes, 0 = no)
                            example: '0'
                          SubmittedDate:
                            type: string
                            description: Date and time the file was submitted
                            example: '2026-01-05 19:46:38'
                          DateAdded:
                            type: string
                            description: Date and time the file was uploaded
                            example: '2026-01-06 12:43:48'
                          TotalAmounts:
                            type: object
                            description: Breakdown of total amounts by category
                  PaginationMetaData:
                    type: object
                    description: Pagination metadata
                    properties:
                      TotalRecords:
                        type: integer
                        description: Total number of records matching the filter criteria
                        example: '37'
                      Offset:
                        type: integer
                        description: Current offset in the dataset
                        example: '0'
                      Limit:
                        type: integer
                        description: Maximum number of records returned per request
                        example: '20'
  /file-conversion/preprocessing/configurations:
    get:
      description: Get preprocessing configurations for the authenticated account.
      summary: file-conversion/preprocessing/configurations
      tags:
      - File Conversion Endpoints
      operationId: FileConversionPreprocessingConfigurationsGET
      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: SourceFormat
        in: query
        required: false
        description: Filter configurations by source format (e.g., xml, json)
        schema:
          type: string
      - name: SourceFile
        in: query
        required: false
        description: Source file content to analyze for configuration options, base64 encoded
        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: ''
                  Configs:
                    type: object
                    description: Collection of preprocessing configuration options
                    properties:
                      '0':
                        type: object
                        description: Preprocessing configuration record
                        properties:
                          FileConversionPreprocessingID:
                            type: string
                            description: Unique ID of the preprocessing configuration
                            example: '1'
                          ConfigName:
                            type: string
                            description: Name of the preprocessing configuration
                            example: Config - CSV
                          SourceFormat:
                            type: string
                            description: Source file format (e.g., csv, xml, json)
                            example: csv
                          IsDefault:
                            type: string
                            description: Whether this is the default configuration (1 = yes, 0 = no)
                            example: '1'
  /file-conversion/transactions:
    get:
      description: Get formatted transactions for a specific file conversion. Optionally filter by processor to view transactions in the format they would be sent to that provider.
      summary: file-conversion/transactions
      tags:
      - File Conversion Endpoints
      operationId: FileConversionTransactionsGET
      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: FileConversionID
        in: query
        required: true
        description: The ID of the file conversion job
        schema:
          type: string
      - name: Processor
        in: query
        required: false
        description: Filter transactions formatted for a specific processor
        schema:
          type: string
          enum:
          - bmo
          - crossriver
          - dc_bank
          - fiserv
          - globalpay
          - goldmansachs
          - mastercard
          - nuvei
          - peoples_trust_bank
          - scotia_bank
          - worldpay
          - bankofamerica
      - name: IsFailed
        in: query
        required: false
        description: Filter to show only failed transactions
        schema:
          type: boolean
      - name: Limit
        in: query
        required: false
        description: 'Maximum number of records to return (default: 50)'
        schema:
          type: integer
      - name: Offset
        in: query
        required: false
        description: 'Number of records to skip for pagination (default: 0)'
        schema:
          type: integer
      - name: Timezone
        in: query
        required: false
        description: Timezone for date formatting (e.g., America/Toronto)
        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: ''
                  FileConversionID:
                    type: string
                    description: The ID of the file conversion job
                    example: '364'
                  NumberOfRecords:
                    type: integer
                    description: Number of transaction records returned in this response
                    example: '20'
                  Transactions:
                    type: object
                    description: Collection of transaction records from the file conversion
                    properties:
                      '0':
                        type: object
                        description: Transaction record
                        properties:
                          TransactionID:
                            type: string
                            description: Unique ID of the transaction
                            example: '3570113'
                          TransactionReference:
                            type: string
                            description: Reference number for the transaction
                            example: '99900021'
                          ClientReferenceNumber:
                            type: string
                            description: Client-provided reference number
                            example: '99900021'
                          Amount:
                            type: string
                            description: Transaction amount
                            example: '1358407.08'
                          Currency:
                            type: string
                            description: 3 character currency code
                            example: USD
                          EffectiveDate:
                            type: string
                            description: Effective date of the transaction (YYYY-MM-DD)
                            example: '2025-10-04'
                          BeneficiaryName:
                            type: string
                            description: Name of the beneficiary
                            example: Tech Solutions Inc
                          BeneficiaryPhoneNumber:
                            type: string
                            description: Phone number of the beneficiary
                            example: ''
                          BeneficiaryEmail:
                            type: string
                            description: Email address of the beneficiary
                            example: ''
                          BeneficiaryAddress:
                            type: string
                            description: Address line 1 of the beneficiary
                            example: 772 Washington Blvd
                          BeneficiaryAddress2:
                            type: string
                            description: Address line 2 of the beneficiary
                            example: ''
                          BeneficiaryProvince:
                            type: string
                            description: Province/state of the beneficiary
                            example: ''
                          BeneficiaryPostalCode:
                            type: string
                            description: Postal/ZIP code of the beneficiary
                            example: ''
                          BeneficiaryCity:
                            type: string
                            description: City of the beneficiary
                            example: San Francisco
                          BeneficiaryCountry:
                            type: string
                            description: Country of the beneficiary
                            example: United States
                          AccountNumber:
                            type: string
                            description: Bank account number of the beneficiary
                            example: '91391679'
                          BankName:
                            type: string
                            description: Name of the beneficiary's bank
                            example: ''
                          TransactionLabel:
                            type: string
                            description: Label assigned to the transaction
                            example: ''
                          OriginatorRoutingNumber:
                            type: string
                            description: Routing number of the originator
                            example: '75606166'
                          Notes:
                            type: string
                            description: Additional notes for the transaction
                            example: Bonus payment
                          IsFailed:
                            type: string
                            description: Whether the transaction failed (1 = yes, 0 = no)
                            example: '0'
                          FailureReason:
                            type: string
                            description: Reason for failure if the transaction failed
                            example: ''
                  PaginationMetaData:
                    type: object
                    description: Pagination metadata
                    properties:
                      TotalRecords:
                        type: integer
                        description: Total number of transaction records in the file conversion
                        example: '10000'
                      Offset:
                        type: integer
                        description: Current offset in the dataset
                        example: '20'
                      Limit:
                        type: integer
                        description: Maximum number of records returned per request
                        example: '20'