Versapay Orders API

openapi: 3.2.0
info:
  version: 1.3.35
  title: Versapay API Reference Orders 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: 'The Order entity represents the sales document in the ERP system. The fields in the ERP system should be aligned as closely as possible with the fields in the order entity, as the gateway will use these fields for credit card interchange optimization. Contact support@versapay.com for support & setup for Order and/or Order Transactions enablement.

    '
servers:
- url: https://secure.versapay.com
  description: Production
- url: https://uat.versapay.com
  description: UAT
tags:
- name: Orders
  description: 'The Order entity represents the sales document in the ERP system. The fields in the ERP system should be aligned as closely as possible with the fields in the order entity, as the gateway will use these fields for credit card interchange optimization. Contact support@versapay.com for support & setup for Order and/or Order Transactions enablement.

    '
paths:
  /api/imports/order:
    post:
      tags:
      - Orders
      summary: Create an order
      description: 'Create an order.<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>

        '
      operationId: createOrder
      requestBody:
        description: Order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: Created, a JSON showing Order, OrderItems
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 1 order 1 order item(s)
                  identifier:
                    type: string
                    example: ABCD
                  order:
                    type: string
                    $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                    example: You need to sign in or create an account before continuing.
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  description: Error message
    patch:
      tags:
      - Orders
      summary: Update an order
      description: 'Updates an order identified by its "identifier".<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>

        '
      operationId: updateOrder
      requestBody:
        description: Order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: Created, a JSON showing Order, OrderItems
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 1 order 1 order item(s)
                  identifier:
                    type: string
                    example: ABCD
                  order:
                    type: string
                    $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                    example: You need to sign in or create an account before continuing.
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  description: Error message
  /api/exports/orders:
    get:
      tags:
      - Orders
      summary: Export Orders
      description: 'Orders that have been created 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.

        '
      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
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                example:
                  orders:
                    '6': {}
                    '7': {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                    example: You need to sign in or create an account before continuing.
  /api/exports/orders/published:
    get:
      tags:
      - Orders
      summary: Export Orders Published
      description: 'Orders that have been published (excluding draft orders) 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.

        '
      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[extended_attributes]
        in: query
        required: false
        description: When this option (options[extended_attributes][key1]=value1) is present, e.g options[extended_attributes][ecommerce_indicator]=true then only published matching('ecommerce_indicator=true') orders are returned in the result.
        schema:
          type: string
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                example:
                  orders:
                    '6': {}
                    '7': {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                    example: You need to sign in or create an account before continuing.
  /api/exports/order/{identifier}:
    get:
      tags:
      - Orders
      summary: Export/View an Order
      description: 'View an order and its item details.<br><br>


        The path parameter `identifier` is matched to the order''s identifier.

        '
      parameters:
      - name: identifier
        in: path
        required: true
        description: The order identifier.
        schema:
          type: string
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties: null
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                    example: You need to sign in or create an account before continuing.
components:
  schemas:
    OrderItem:
      type: object
      properties:
        number:
          type: string
          description: Order line-item number
        description:
          type: string
          description: Order line-item description
        quantity:
          type: number
          description: Order line-item quantity
        unit_cost_cents:
          type: integer
          description: Order line-item unit price in cents.
        amount_cents:
          type: integer
          description: Order line-item total in cents.
        tax_amount_cents:
          type: integer
          description: Order line-item tax in cents.
        discount_amount_cents:
          type: integer
          description: Order line-item discount in cents.
        product_code:
          type: string
          description: Order line-item product_code.
        category:
          type: string
          description: Order line-item category.
        attributes:
          type: object
          properties: {}
          description: array of key pair items.
        L3_commodity_code:
          type: string
          description: Product commodity code (UNSPSC).
          example: '12345678'
        L3_unit_of_measure:
          type: string
          description: Unit of measure (EA, KG, L).
          example: EA
        L3_discount_amount:
          type: string
          description: Discount amount.
          example: '1.00'
        L3_tax_amount:
          type: string
          description: Tax amount.
          example: '0.50'
        L3_product_code:
          type: string
          description: Product SKU or internal code.
          example: SKU-001
      example:
        number: '1'
        amount_cents: 10000
        description: description
        product_code: product_code
        category: category
        quantity: 1
        unit_cost_cents: 10000
        tax_amount_cents: 100
        discount_amount_cents: 0
        orderitem_attr1: '1111111'
        orderitem2_attr2: '222222'
    SummaryOrderReference:
      type: object
      description: Summary reference of known order
      properties:
        identifier:
          type: string
          description: Associated order identifier
        number:
          type: string
          description: Associated order number
        amount_cents:
          type: number
          description: Associated order amount
    Watermark:
      type: integer
      format: int64
      example: 0
    OrderTransaction:
      type: object
      properties:
        token:
          type: string
          description: Transaction token
        amount_in_cents:
          type: number
          description: Transaction amount in cents
        message:
          type: string
          description: Applies to payport transactions
        link_url:
          type: string
          description: Applies to payport transactions
        type:
          type: string
          description: Literal for payport transaction compatibility 'transaction'
        transaction_type:
          type: string
          description: Literal for payport transaction compatibility 'request_money'
        email:
          type: string
          description: TBD
        state:
          type: string
          description: See the lifecycle states of transaction settlement
        currency:
          type: string
          description: Currency code, based on ISO-4217. E.g. `CAD`, `USD`, `AUD`
        payment_method:
          type: string
          enum:
          - credit_card
          - bank_account
          - gift_card
          - pos_terminal
        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
        transaction_reference:
          type:
          - string
          - 'null'
          description: N/A for payport transaction compatibility
        unique_reference:
          type:
          - string
          - 'null'
          description: N/A for payport transaction compatibility
        from_account:
          type: string
          description: Name of the customer (or card/account holder) from which payment is made
        to_account:
          type: string
          description: Name of the supplier receiving payment
        process_on:
          type:
          - string
          - 'null'
          format: date
          description: N/A for payport transaction compatibility
        created_by_user:
          type: string
          description: Name of the user otherwise the API token appears if the transaction was created with the api.
        auto_withdraw:
          type: boolean
          description: N/A for payport transaction compatibility
        auto_withdrawal_token:
          type:
          - string
          - 'null'
          description: N/A for payport transaction compatibility
        action:
          type: string
          description: Transaction type/action performed
          enum:
          - verify
          - sale
          - credit
          - auth
          - capture
          - refund
          - void
        step_types:
          type: array
          items:
            type: string
        authorization_response:
          type: string
          description: Authorization response code indicating
          enum:
          - 100 (approval)
          - 200 (decline)
          - 400 (error)
          - 500 (unexpected/other)
        avs_response:
          type: string
          description: For credit card payments AVS result code when applicable
          enum:
          - 0 (APPROVED/NOT_REQUESTED)
          - D (V_FULL_MATCH_INTERNATIONAL)
          - F (V_FULL_MATCH_UK)
          - M (V_FULL_MATCH)
          - Y (MATCH_ADDRESS_MATCH_ZIP)
          - X (MATCH_ADDRESS_MATCH_ZIP9)
          - A (MATCH_ADDRESS_NO_ZIP)
          - B (MATCH_ADDRESS_MALFORMED_ZIP)
          - P (MALFORMED_ADDRESS_MATCH_ZIP)
          - W (NO_ADDRESS_MATCH_ZIP9)
          - Z (NO_ADDRESS_MATCH_ZIP)
          - N (NO_MATCH)
          - C (MALFORMED_ADDRESS_MALFORMED_ZIP)
          - S (NOT_SUPPORTED)
          - G (NOT_AVS_PARTICIPANT)
          - I (NOT_VERIFIED)
          - U (NO_DATA_FROM_ISSUER)
          - R (RETRY)
          - 2 (AMEX_NAME_ADDRESS_ZIP)
          - 3 (AMEX_NAME_ADDRESS)
          - 1 (AMEX_NAME_ZIP)
          - 4 (AMEX_NAME)
          - 6 (AMEX_ADDRESS_ZIP)
          - 7 (AMEX_ADDRESS)
          - 5 (AMEX_ZIP)
          - 8 (AMEX_NO_MATCH)
        cvv_response:
          type: string
          description: For credit card payments CVV result code when applicable
          enum:
          - M (MATCH)
          - N (NO_MATCH)
          - P (NOT_PROCESSED)
          - S (NOT_PRESENT)
          - U (NOT_CERTIFIED)
        gateway_response:
          type: object
          description: Raw data returned by underlying gateway
        fx_amount_cents:
          type: integer
          description: When FX is involved, the amount in cents after conversion by the gateway. Not returned if no FX occurred.
        fx_rate:
          type: string
          description: When FX is involved, the exchange rate applied by the gateway. Not returned if no FX occurred.
        credit_card:
          type: object
          description: For credit card payments, raw data returned by underlying gateway
          properties:
            token:
              type: string
              description: Low level token representing the vaulted credit card
        credit_card_bin:
          type: string
          description: When available, the first six digits of the credit card that identify its brand and issuer
        credit_card_masked_number:
          type: string
          description: The credit card number, with all but the last 4 digits replaced with a mask character. Used to verify the last 4 digits and card number length.
        credit_card_brand:
          type: string
          description: The credit card brand
          enum:
          - master
          - visa
          - american_express
          - discover
        credit_card_expiry:
          type: string
          description: Expiration date string for the credit card, in MMYYYY format
        bank_account:
          type: object
          description: For ACH payments, raw data returned by underlying gateway
          properties:
            token:
              type: string
              description: Low level token representing the vaulted credit card
        bank_account_masked_number:
          type: string
          description: The bank account number, with all but the last 4 digits replaced with a mask character
        bank_account_routing:
          type: string
          description: For US bank accounts, the bank routing number
        bank_account_type:
          type: string
          description: For US bank accounts, whether the account is a checking or savings account
          enum:
          - checking
          - savings
        bank_account_check_type:
          type: string
          description: For US bank accounts, whether the account is personal or business
          enum:
          - personal
          - business
        gift_card:
          type: object
          description: For gift card payments, raw data returned by underlying gateway
          properties:
            token:
              type: string
              description: Low level token representing the vaulted gift card
        terminal:
          type: object
          description: For CP EMV terminal payments, raw data returned by underlying gateway
          properties:
            token:
              type: string
              description: Low level token representing the vaulted terminal card
        orders:
          type: array
          description: The order associated with this transaction, if any, for reference detail only
          items:
            $ref: '#/components/schemas/SummaryOrderReference'
        payments:
          type: array
          description: Any C-AR invoicing payments associated with this transaction, if any, for reference detail only
          items:
            $ref: '#/components/schemas/SummaryPaymentReference'
      example:
        token: 1TQ7L54E5L9R
        amount_in_cents: 100
        message: null
        link_url: null
        type: transaction
        transaction_type: request_money
        email: customer+abcmedia@versapay.com
        state: completed
        transaction_reference: null
        unique_reference: null
        from_account: avscvv2b Test
        to_account: ABC Media
        process_on: null
        created_by_user: zoM2xjrzczmgbbGhfHFh
        auto_withdraw: false
        auto_withdrawal_token: null
        action: verify
        payment_method: credit_card
        settlement_token: MAY7USR7KABC
        currency: usd
        step_types:
        - TransactionSteps::CardVerifyStep
        wallet: 2JN6JSR7IBML
        credit_card: CC9DIRFZE61U
        authorization_response: APPROVAL
        avs_response: A
        cvv_response: N
        approved_amount_cents: 100
        gateway_response:
          token: msjhrhcfbily
          gateway_token: '39052'
          authorization_response: APPROVAL
          avs_response: A
          cvv_response: N
          gateway_response:
            response:
              authentication:
                responsestatus: success
                sessionid: DH6rQ0CRxuScK9ZDJjcuhXBodyadb^ae
              content:
                refname: '90144'
                update:
                - customer:
                    refname: customer
                    responsestatus: failure
                    errors:
                      error:
                        number: '102.021'
                        description: name is invalid
                - contact:
                    refname: contact
                    responsestatus: failure
                    errors:
                      error:
                        number: '102.021'
                        description: name is invalid
                create:
                - customer:
                    refname: customer
                    responsestatus: success
                    id: '10485'
                    name: avs_cvv2b Test
                - contact:
                    refname: contact
                    responsestatus: success
                    id: '11611'
                - salesdocument:
                    refname: invoice
                    responsestatus: success
                    id: '34054'
                - transaction:
                    refname: 0d18e9e7-f7f6-4ee8-a1f9-6a78219bca01
                    responsestatus: success
                    authorizationcode: '280278'
                    avsresponse: A
                    cvvresponse: N
                    authorizationresponse: APPROVAL
                    id: '39052'
                    hash: '######1111'
                    cardtype.name: Visa
                    accountholder: avs_cvv2b Test
                    amount: '0.00'
                    account.id: '2013'
                    token: c500f04b-a61c-44bd-be03-2c3a423cbbaf
          credit_card:
            token: c500f04b-a61c-44bd-be03-2c3a423cbbaf
        orders:
        - identifier: 1ESZXPKGAJCK
          number: 1ESZXPKGAJCK
          amount_cents: 100
        payments:
        - identifier: 9U4PK6D11H3D
          display_identifier: 9U4PK6D11H3D
          amount_cents: 100
    Order:
      properties:
        watermark:
          $ref: '#/components/schemas/Watermark'
          description: This cannot be an imported attribute, the import will fail
        identifier:
          type: string
          description: order identifier, this may be imported or if not provided it will be generated by cds
        number:
          type: string
          description: Order number, may be unique within supplier., supplied by client.
        currency:
          type: string
          description: Currency code, based on ISO-4217. E.g. `CAD`, `USD`, `AUD`
        amount_cents:
          type: integer
          description: amount of order in cents.
        date:
          type: string
          description: order date
        billing_name:
          type: string
          description: The billing addressee
        billing_address:
          type: string
          description: The first line of the billing street address
        billing_address2:
          type: string
          description: The second line of the billing street address
        billing_city:
          type: string
          description: The billing city
        billing_country:
          type: string
          description: The 3-character alphabetic ISO billing country code
        billing_email:
          type: string
          description: The billing email address associated with the addressee
        billing_telephone:
          type: string
          description: The billing phone number associated with the addressee
        billing_postalcode:
          type: string
          description: The billing post code or ZIP code
        billing_state_province:
          type: string
          description: The billing state or province
        shipping_name:
          type: string
          description: The shipping addressee
        shipping_address:
          type: string
          description: The first line of the shipping street address
        shipping_address2:
          type: string
          description: The second line of the shipping street address
        shipping_city:
          type: string
          description: The shipping city
        shipping_country:
          type: string
          description: The 3-character alphabetic ISO shipping country code
        shipping_email:
          type: string
          description: The shipping email address associated with the addressee
        shipping_telephone:
          type: string
          description: The shipping phone number associated with the addressee
        shipping_postalcode:
          type: string
          description: The shipping post code or ZIP code
        shipping_state_province:
          type: string
          description: The shipping state or province
        customer_identifier:
          type: string
          description: customer identifier, if it was imported
        draft:
          type: boolean
          description: if true order is a draft else can be published
        settlement_token:
          type: string
          description: A settlement token reference (see whoami response structure) representing the merchant/bank processor configuration that should be used for transaction settlement.
          example: MA123XYZABCD
        attributes:
          type: object
          properties: {}
          description: array of key pair items.
        L3_po_number:
          type: string
          description: Purchase order number.
          example: PO12345
        L3_tax:
          type: string
          description: Total tax amount.
          example: '5.00'
        L3_duty:
          type: string
          description: Duty amount (if applicable).
          example: '2.00'
        L3_shipping:
          type: string
          description: Shipping amount.
          example: '1.50'
        L3_ship_from_zip:
          type: string
          description: Origin ZIP code.
          example: '90210'
        L3_ship_from_country:
          type: string
          description: Origin country code (ISO-2).
          example: US
        order_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/OrderTransaction'
      example:
        watermark: 1
        identifier: ABCDF
        number: sh763-h3454-dh3432
        amount_cents: 20000
        currency: cad
        date: '2020-11-01'
        shipping_name: Acme Inc.
        shipping_address: 123 First Lane
        shipping_address2: Suite 600
        shipping_city: New York
        shipping_state_province: NY
        shipping_country: USA
        shipping_email: acme@gmail.com
        shipping_telephone: 555-555-5555
        shipping_postalcode: '90210'
        billing_name: Acme Inc.
        billing_address: 123 First Lane
        billing_address2: Suite 600
        billing_city: New York
        billing_state_province: NY
        billing_country: USA
        billing_email: acme@gmail.com
        billing_telephone: 555-555-5555
        billing_postalcode: '90210'
        order_att1: att1value1
        order_att2: att1value2
        customer_identifier: '123'
        draft: false
        order_items:
        - number: '1'
          amount_cents: 10000
          description: description
          product_code: product_code
          category: category
          quantity: 1
          unit_cost_cents: 10000
          tax_amount_cents: 100
          discount_amount_cents: 0
          orderitem_attr1: '1111111'
          orderitem2_attr2: '222222'
        - number: '2'
          amount_cents: 20000
          description: description
          product_code: product_code
          category: category
          quantity: 1
          unit_cost_cents: 20000
          tax_amount_cents: 200
          discount_amount_cents: 0
          orderitem_attr1: '32222222'
          orderitem2_attr2: '422222'
        transactions: []
    SummaryPaymentReference:
      type: object
      description: Summary reference of known invoicing payment
      properties:
        identifier:
          type: string
          description: Associated invoicing payment identifier
        number:
          type: string
          description: Associated invoicing payment number
        amount_cents:
          type: number
          description: Associated invoicing payment amount
x-tagGroups:
- name: Versapay API
  description: Introduction to the Versapay API.
  tags:
  - Overview
  - Versioning & Compatibility
  - Environments
  - Rate Limits
  - Authentication
  - Webhooks
  - Watermark & Limit
- name: Collaborative AR
  description: Operations available for Collaborative AR integration.
  tags:
  - Reference Data
  - Onboarding
  - Ecommerce Integration
  - Orders
  - Order Transactions
  - Testing Order Transactions
  - Gift Cards
  - Card Present EMV
  - Settlement Reporting
  - Wallets
  - Customers
  - Invoices
  - Autopay
  - Invoicing Payments
  - Divisions
  - Notifications
  - Collaboration
  - File Imports