openapi: 3.2.0
info:
  version: '3.0'
  title: Payments API
  description: Payment endpoint accepting nested JSON payloads with rail-specific params.
  contact:
    email: help@vopay.com
servers:
- url: https://earthnode-dev.vopay.com/api
tags:
- name: Payments
paths:
  /v3/payment:
    post:
      summary: payment
      description: Create a payment. Common top-level fields plus nested DebitorInformation, CreditorInformation and RailSpecificInfo objects.
      tags:
      - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - AccountID
              - Key
              - Signature
              - PaymentRail
              - Amount
              - Currency
              properties:
                AccountID:
                  type: string
                  example: '{{AccountID}}'
                Key:
                  type: string
                  example: '{{Key}}'
                Signature:
                  type: string
                  example: '{{Signature}}'
                PaymentRail:
                  type: string
                  example: sepainstant
                  description: Identifier of the rail to use (e.g. sepainstant, ach, eft)
                Amount:
                  type: string
                  example: '100'
                Currency:
                  type: string
                  example: EUR
                Notes:
                  type: string
                  example: Test SEPA Instant Transaction
                DebitorInformation:
                  type: object
                  properties:
                    Name:
                      type: string
                      example: Tim
                    AddressInfo:
                      type: object
                      description: Optional address object
                    VirtualAccountID:
                      type: integer
                      example: 1
                CreditorInformation:
                  type: object
                  properties:
                    Name:
                      type: string
                      example: Timmy Spears
                RailSpecificInfo:
                  description: Rail-specific parameters. Use `PaymentRail` to determine which schema applies.
                  oneOf:
                  - $ref: '#/components/schemas/Rail_SEPAInstant'
                  - $ref: '#/components/schemas/Rail_EFT'
                  - $ref: '#/components/schemas/Rail_Default'
      responses:
        '200':
          description: Payment created (or validation errors returned)
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    example: true
                  ErrorMessage:
                    type: string
                    example: ''
                  TransactionID:
                    type: string
                    example: '3571926'
                  Status:
                    type: string
                    example: pending
                    enum:
                    - pending confirmation
                    - in progress
                    - blocked by financial institution
                    - pending approval
                    - received
                    - complete
                    - declined
                    - waiting
                    - settled
                    - cancellation requested
                    - cancelled
                    - failed
                    - successful
                    - sent
                    - requested
                    - pending
              example:
                Success: true
                ErrorMessage: ''
                TransactionID: '3571926'
                Status: pending
components:
  schemas:
    Rail_Default:
      type: object
      description: Default empty rail-specific object
      properties: {}
    Rail_SEPAInstant:
      type: object
      properties:
        CreditorIBAN:
          type: string
          example: IE29AIBK93115212345678
        RemittanceInformation:
          type: string
      required:
      - CreditorIBAN
    Rail_EFT:
      type: object
      properties:
        BeneficiaryAccountNumber:
          type: string
        BeneficiarySortCode:
          type: string