Versapay Invoicing Payments API

openapi: 3.2.0
info:
  version: 1.3.35
  title: Versapay API Reference Invoicing Payments API
  contact:
    name: Versapay Support
    url: https://www.versapay.com/support
    email: support@versapay.com
  x-logo:
    url: https://developers.versapay.com/images/logo.png
  termsOfService: https://www.versapay.com/terms-of-use
  license:
    name: Copyright 2022 Versapay. All Rights Reserved.
  description: 'As a supplier a payments are made by customers for invoices issued to them.


    ## Webhooks


    When using Webhooks, your application will be notified when key events are triggered for a payment.

    '
servers:
- url: https://secure.versapay.com
  description: Production
- url: https://uat.versapay.com
  description: UAT
tags:
- name: Invoicing Payments
  description: 'As a supplier a payments are made by customers for invoices issued to them.


    ## Webhooks


    When using Webhooks, your application will be notified when key events are triggered for a payment.

    '
paths:
  /api/imports/payment:
    post:
      summary: Create a Payment
      description: "Create and update external payments.<br><br>The set of attributes to send in the request body may vary based on the account configuration. Please contact the implementation specialist for more information.<br><br>\nThe request schema for posting a payment for a single invoice is slightly different than that for posting a payment for multiple invoices.\n\nFor instance, sample request for posting payment for a single invoice looks like:\n```\n{\n  \"identifier\": \"PMT0010-05\",\n  \"invoice_number\": \"INV1234-01\",\n  \"amount\": 10000,\n  \"currency\": \"usd\",\n  \"date\": \"2018-01-10\",\n  \"customer_identifier\": \"C1234\",\n  \"customer_name\": \"Acme Inc.\",\n  \"notes\": \"Notes\",\n  \"ref1\": \"1234\",\n  \"ref2\": \"PO# 84767\"\n}\n```\n\n*Note: Customer will be created using the customer_&ast; attributes if it doesn’t already exist at the time of payment import.*\n"
      tags:
      - Invoicing Payments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentImport'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                    example: PMT123
                  message:
                    type: string
                    example: 1 payment 1 invoice amounts
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
  /api/exports/payment/{reference_or_token}:
    get:
      summary: Export/View a Payment
      description: 'View a payment.<br><br>


        The path parameter `reference_or_token` is matched to the payment''s `payment_reference` or `payment_transaction_token`, in that order.

        '
      tags:
      - Invoicing Payments
      parameters:
      - name: reference_or_token
        in: path
        required: true
        description: The payment's `payment_reference` or `payment_transaction_token`.
        schema:
          type: string
      - name: options[export_payment_tree]
        in: query
        schema:
          type: boolean
        required: false
        description: 'When present: `?options[export_payment_tree]=true` then the optional `payment_tree` attribute is included in the response payload.

          '
      - name: options[fx]
        in: query
        schema:
          type: boolean
        required: false
        description: 'When present: `?options[fx]=true` then the optional `fx_rate`, `fx_amount`, and `fx_amount_cents` attributes are included in the response payload.

          '
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /api/exports/payment_amounts:
    get:
      summary: Export Payment Allocations
      description: 'Payments made/recorded to your supplier account from your customers since watermark, limited to 100 payment amounts at a time.<br><br>A consumer should store the last `id` value of each response and include it as the watermark parameter for a subsequent calls.

        '
      tags:
      - Invoicing Payments
      parameters:
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      - name: options[fx]
        in: query
        schema:
          type: boolean
        required: false
        description: 'When present: `?options[fx]=true` then the optional `fx_rate`, `fx_amount`, and `fx_amount_cents` attributes are included in the response payload.

          '
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  payment_amounts:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/PaymentAmount'
              examples:
                payment_amount:
                  value:
                    payment_amounts:
                      '1591737':
                        payment_reference: 4TQRLRCHY7TT
                        checkout_token: XYZABADXO7XX
                        invoice_number: INV001
                        date: '2017-12-16'
                        amount: '10.00'
                        plan_fee: '0.00'
                        payment_amount: '10.00'
                        payment_transaction_amount: '10.00'
                        payment_transaction_token: 8MSPMBLBG6VK
                        payment_method: ' (6567)'
                        payment_from_bank_account: true
                        payment_from_credit_card: false
                        payment_institution_name: null
                        payment_credit_card_brand: null
                        settlement_token: MAY7USR7KABC
                        short_pay_indicator: Y
                        payment_note: null
                        auto_debit_indicator: N
                        invoice_balance: '140.00'
                        payment_timestamp: '2017-12-16T20:18:30-05:00'
                        invoice_division: null
                        invoice_division_number: null
                        invoice_division_name: null
                        pay_to_bank_account: '300987898'
                        pay_to_bank_account_name: ' (7898)'
                        customer_identifier: CUS001
                        customer_name: Acme Inc.
                        status: PAID
                        status_reason: ''
                        payment_source: ARC
                        payment_code: null
                        payment_description: null
                        gateway_authorization_code: TM0FED
                        purchase_order_number: null
                        ref1: null
                        ref2: null
                        ref3: null
                        short_pay_reason_identifier: null
                        short_pay_reason: null
                        dispute_reason_identifier: null
                        dispute_reason: null
                        invoice_amount_paid: '30.00'
                        invoice_identifier: supplier|INV001
                        invoice_date: '2017-11-01'
                        invoice_external_id: null
                        invoice_currency: usd
                        invoice_purchase_order_number: PO-3847
                        invoice_ref1: null
                        invoice_ref2: null
                        invoice_ref3: null
                        cumulative_customer_amount: '10.00'
                        line_item_transactional_amounts:
                        - line_item_number: '001'
                          line_item_payment_amount: '8.00'
                          line_item_balance: '50.00'
                          line_item_short_pay_indicator: Y
                          line_item_payment_note: will pay tomorrow
                          line_item_short_pay_reason_identifier: null
                          line_item_short_pay_reason: null
                          line_item_dispute_reason_identifier: null
                          line_item_dispute_reason: null
                        - line_item_number: '002'
                          line_item_payment_amount: '2.00'
                          line_item_balance: '90.00'
                          line_item_short_pay_indicator: Y
                          line_item_payment_note: will pay tomorrow
                          line_item_short_pay_reason_identifier: null
                          line_item_short_pay_reason: null
                          line_item_dispute_reason_identifier: null
                          line_item_dispute_reason: null
                        batch_number: '2199312514'
                        batch_amount: '48.25'
                        invoice_display_number: INV001
                        invoice_internal_number: INV001
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /api/exports/payments:
    get:
      summary: Export Payments
      description: 'Payments made/recorded to your supplier account from your customers since watermark, limited to 100 payments at a time.<br><br>A consumer should store the last `id` value of each response and include it as the watermark parameter for a subsequent calls.

        '
      tags:
      - Invoicing Payments
      parameters:
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      - name: options[export_payment_tree]
        in: query
        schema:
          type: boolean
        required: false
        description: 'When present: `?options[export_payment_tree]=true` then the optional `payment_tree` attribute is included in the response payload.

          '
      - name: options[fx]
        in: query
        schema:
          type: boolean
        required: false
        description: 'When present: `?options[fx]=true` then the optional `fx_rate`, `fx_amount`, and `fx_amount_cents` attributes are included in the response payload.

          '
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/PaymentResponse'
              examples:
                PAID:
                  value:
                    payments:
                      '13367716':
                        payment_reference: 92YQ57XNXXW5
                        date: '2018-11-05'
                        payment_amount: '20.00'
                        payment_transaction_amount: '20.00'
                        payment_method: ' (9876)'
                        auto_debit_indicator: N
                        payment_timestamp: '2018-11-05T21:51:02-05:00'
                        customer_identifier: 101acme1
                        customer_name: ACME Specialties Inc.
                        status: PAID
                        payment_source: ARC
                        payment_code: null
                        payment_description: null
                        gateway_authorization_code: '123456'
                        pay_to_bank_account: 0888111122
                        pay_to_bank_account_name: ' (1122)'
                        status_reason: ''
                        watermark: 13367716
                        signature: Dc5oLlk3sxAExI7K77BOyN6AAfvqo5naqYFtyxT7%2BCU%3D%0A
                DECLINED:
                  value: "{\n  \"payments\":{\n    \"13367716\":{\n      \"payment_reference\":\"92YQ57XNXXW5\",\n      \"date\":\"2018-11-05\",\n      \"payment_amount\":\"20.00\",\n      \"payment_transaction_amount\":\"20.00\",\n      \"payment_method\":\" (9876)\",\n      \"auto_debit_indicator\":\"N\",\n      \"payment_timestamp\":\"2018-11-05T21:51:02-05:00\",\n      \"customer_identifier\":\"101acme1\",\n      \"customer_name\":\"ACME Specialties Inc.\",\n      \"status\":\"ERROR (DECLINED)\",\n      \"payment_source\":\"ARC\",\n      \"payment_code\":null,\n      \"payment_description\":null,\n      \"gateway_authorization_code\":\"123456\",\n      \"pay_to_bank_account\":\"0888111122\",\n      \"pay_to_bank_account_name\":\" (1122)\",\n      \"status_reason\":\"Invalid routing number.\",\n      \"watermark\":13367716,\n      \"signature\":\"Dc5oLlk3sxAExI7K77BOyN6AAfvqo5naqYFtyxT7%2BCU%3D%0A\"\n    }\n  }\n}\n"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /api/exports/payments/recent:
    get:
      summary: Export Payments Recently Updated
      description: 'Payment records that have been updated in the past 7 days, since watermark, limited to 100 records at a time.<br><br>A consumer should store the last `id` value of each response and include it as the watermark parameter for subsequent calls.

        '
      tags:
      - Invoicing Payments
      parameters:
      - name: watermark
        in: query
        description: The value to base a subsequent extract of the next 100 items.
        schema:
          $ref: '#/components/schemas/Watermark'
      - name: list
        in: query
        description: See Watermark & Limit for more information on response structure.
        schema:
          type: boolean
          example: true
      - name: options[export_payment_tree]
        in: query
        schema:
          type: boolean
        required: false
        description: 'When present: `?options[export_payment_tree]=true` then the optional `payment_tree` attribute is included in the response payload.

          '
      - name: options[fx]
        in: query
        schema:
          type: boolean
        required: false
        description: 'When present: `?options[fx]=true` then the optional `fx_rate`, `fx_amount`, and `fx_amount_cents` attributes are included in the response payload.

          '
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  payments:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/PaymentResponse'
              examples:
                PAID:
                  value:
                    payments:
                      '13367716':
                        payment_reference: 92YQ57XNXXW5
                        date: '2018-11-05'
                        payment_amount: '20.00'
                        payment_transaction_amount: '20.00'
                        payment_method: ' (9876)'
                        auto_debit_indicator: N
                        payment_timestamp: '2018-11-05T21:51:02-05:00'
                        customer_identifier: 101acme1
                        customer_name: ACME Specialties Inc.
                        status: PAID
                        payment_source: ARC
                        payment_code: null
                        payment_description: null
                        gateway_authorization_code: '123456'
                        pay_to_bank_account: 0888111122
                        pay_to_bank_account_name: ' (1122)'
                        status_reason: ''
                        watermark: 13367716
                        signature: Dc5oLlk3sxAExI7K77BOyN6AAfvqo5naqYFtyxT7%2BCU%3D%0A
                DECLINED:
                  value: "{\n  \"payments\":{\n    \"13367716\":{\n      \"payment_reference\":\"92YQ57XNXXW5\",\n      \"date\":\"2018-11-05\",\n      \"payment_amount\":\"20.00\",\n      \"payment_transaction_amount\":\"20.00\",\n      \"payment_method\":\" (9876)\",\n      \"auto_debit_indicator\":\"N\",\n      \"payment_timestamp\":\"2018-11-05T21:51:02-05:00\",\n      \"customer_identifier\":\"101acme1\",\n      \"customer_name\":\"ACME Specialties Inc.\",\n      \"status\":\"ERROR (DECLINED)\",\n      \"payment_source\":\"ARC\",\n      \"payment_code\":null,\n      \"payment_description\":null,\n      \"gateway_authorization_code\":\"123456\",\n      \"pay_to_bank_account\":\"0888111122\",\n      \"pay_to_bank_account_name\":\" (1122)\",\n      \"status_reason\":\"Invalid routing number.\",\n      \"watermark\":13367716,\n      \"signature\":\"Dc5oLlk3sxAExI7K77BOyN6AAfvqo5naqYFtyxT7%2BCU%3D%0A\"\n    }\n  }\n}\n"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    PaymentAmount:
      type: object
      properties:
        payment_reference:
          type: string
          description: The payment identifier
        checkout_token:
          type: string
          description: Correlation key for payment amounts applied during the same payment portal session
        invoice_number:
          type: string
          description: The display number of the invoice for which the payment was made.  If the display number is not available, the number of the invoice for which the payment was made.
        date:
          type: string
          format: date
          description: The payment date, in YYYY-MM-DD format.
        amount:
          type: string
          description: The amount of the payment applied to the invoice, in dollars and cents.
        plan_fee:
          type: string
          description: Payment plan fee amount, in dollars and cents, associated to this invoice.
        payment_amount:
          type: string
          description: The amount of the total payment, excluding fees.
        payment_transaction_amount:
          type: string
          description: The amount of the total payment, including fees.
        payment_transaction_token:
          type: string
          description: The payment transaction token.
        payment_method:
          type: string
          description: The method used to make payment.
        payment_from_bank_account:
          type: string
          description: '`true` if the payment was made using a bank account.

            '
        payment_from_credit_card:
          type: string
          description: '`true` if the payment was made using a credit card.

            '
        payment_institution_name:
          type: string
          description: Institution name, if the payment was made using a bank account.
        payment_credit_card_brand:
          type: string
          description: 'Credit card "association brand", if the payment was made using a credit card. Example: VISA, MASTER

            '
        settlement_token:
          type: string
          description: Token corresponding to the settlement routing/processor profile as enumerated in whoami eg bank transfer processor for ACH/EFT, merchant account for CC, gift card processor, pos/terminal processor
        short_pay_indicator:
          type: string
          description: '`Y` if a short payment was made.

            '
        payment_note:
          type: string
          description: Note accompanying the payment.
        auto_debit_indicator:
          type: string
          description: '`Y` if the payment was made via AutoPay agreement.

            '
        invoice_balance:
          type: string
          description: Remaining balance on the invoice (after the payment is processed).
        payment_timestamp:
          type: string
          description: The ISO8601 timestamp corresponding to payment.
        invoice_division:
          type: string
          description: The division code if any associated with the invoice.
        invoice_division_number:
          type: string
          description: The external division identifier if any associated with the invoice.
        invoice_division_name:
          type: string
          description: The division name if any associated with the invoice.
        pay_to_bank_account:
          type: string
          description: The GL number of the settlement account receiving the payment.
        pay_to_bank_account_name:
          type: string
          description: The display name of the settlement account receiving the payment.
        customer_identifier:
          type: string
          description: The invoice customer identifier.
        customer_name:
          type: string
          description: The invoice customer name.
        status:
          type: string
          description: The payment status.
          enum:
          - IN PROGRESS
          - PAID (UNVERIFIED)
          - REVERSAL
          - ERROR (NSF)
          - ERROR (DECLINED)
          - PAID
        status_reason:
          type: string
          description: Additional information explaining when the payment has failed.
        payment_source:
          type: string
          description: The source of the payment.
        payment_code:
          type: string
          description: The back office payment code (applicable to externally sourced payments).
        payment_description:
          type: string
          description: The back office payment description (applicable to externally sourced payments).
        gateway_authorization_code:
          type: string
          description: The underlying gateway authorization code.
        purchase_order_number:
          type: string
          description: The purchase order number entered at the time of making a prepayment.
        ref1:
          type: string
          description: The reference number or string entered at the time of making a prepayment.
        ref2:
          type: string
          description: Same as above.
        ref3:
          type: string
          description: Same as above.
        short_pay_reason_identifier:
          type: string
          description: Short pay reason code, if set up.
        short_pay_reason:
          type: string
          description: Short pay reason description, if set up.
        dispute_reason_identifier:
          type: string
          description: Dispute reason code, if set up.
        dispute_reason:
          type: string
          description: Dispute reason description, if set up.
        invoice_amount_paid:
          type: string
          description: The total amount of payments, in dollars and cents, made to date via Collaborative AR towards this invoice.
        invoice_identifier:
          type: string
          description: The identifier of the invoice for which the payment was made.
        invoice_date:
          type: string
          format: date
          description: Invoice date, in the format YYYY-MM-DD.
        invoice_external_id:
          type: string
          description: The external identifier/reference, if any, of the invoice for which the payment was made.
        invoice_currency:
          type: string
          description: The currency of the invoice for which the payment was made.
        invoice_purchase_order_number:
          type: string
          description: The purchase order number associated to the invoice.
        invoice_ref1:
          type: string
          description: Reference number or string associated to the invoice.
        invoice_ref2:
          type: string
          description: Same as above.
        invoice_ref3:
          type: string
          description: Same as above.
        cumulative_customer_amount:
          type: string
          description: 'The total payment processed for *this* customer under *this* `payment_reference`.

            '
        display_identifier:
          type: string
          description: The value of display_identifier that was provided for the payment; if this was null, this will be the the value of the payment_reference
        line_item_transactional_amounts:
          type: array
          items:
            type: object
            properties:
              line_item_number:
                type: string
                description: Invoice line-item number
              line_item_payment_amount:
                type: string
                description: The amount of the payment applied to the line-item, in dollars and cents.
              line_item_balance:
                type: string
                description: Remaining balance on the line-item (after the payment is processed), in dollars and cents.
              line_item_short_pay_indicator:
                type: string
                description: '`Y` if a short payment was made.

                  '
              line_item_payment_note:
                type: string
                description: Note accompanying the payment at the line-item level.
              line_item_short_pay_reason_identifier:
                type: string
                description: Short pay reason code, if set up.
              line_item_short_pay_reason:
                type: string
                description: Short pay reason description, if set up.
              line_item_dispute_reason_identifier:
                type: string
                description: Dispute reason code, if set up.
              line_item_dispute_reason:
                type: string
                description: Dispute reason description, if set up.
          description: 'Payments applied to invoice line-items. Applicable if accepting short payments at line-item level.

            '
        batch_number:
          type: string
          description: The batch number associated with the payment, if any. If none, the value will be null.
        batch_amount:
          type: string
          description: The batch amount of the batch associated with the payment, if any. If none, the value will be an empty string ""
        invoice_display_number:
          type: string
          description: The display number of the invoice for which the payment was made.
        invoice_internal_number:
          type: string
          description: The number of the invoice for which the payment was made.
        fx_rate:
          type: string
          description: Optional. The exchange rate used for the payment.
        fx_amount:
          type: string
          description: Optional. The amount of the payment in the gateway currency.
        fx_amount_cents:
          type: number
          description: Optional. The amount of the payment in the gateway currency in cents.
    PaymentImport:
      type: object
      required:
      - identifier
      properties:
        identifier:
          type: string
          description: 'Payment identifier; must be unique within supplier. May appear multiple times in a single file if payment was applied to multiple invoices.

            '
        amount_cents:
          type: integer
          description: 'The amount of total payment, in cents.


            Note: when providing data in a CSV layout this field can also be represented as payment_total; however, in JSON layout this field must be called amount_cents.


            Note 2: For the update of a payment originated in Versapay, only the total payment amount without fees, or the total payment amount with fees will be accepted.  Any other value will be rejected.'
        date:
          type: string
          format: date
          description: Payment date, in the format YYYY-MM-DD.
        currency:
          type: string
          description: Currency code, based on ISO-4217.
        invoice_number:
          type: string
          description: 'Invoice number associated with this payment (if payment covers single invoice).

            If payment covers multiple invoices, provide `payment_amounts_attributes` instead.

            '
        payment_code:
          type: string
          description: Payment code
        payment_description:
          type: string
          description: Description corresponding to payment code.
        payment_amounts_attributes:
          type: array
          description: Applicable only when payment covers multiple invoices.
          items:
            type: object
            properties:
              invoice_number:
                type: string
                description: Invoice number associated with this payment.
              amount:
                type: integer
                description: Amount paid towards this invoice.
              notes:
                type: string
                description: Payment note
              purchase_order_number:
                type: string
                description: Purchase order number to link this payment to an invoice.
              ref1:
                type: string
                description: An additional reference number that could link this payment to an invoice. E.g. policy number, contract number, etc.
              ref2:
                type: string
                description: Same as above.
              ref3:
                type: string
                description: Same as above.
              line_number:
                type: string
                description: (Optional) Invoice line item to which this payment amount should apply.
              short_pay_reason_identifier:
                type: string
                description: Short pay reason code, if set up.
              reason_type:
                type: string
                description: 'Indicates the type of short payment. Acceptable values are:

                  * `short_pay`: The payment amount is less than expected.

                  * `dispute`: A dispute will be opened for the invoice.


                  Note: If the value is `dispute`, it means an invoice dispute will be initiated.'
              match_at:
                type: string
                format: date
                description: The date when an external payment was matched outside of Versapay and/or via Cash application processing, in the format YYYY-MM-DD.
              remit_invoice_date:
                type: string
                format: date
                description: Original invoice date supplied with remittance. May or may not match actual invoice.
              remit_invoice_amount_cents:
                type: integer
                description: Original invoice amount supplied with remittance. May or may not match actual invoice.
              remit_invoice_discount_cents:
                type: integer
                description: 'Original invoice discount taken supplied with remittance. May or may not match actual invoice.


                  When part of an external payment, this value will be applied towards the invoice in addition to the value passed in `amount`.

                  '
              remit_customer_number:
                type: string
                description: A customer identifier or number associated with the invoice. This may or may not match what is in Collaborative AR. It is for information purposes only, for manual matching if invoice# is missing.
              remit_customer_name:
                type: string
                description: A customer name associated with the invoice. This may or may not match what is in Collaborative AR. It is for information purposes only, for manual matching if invoice# is missing.
              division:
                type: string
                description: 'Division code, if divisions are set up.


                  This value takes precedence over the value specified in the header data.

                  '
        division:
          type: string
          description: 'Division code, if divisions are set up.


            This value will be used for all `payment_amounts_attributes` that do not specify their own `division` attribute.

     

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/versapay/refs/heads/main/openapi/versapay-invoicing-payments-api-openapi.yml