openapi: 3.2.0
info:
  description: "# Introduction\n\nThe Versapay e-commerce solution is composed of several components. First, is a server-side API that allows your application to configure a new payment session, manage customer wallets, create orders, and initiate payments. In addition, there is a client-side JavaScript SDK that enables your web applicaiton to accept secure payment data via an iframe hosted by Versapay. Your sensitive payment data will not transit your application when you use the iframe, so your application will have a reduced PCI scope.\n\nIn order to accept a payment, the general flow is to first create a session using the server-side API. Once a session ID has been generated by the Versapay server and returned to your application, your client-side code can use that session ID to initialize the Versapay payment SDK, which will, in turn, render the iframe. Next, the customer will interact with the iframe to specify a payment method. The SDK will return a token representing that payment method to your client-side code. Your client-side code must return the token to your server-side code, which will then use the original session ID and the token to create an order and take a payment. Finally, your ERP or order fulfillment system will query the Versapay cloud platform for new orders so that they may be created and fulfilled via your standard workflow.\n\n# Environments\n\nThe UAT environment is a useful sandbox for integration testing where transaction settlements are simulated using test account numbers and test dollar amounts.\n\nhttps://ecommerce-api-uat.versapay.com\n\nOnce integration testing is complete via the UAT environment, start sending your requests to the production URL to start moving money and/or integrating with Versapay.\n\nhttps://ecommerce-api.versapay.com\n\n# Server-side Setup\n\n## Wallets\n\nIf the customer checking out through your website is a known customer with an authenticated account and you would like the Versapay cloud platform to offer to store payment methods for future use, you can generate a Wallet ID for that customer. To do so, POST to the `/wallets` endpoint to generate a new Wallet ID. Once the Wallet ID has been returned to your application, it is your application's responsibility to associate the Wallet ID with the customer record in your web application so that it can be provided to the API each time the customer checks out.\n\nIf the customer already has a Wallet ID associated with their record in your application, that Wallet ID should be provided in the session creation request.\n\n## Sessions\n\nEach checkout attempt requires that your application request a Session ID from the Versapay API. This is accomplished by POSTing to the `/sessions` endpoint. When creating a new session, you must specify your Versapay gateway credentials, which consist of an API Token and an API Key. These are passed in the http request using an authorization header. In addition, you may pass session options to the API that control the behavior, and verbiage of the checkout experience in the hosted iframe.\n\nSession options also allow you to specify a Wallet ID for the current customer in the `wallet` element. \n\nThe POST request to the `/sessions` endpoint will return a Session ID to your application. That Session ID must be passed to your client-side JavaScript so that it can initialize the Versapay Checkout Client SDK.\n\n# Versapay Checkout Client SDK\n\nThe Versapay Checkout JavaScript SDK can be used to initialize a hosted iframe within your ecommerce website that contains all the fields needed to complete a secure credit card transaction while keeping your website out of scope for PCI compliance.\n\n## Setup\n\n### Install the Versapay library\n\nTo start using the SDK, load the library from the hosting url. This will give you access to functions in the versapay module.\n\n    <!-- Load the client component -->\n    <script src=\"https://ecommerce-api-uat.versapay.com/client.js\"></script>\n\n    <!-- Call functions in the versapay module -->\n    <script>\n        var client = versapay.initClient(sessionId)\n    </script>\n\n### Get a Session ID\n\nThe Versapay SDK requires a Session ID generated by a [server side API request](#serversetup). Once you have a Session ID, you can initialize the client.\n\n### Create a client instance\n\nCreate an instance of the client class using the versapay.initClient function, passing the session key generated on the server side as a parameter.\n\n    <script>\n        var client = versapay.initClient(sessionId)\n    </script>\n\n### Add styles or fonts\n\nAlthough you can use the default styles and fonts of the checkout iframe, it can also be configured with styles and fonts that fit with your ecommerce website. These can be passed as optional parameters to the initClient function.\n\nThe styles parameter should be sent as a json object of CSS selectors and properties. See the CSS Styling section for a list of supported properties and DOM element IDs that can be used in selectors.\n\nThe fontUrls parameter should be an array of urls that point to an embeddable Google Fonts link.\n\n    <script>\n        var styles = {\n            html: {\n                \"font-family\": \"DotGothic16\",\n            },\n            input: {\n                \"font-size\": \"14pt\",\n                \"color\": \"#3A3A3A\",\n            },\n            select: {\n                \"font-size\": \"14pt\",\n                \"color\": \"#3A3A3A\",\n            }\n        };\n\n        var fontUrls = ['https://fonts.googleapis.com/css2?family=DotGothic16&display=swap']\n\n        var client = versapay.initClient(clientSession, styles, fontUrls)\n    </script>\n\n### Create DOM elements\n\nThe hosted iframe requires two DOM elements, a form and an empty DOM element within the form to act as a container for the iframe. You will likely also want to include a way to submit the form, like a Submit or Pay button, and a way to display submission errors.\n\n    <form id='form'>\n        <div id='container'></div>\n        <div>\n            <button id='submit'>Pay</button>\n            <span id='submitError'></span>\n        </div>\n    </form>\n    <script>\n        const form = document.querySelector('#form')\n        const submit = document.querySelector('#submit')\n        const submitError = document.querySelector('#submitError')\n    </script>\n\n### Initialize the iframe and create a frame promise\n\nInitialize the iframe using the client.initFrame async function, passing the empty DOM element and the desired iframe width and height as parameters. Since the iframe will resize its internal elements responsively to fit the width and height specified here, these parameters can be assigned programmatically to ensure that the checkout page displays correctly on all devices. The return value of this function is a promise object that is resolved when the iframe and fields are ready.\n\n    <script>\n        const form = document.querySelector('#form')\n        const submit = document.querySelector('#submit')\n        \n        var containerWidth = document.documentElement.clientWidth > 500 ? '500px' : '400px'\n\n        versapay.initClient(clientSession).then(function(client) {\n            frameReadyPromise = client.initFrame(document.querySelector('#container'), '500px', containerWidth)\n        }\n    </script>\n\n### Listen for payment method approval events <a name=\"approvalevents\"></a>\n\nWhen the selected payment method is approved or rejected by the hosted iframe, an approval promise is fulfilled or rejected in the instance of the client class. Use the client.onApproval(onResolve, onReject) function to return the results of the approval promise, where the parameters are callback functions to execute when the promise is fullfilled or rejected.\n\n    <script>\n        client.onApproval(\n            onResolve = result => {\n                // this is the callback function to use when the payment method is approved\n                console.log(result)\n            }, \n            onReject = error => {\n                // this is the callback function to use when the payment method is rejected\n                console.log(error)\n            }\n        )\n    </script>\n\n### Create the submit event handler\n\nAdd an event handler for the form submit event that calls the client.submitEvents() function. The submitEvents() function triggers a submission on the form in the hosted iFrame, which returns the results of that submission to the [approval event in the client instance.](#approvalevents). Note that the form.then() function is also useful for handling any other code that should be executed once the frame and fields are ready for input, like setting a form submit button to enabled.\n\n    <script>\n        const form = document.querySelector('#form')\n        const submit = document.querySelector('#submit')\n\n        versapay.initClient(clientSession).then(function(client) {\n            frameReadyPromise = client.initFrame(document.querySelector('#container'), '500px', '250px')\n\n            frameReadyPromise.then(function() {\n                submit.removeAttribute('disabled')\n\n                form.addEventListener('submit', function(event) {\n                    event.preventDefault()\n                    var tokenPromise = client.submitEvents()\n                })\n            })\n        }\n    </script>\n\n### Receive the payment method submission results from the iframe\n\nAfter the form is submitted, the results of the payment method submission are passed back to the iframe. The submission results are returned to the client library using the [approval promise](#approvalevents) on the client instance. When the approval promise is fulfilled, the results will return a json object containing the payment type and a token that can be passed back up to the server side code to perform a charge, authorization, etc. If the approval promise is rejected, the error can be used in the callback function.\n    \n    <script>\n        client.onApproval(\n            onResolve = result => {\n                // this is the callback function to use when the payment method is approved\n                // the result.paymentType value can be used to conditionally handle different payment types (creditCard, ach, giftCard)\n                // the result.token value can be passed up to the server-side code to use for other operations\n                console.log(`Payment Type: ${result.paymentType}, Token: ${result.token}`)\n            }, \n            onReject = error => {\n                // this is the callback function to use when the payment method is rejected\n                // the error.paymentType value can be used to conditionally handle different payment types (creditCard, ach, giftCard)\n                // the error.error value will contain more information about the payment method error\n                console.log(`Payment Type: ${error.paymentType}, Error: ${error.error}`)\n                submitError.textContent = error.error\n            }\n        )\n    </script>\n\n## Example HTML Code\n    <!DOCTYPE html>\n    <html lang=\"en\">\n        <head>\n            <meta charset=\"UTF-8\" />\n            <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n            <title>Versapay JS Ecomm Library Demo</title>\n            <style>\n                @import url('https://fonts.googleapis.com/css2?family=Yantramanav&display=swap');\n            </style>\n        </head>\n        <body>\n            <form id='form'>\n                <div id='container' style=\"height:358px; width:500px\"></div>\n                <div style=\"position: relative\">\n                    <button id='submit' style=\n                        \"width:420px; \n                        height:50px; \n                        color:#FFFFFF; \n                        font-size: 18px; \n                        line-height: 20px;\n                        background-color:#002233; \n                        margin: 16px 40px;\n                        font-family: Yantramanav;\n                        padding-left: 20px;\n                        border: 0;\n                        border-radius: 3px;\"\n                    >Pay</button>\n                    <span id='submitError' style=\n                        \"line-height: 14px;\n                        color: red;\n                        font-size: 12px;\n                        font-family: Yantramanav;\n                        position: absolute;\n                        bottom: -5px;\n                        left: 42px;\"\n                    ></span>\n                </div>\n            </form>\n            <script src=\"https://ecommerce-api-uat.versapay.com/client.js\"></script>\n            <script>\n                const form = document.querySelector('#form')\n                const submit = document.querySelector('#submit')\n                const submitError = document.querySelector('#submitError')\n\n                // Get the Session ID from the server side API.\n                var clientSession = '24653110-410a-49f2-9ee3-477f6bfe06b3'\n\n                // Set any custom styles to pass to the iFrame.\n                var styles = {\n                    // html: {\n                    //     \"font-family\": \"DotGothic16\",\n                    // },\n                    // input: {\n                    //     \"font-size\": \"14pt\",\n                    //     \"color\": \"#3A3A3A\",\n                    // },\n                    // select: {\n                    //     \"font-size\": \"14pt\",\n                    //     \"color\": \"#3A3A3A\",\n                    // }\n                };\n\n                // Set custom google font families to display in the iFrame.\n                var fontUrls = ['https://fonts.googleapis.com/css2?family=DotGothic16&display=swap']\n\n                // Initialize the client with the Session ID and any custom styles or fonts.\n                var client = versapay.initClient(clientSession, styles, fontUrls)\n\n                // Instantiate the iFrame from client object using the target dom and set the frame height and width.\n                var frameReadyPromise = client.initFrame(document.querySelector('#container'), '358px', '500px')\n\n                // Initialize approval callbacks to handle success/failure of tokenization or payment in the iframe\n                client.onApproval(\n                    onResolve = result => {\n                        // this is the callback function to use when the payment method is approved\n                        // the result.paymentType value can be used to conditionally handle different payment types (creditCard, ach, giftCard)\n                        // the result.token value can be passed up to the server-side code to use for other operations\n                        console.log(result)\n                    }, \n                    onReject = error => {\n                        // this is the callback function to use when the payment method is rejected\n                        // the error.paymentType value can be used to conditionally handle different payment types (creditCard, ach, giftCard)\n                        // the error.error value will contain more information about the payment method error\n                        console.log(error)\n                    }\n                )\n\n                // The client.initFrame function returns a promise that resolves when the iFrame is ready to be used\n                frameReadyPromise.then(function() {       \n                    // Code that is placed here will run after the iFrame is ready.\n                    // For instance, you can disable your form submit button and \n                    // only allow clicks after the iFrame is ready.\n                    submit.removeAttribute('disabled')\n\n                    // Add an event listener for your form submission.\n                    form.addEventListener('submit', function(event) {\n                        event.preventDefault()\n\n                        // Use submit to trigger the submit event on the form in the iframe\n                        client.submitEvents()\n                    })\n                })\n            </script>\n        </body>\n    </html>    \n\n## CSS Styling\n\n---\n\n### DOM Element IDs\n\nThe following IDs can be used as CSS selectors in the style json that can be passed as a parameter to initClient.\n\n    #accountNoDiv\n    #accountNo\n    #cardholderNameDiv\n    #cardholderName\n    #expDateDiv\n    #expDate\n    #expMonth\n    #expYear\n    #cvvDiv\n    #cvv\n\n### Supported CSS properties\n\n    '-moz-appearance',\n    '-moz-osx-font-smoothing',\n    '-moz-tap-highlight-color',\n    '-moz-transition',\n    '-webkit-appearance',\n    '-webkit-font-smoothing',\n    '-webkit-tap-highlight-color',\n    '-webkit-transition',\n    'appearance',\n    'background-color',\n    'border',\n    'border-radius',\n    'color',\n    'direction',\n    'font',\n    'font-family',\n    'font-size',\n    'font-size-adjust',\n    'font-stretch',\n    'font-style',\n    'font-variant',\n    'font-variant-alternates',\n    'font-variant-caps',\n    'font-variant-east-asian',\n    'font-variant-ligatures',\n    'font-variant-numeric',\n    'font-weight',\n    'letter-spacing',\n    'line-height',\n    'margin',\n    'margin-top',\n    'margin-right',\n    'margin-bottom',\n    'margin-left',\n    'opacity',\n    'outline',\n    'padding',\n    'padding-top',\n    'padding-right',\n    'padding-bottom',\n    'padding-left',\n    'text-align',\n    'text-shadow',\n    'transition',\n    'flex-direction',\n    'flex-flow',\n    'flex-basis',\n    'flex-shrink',\n    'flex-grow',\n    'flex-wrap',\n    'justify-content',\n    'flex',\n    'align-self',\n    'align-items',\n    'align-content'  \n# Server-side Orders and Payments\n\nOnce your client-side script has received the payment token from the Versapay Client SDK and passed it to your server-side application, you need to use the API to create and order and process a payment. Depending on your checkout scenario, this can be done in a single step, or it can be split into multiple steps to support more complex flows. \n\nWhen an order is created, it has a status of either Finalized or Not Finalized. Only Finalized orders will be brought into your ERP or order fulfillment system. If you are attempting to use a single payment method for the order, you can use the one-step process. The one-step process will automatically Finalize the order if the payment is approved. Other scenarios, which may include zero payments (e.g., the order is being paid via a Purchase Order) or multiple payments (e.g., the order payment is being split between two credit cards), require that you:\n1. Create the order without any payments\n2. Request zero or more payments necessary for order completion\n3. If all payments are successful, Finalize the order to signal that it is ready to be retrieved by the ERP or order fulfillment system\n\n## Create an Order\n\nWhen you POST to `/sessions/{sessionId}/sales`, the Versapay system will create an order based on the data that you supply in your request. Your POST can include a `payment` element if the intent is to take exactly one payment for the order.\n\nIf successful, the API will return an Order ID, the Finalization status, and, if a payment was requested, the payment response information.\n\nAlways check the Finalization status of the order. If the payment was approved, but the order was not automatically finalized, you should send a PATCH request to finalize the order yourself.\n\n## Create a Payment\n\nIf your intent is to process multiple payments against an order, and you have already create the order and have an Order ID, you can POST to the `/sessions/{sessionId}/sales/{saleId}/payments` endpoint to request a payment against the order.\n\nOnce all payments are successful, you must finalize the order.\n\n## Order Finalization\n\nWhen you are finished with an order and are ready for the ERP or order fulfillment system to retrieve it, you can finalize the order by sending a PATCH request to the `/sessions/{sessionId}/sales/{saleId}` endpoint. If finalization is successful, the API will return a response indicating that the order has been finalized.\n"
  version: 2.0.0
  title: Versapay Ecommerce Developers API
  contact:
    url: https://www.versapay.com
    name: Versapay
    email: support@versapay.com
  x-logo:
    url: https://developers.versapay.com/images/logo.png
servers:
- url: https://{subdomain}.versapay.com/api/v2
  variables:
    subdomain:
      default: ecommerce-api
tags:
- name: developers
  description: Operations available to developers
paths:
  /sessions:
    post:
      tags:
      - developers
      summary: create a session
      operationId: createSession
      security: []
      description: "By passing in the appropriate options, you can create an iframe \nsession with options that meet your needs. If successful, this operation will return a session id in the \"id\" property of the response. Your application can then use that session id when initializing our client-side JavaScript library, which will inject an iframe into your page. The iframe will be rendered using the options you specify. When sensitive payment data is entered into the iframe, it will be tokenized by our servers, and that token will be returned to your page via JavaScript. Your page should post that token back to your server and use it to make a follow-on API call to create an order and payment.                                                                                                                                                                                                                                                                                                                                 \n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRequest'
        description: These are the options for the iframe session
        required: true
      responses:
        '201':
          description: The session has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
        '401':
          description: Gateway authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /wallets:
    post:
      operationId: createWallet
      security: []
      tags:
      - developers
      summary: create a wallet for a known user
      description: This operation will create a new wallet for a known customer. If the customer is using a guest checkout feature, wallets should not be used until an account is created and the customer becomes known.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimpleRequest'
        description: These are the authentication parameters for the gateway
        required: true
      responses:
        '201':
          description: The wallet has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletResponse'
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{id}/sales:
    post:
      operationId: createSale
      security: []
      tags:
      - developers
      summary: process a sale
      description: This operation will send a new order to our server. You can optionally process a payment transaction in a single operation. However, if you need to process multiple payment transactions, you should use the seperate payment operation. If a payment is included, the order will be finalized if the payment is approved. If a payment is not included, the order will not be finalized, and a PATCH request will be required to finalize the order once all payments have been processed.
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sale'
      responses:
        '201':
          description: The order has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaleResponse'
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Gateway authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{id}/sales/{saleid}:
    patch:
      operationId: finalizeSale
      security: []
      tags:
      - developers
      summary: update a sale
      description: This operation will update an existing order on our server to finalize the order and get it ready for import.
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      - name: saleid
        in: path
        description: Order ID
        required: true
        schema:
          $ref: '#/components/schemas/OrderID'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - gatewayAuthorization
              properties:
                gatewayAuthorization:
                  $ref: '#/components/schemas/GatewayAuthorization'
      responses:
        '202':
          description: The order has been updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaleResponse'
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{id}/sales/{saleid}/payments:
    post:
      operationId: createPayment
      security: []
      tags:
      - developers
      summary: process a payment
      description: Use this operation to authorize a payment instrument for an existing sale. You must have already created the sale.
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      - name: saleid
        in: path
        description: Order ID
        required: true
        schema:
          $ref: '#/components/schemas/OrderID'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - gatewayAuthorization
              allOf:
              - type: object
              - properties:
                  gatewayAuthorization:
                    $ref: '#/components/schemas/GatewayAuthorization'
              - $ref: '#/components/schemas/Payment'
      responses:
        '201':
          description: The payment has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Gateway authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentError'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{id}/balance/{giftcardid}:
    get:
      operationId: getGiftCardBalance
      security: []
      tags:
      - developers
      summary: check the balance of a payment method fund token
      description: This operation will check the balance of a payment method using the fund token. This will result in an error for payment method types other than gift cards.
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      - name: giftcardid
        in: path
        description: Gift Card Token
        required: true
        schema:
          $ref: '#/components/schemas/FundToken'
      responses:
        '200':
          description: The balance was retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '404':
          description: The balance could not be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{id}/applepay-validatemerchant:
    post:
      tags:
      - developers
      summary: Validate Apple Pay merchant
      description: Validate Apple Pay merchant session for Apple Pay processing.
      parameters:
      - name: id
        in: path
        description: Session ID for the Apple Pay validation request.
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplePayMerchantValidationRequest'
      responses:
        '200':
          description: Merchant validation successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplePayMerchantValidationResponse'
        '400':
          description: Bad request due to invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session not found or invalid session ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: Error
      properties:
        message:
          type: string
          example: not found
          description: The error message
        errors:
          type: array
          description: A collection of errors
          items:
            type: object
            description: An error
            properties:
              path:
                type: string
                example: /foo
                description: The path that generated the error
              message:
                type: string
                example: not found
                description: The error message
    ApplePayMerchantValidationRequest:
      type: object
      required:
      - validationUrl
      - applePayConfig
      properties:
        validationUrl:
          type: string
          format: uri
          description: The URL provided by Apple for merchant validation.
          example: https://apple-pay-gateway.apple.com/paymentservices/startSession
        applePayConfig:
          type: object
          description: The configuration details for Apple Pay validation.
          properties:
            merchantIdentifier:
              type: string
              description: The unique merchant identifier for Apple Pay.
              example: merchant.com.example
            displayName:
              type: string
              description: Display name of the merchant or store.
              example: Versapay Example Store
            initiativeContext:
              type: string
              description: A value provided based on the initiative.
              example: example.com
            merchantCapabilities:
              type: array
              items:
                type: string
              description: Capabilities supported by the merchant, e.g., 3D Secure.
              example:
              - supports3DS
            supportedNetworks:
              type: array
              items:
                type: string
              description: Supported card networks for Apple Pay.
              example:
              - amex
              - masterCard
              - visa
            ecommSubdomain:
              type: string
              description: The subdomain used for ecommerce API.
              example: ecommerce-api-uat
            countryCode:
              type: string
              description: The country code for the transaction.
              example: US
            currencyCode:
              type: string
              description: The currency code for transaction.
              example: USD
    Balance:
      description: Balance of payment method
      properties:
        balance:
          type: number
          format: float
          example: 10.5
          minimum: 0
          description: The balance of the payment method.
    PaymentError:
      type: object
      description: Error
      properties:
        message:
          type: string
          example: not found
          description: The error message
        errors:
          type: array
          description: A collection of errors
          items:
            type: object
            description: An error
            properties:
              path:
                type: string
                example: /foo
                description: The path that generated the error
              response_code:
                type: string
                example: '999'
                description: The error response code from the gateway
              message:
                type: string
                example: not found
                description: The error message
    Address:
      type: object
      description: An Address
      properties:
        contactFirstName:
          type: string
          example: Alice
          description: The contact's first name
        contactLastName:
          type: string
          example: Smith
          description: The contact's last name
        companyName:
          type: string
          example: My Company
          description: The company name
        address1:
          type: string
          example: 123 Main Street
          minLength: 1
          description: The first address line
        address2:
          type: string
          example: Apartment 1
          description: The second address line
        city:
          type: string
          example: Anytown
          minLength: 1
          description: The city
        stateOrProvince:
          type: string
          example: CA
          description: The state or province code
        postCode:
          type: string
          minLength: 1
          maxLength: 10
          example: '55555'
          description: The ZIP or post code
        country:
          type: string
          pattern: ^[A-Z]{2}$
          example: US
          description: The uppercase 2-character ISO country code
        phone:
          type: string
          example: 555-555-5555
          description: The phone number
        email:
          type: string
          format: email
          example: me@example.com
          description: The email address for the contact
    FundToken:
      type: string
      example: 1NQGAW7N4S7H
      pattern: ^[0-9A-Z]{12}$
      description: The token associated with a funding source
    SaleLine:
      type: object
      description: A line item for an order
      required:
      - number
      - description
      - price
      - quantity
      properties:
        type:
          type: string
          example: Item
          default: Item
          description: The type of sales line (e.g., Item, Resource, G/L Account), which is a valid sales line type for the ERP system
        number:
          type: string
          example: I1234
          minLength: 1
          maxLength: 255
          description: The identifier for the current sales line, as known by the ERP system (e.g., if the type is Item, this would be the item identifier)
        description:
          type: string
          example: Widget
          description: A description for the sales line
        price:
          type: number
          format: float
          example: 1.5
          description: The unit price, expressed in the currency of the current sale
        quantity:
          type: number
          format: float
          example: 2
          description: The quantity sold
        discount:
          type: number
          format: float
          example: 0
          minimum: 0
          description: The line discount amount, expressed as a positive value, in the currency of the current sale
        l3TaxAmount:
          type: number
          format: float
          minimum: 0
          example: 0.53
          description: Level 3 tax amount allocated to this line item, required for CEDP
        l3CommodityCode:
          type: string
          maxLength: 20
          example: '33712'
          description: Level 3 commodity code for this line item, required for CEDP
        l3UnitOfMeasure:
          type: string
          maxLength: 12
          example: EA
          description: Level 3 unit of measure for this line item, required for CEDP
        l3ProductCode:
          type: string
          maxLength: 255
          example: I1234
          description: Level 3 product code/SKU for this line item, required for CEDP
        l3DiscountAmount:
          type: number
          format: float
          minimum: 0
          example: 0
          description: Level 3 discount amount allocated to this line item, required for CEDP
        lineAttributes:
          type: object
          description: Extra dynamic fields that can be added to the sales line with key-value pairs
          example:
            line_attribute1: attribute1value
            line_attribute2: attribute2value
    ACHPaymentType:
      description: A credit card payment type definition
      properties:
        paymentType:
          $ref: '#/components/schemas/PaymentType'
      example:
        name: ach
        label: Bank Account
        promoted: false
        fields:
        - name: accountType
          label: Account Type
          errorLabel: Account type
        - name: checkType
          label: Check Type
          errorLabel: Check type
        - name: accountHolder
          label: Account Holder
          errorLabel: Account holder
        - name: routingNo
          label: Routing Number
          errorLabel: Routing number
        - name: achAccountNo
          label: Account Number
          errorLabel: Bank account number
    PaymentType:
      description: A payment type or method
      required:
      - name
      - label
      properties:
        name:
          $ref: '#/components/schemas/PaymentMethod'
        label:
          type: string
          example: Credit Card
          description: The payment method display name
        promoted:
          type: boolean
          example: false
          description: Set this option to true to display this payment method in a promoted fashion
        fields:
          $ref: '#/components/schemas/FieldOptions'
      additionalProperties:
        description: Reserved for future use
        oneOf:
        - type: object
        - type: boolean
        - type: integer
        - type: string
        - type: number
    CreditCardPaymentType:
      description: A credit card payment type definition
      properties:
        paymentType:
          $ref: '#/components/schemas/PaymentType'
      example:
        name: creditCard
        label: Payment Card
        promoted: false
        fields:
        - name: cardholderName
          label: Cardholder Name
          errorLabel: Cardholder name
        - name: accountNo
          label: Account Number
          errorLabel: Credit card number
        - name: expDate
          label: Expiration Date
          errorLabel: Expiration date
        - name: cvv
          label: Security Code
          errorLabel: Security code
    Sale:
      required:
      - gatewayAuthorization
      - billingAddress
      - shippingAddress
      - orderNumber
      - lines
      - currency
      type: object
      description: Order details
      properties:
        gatewayAuthorization:
          $ref: '#/components/schemas/GatewayAuthorization'
        customerNumber:
          type: string
          example: C1234
          description: The Customer identifier as the Customer is known to the ERP system
        orderNumber:
          type: string
          example: SO1234
          minLength: 1
          description: The Order identifier generated by the shopping cart system
        purchaseOrderNumber:
          type: string
          example: PO1234
          description: The customer's Purchase Order Number
        shippingAgentNumber:
          type: string
          example: USPS
          description: The Shipping Agent identifier known to the ERP system
        shippingAgentServiceNumber:
          type: string
          example: PRIORITY
          description: The Shipping Agent Service identifier known to the ERP system
        shippingAgentDescription:
          type: string
          example: United States Postal Service
          description: A description or name of the Shipping Agent
        shippingAgentServiceDescription:
          type: string
          example: Priority Mail
          description: A description or name of the Shipping Agent Service
        currency:
          $ref: '#/components/schemas/Currency'
        orderAttributes:
          type: object
          description: Extra dynamic fields that can be added to the sales order with key-value pairs
          example:
            order_attribute1: attribute1value
            order_attribute2: attribute2value
        billingAddress:
          $ref: '#/components/schemas/Address'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        l3PoNumber:
          type: string
          maxLength: 255
          example: PO1234
          description: Level 3 purchase order number/reference, required for CEDP
        l3Tax:
          type: number
          format: float
          minimum: 0
          example: 1.05
          description: Level 3 total tax amount for the order, required for CEDP
        l3Duty:
          type: number
          format: float
          minimum: 0
          example: 0
          description: Level 3 duty/customs amount for the order, required for CEDP
        l3Shipping:
          type: number
          format: float
          minimum: 0
          example: 5.05
          description: Level 3 shipping/freight amount for the order, required for CEDP
        l3ShipFromZip:
          type: string
          maxLength: 10
          example: '55555'
          description: Level 3 ship-from/origin postal code, required for CEDP
        l3ShipFromCountry:
          type: string
          pattern: ^$|^[A-Z]{2}$
          example: US
          description: Level 3 ship-from/origin country, required for CEDP.
        lines:
          type: array
          minItems: 1
          description: The collection of order lines
          items:
            $ref: '#/components/schemas/SaleLine'
        shippingAmount:
          type: number
          format: float
          example: 5.05
          minimum: 0
          description: The amount being charged for freight, expressed in the currency of the current sale
        discountAmount:
          type: number
          format: float
          example: 2.25
          minimum: 0
          description: The order-level discount amount, expressed as a positive value, in the currency of the current sale
        taxAmount:
          type: number
          format: float
          example: 1.05
          minimum: 0
          description: The sales tax amount, expressed in the currency of the current sale
        payment:
          $ref: '#/components/schemas/Payment'
        payments:
          $ref: '#/components/schemas/Payments'
        applePayPayment:
          $ref: '#/components/schemas/ApplePayPayment'
    FieldOptions:
      type: array
      description: A collection of field options
      items:
        $ref: '#/components/schemas/FieldOption'
    Payment:
      type: object
      description: A Payment
      required:
      - type
      - token
      - amount
      - capture
      properties:
        type:
          $ref: '#/components/schemas/PaymentMethod'
        settlementToken:
          $ref: '#/components/schemas/SettlementToken'
        token:
          $ref: '#/components/schemas/FundToken'
        amount:
          type: number
          format: float
          example: 6.85
          minimum: 0
          description: The payment amount, expressed in the currency of the current sale
        capture:
          type: boolean
          example: false
          description: Indicates if the gateway should capture the funds or just reserve the funds via an authorization
    SessionResponse:
      type: object
      required:
      - id
      properties:
        id:
          $ref: '#/components/schemas/SessionID'
    ApplePayMerchantValidationResponse:
      type: object
      properties:
        epochTimestamp:
          type: integer
          format: int64
          description: Timestamp when the session starts (in milliseconds since epoch).
        expiresAt:
          type: integer
          format: int64
          description: Timestamp when the session expires (in milliseconds since epoch).
        merchantSessionIdentifier:
          type: string
          description: Unique identifier for the merchant session.
        nonce:
          type: string
          description: Unique random value for session validation.
        merchantIdentifier:
          type: string
          description: Merchant identifier used for Apple Pay.
        domainName:
          type: string
          description: Domain name for the merchant performing validation.
        displayName:
          type: string
          description: Display name of the merchant or store.
        signature:
          type: string
          description: Base64-encoded cryptographic signature for the session.
        operationalAnalyticsIdentifier:
          type: string
          description: Identifier for operational analytics tracking.
        retries:
          type: integer
          format: int32
          description: Number of retries for the validation request.
        pspId:
          type: string
          description: Payment service provider identifier.
      required:
      - epochTimestamp
      - expiresAt
      - merchantSessionIdentifier
      - nonce
      - merchantIdentifier
      - domainName
      - displayName
      - signature
      - operationalAnalyticsIdentifier
      - retries
      - pspId
      example:
        epochTimestamp: 1732209660630
        expiresAt: 1732209660630
        merchantSessionIdentifier: SSHF3882F91426C4F868702059B47B0XXX
        nonce: 5ec8xxxx
        merchantIdentifier: 8C421777BCD9BEDAB86991B8EXXXX
        domainName: example.com
        displayName: Versapay Example Store
        signature: base64EncodedSignature
        operationalAnalyticsIdentifier: identifier
        retries: 0
        pspId: 8C421777BCD9BEDAB86991B8EXXXX
    SessionID:
      type: string
      format: uuid
      example: d290f1ee-6c54-4b01-90e6-d701748f0851
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      description: The session ID returned by a POST to /sessions
    PaymentTypes:
      type: array
      items:
        anyOf:
        - $ref: '#/components/schemas/CreditCardPaymentType'
        - $ref: '#/components/schemas/ACHPaymentType'
        - $ref: '#/components/schemas/GiftCardPaymentType'
        - $ref: '#/components/schemas/ApplePayPaymentType'
      example:
      - name: creditCard
        label: Payment Card
        promoted: false
        fields:
        - name: cardholderName
          label: Cardholder Name
          errorLabel: Cardholder name
        - name: accountNo
          label: Account Number
          errorLabel: Credit card number
        - name: expDate
          label: Expiration Date
          errorLabel: Expiration date
        - name: cvv
          label: Security Code
          errorLabel: Security code
      - name: ach
        label: Bank Account
        promoted: false
        fields:
        - name: accountType
          label: Account Type
          errorLabel: Account type
        - name: checkType
          label: Check Type
          errorLabel: Check type
        - name: accountHolder
          label: Account Holder
          errorLabel: Account holder
        - name: routingNo
          label: Routing Number
          errorLabel: Routing number
        - name: achAccountNo
          label: Account Number
          errorLabel: Bank account number
      - name: giftCard
        label: Gift Card
        promoted: false
        fields:
        - name: gcAccountNo
          label: Account Number
          errorLabel: Gift card number
        - name: expDate
          label: Expiration Date
          errorLabel: Expiration date
        - name: pin
          label: PIN
          errorLabel: PIN
      - name: applePay
        label: ApplePay
        promoted: true
        fields:
        - name: applePay
        - label: applePay
        - errorLabel: applePay
    SessionOptionBase:
      description: An option for a specific session
      additionalProperties:
        oneOf:
        - type: object
        - type: boolean
        - type: integer
        - type: string
        - type: number
      properties:
        fields:
          allOf:
          - $ref: '#/components/schemas/FieldOptions'
          - deprecated: true
        paymentTypes:
          $ref: '#/components/schemas/PaymentTypes'
        avsRules:
          $ref: '#/components/schemas/AVSOption'
    AVSOption:
      description: Merchant defined AVS fraud protection settings
      properties:
        rejectAddressMismatch:
          $ref: '#/components/schemas/RejectAddressMismatch'
        rejectPostCodeMismatch:
          $ref: '#/components/schemas/RejectPostCodeMismatch'
        rejectUnknown:
          $ref: '#/components/schemas/RejectAVSUnknown'
    SessionOptionPost:
      allOf:
      - type: object
        properties:
          wallet:
            $ref: '#/components/schemas/WalletOptionsBase'
      - $ref: '#/components/schemas/SessionOptionBase'
    WalletResponse:
      type: object
      description: A response containing wallet information
      required:
      - walletId
      properties:
        walletId:
          $ref: '#/components/schemas/WalletID'
    SettlementToken:
      type: string
      example: MA1F8B2E87AM
      pattern: ^[0-9A-Z]{12}$
      description: The token associated with the MID to use for settlement in Collaborative AR
    SessionRequest:
      type: object
      description: A new session request
      required:
      - gatewayAuthorization
      - options
      properties:
        gatewayAuthorization:
          $ref: '#/components/schemas/GatewayAuthorization'
        options:
          $ref: '#/components/schemas/SessionOptionPost'
    WalletOptionsBase:
      description: Options for wallet behavior
      properties:
        id:
          $ref: '#/components/schemas/WalletID'
        customerId:
          type: string
          example: 1NQGAW7N4S7H
          minLength: 1
          pattern: ^[0-9A-Z]+$
          description: Set this option to the desired customer id, this can be specified instead of a wallet id
        tokens:
          type: array
          description: An array of payment method tokens associated with the specified wallet ID or customer ID. Use this array to filter the contents of the wallet and only display the specified fund tokens.
          items:
            $ref: '#/components/schemas/FundToken'
        allowAdd:
          type: boolean
          example: true
          description: Set this option to true if the customer should be allowed to add new payment methods to the wallet
        allowEdit:
          type: boolean
          example: true
          description: Set this option to true if the customer should be allowed to edit existing wallet items
        allowDelete:
          type: boolean
          example: true
          description: Set this option to true if the customer should be allowed to remove items from the wallet
        saveByDefault:
          type: boolean
          example: true
          description: Set this option to true if the entry should be saved to the wallet by default
      example:
        id: BA25BVH5HCRI
        customerId: CUST12345
        tokens:
        - 1NQGAW7N4S7H
        allowAdd: true
        allowEdit: true
        allowDelete: true
        saveByDefault: false
    Currency:
      type: string
      example: USD
      pattern: ^[A-Z]{3}$
      description: The uppercase 3-letter ISO currency code
    FieldOption:
      description: Options for a single field
      required:
      - name
      - label
      additionalProperties:
        description: Reserved for future use
        oneOf:
        - type: boolean
        - type: integer
        - type: string
        - type: number
      properties:
        name:
          type: string
          example: expDate
          description: Field name
        label:
          type: string
          example: Expiration Date
          description: Field display name
        placeholder:
          type: string
          example: MM / YY
          description: The placeholder shown on the form
        errorLabel:
          type: string
          example: Please check the Expiration Date
          description: The error message displayed for an invalid entry
        allowLabelUpdate:
          type: boolean
          example: true
          description: Set to true if the client-side code should be allowed to override the label
        id:
          type: string
          example: ddlExpDate
          minLength: 1
          description: The DOM ID of the field
    GiftCardPaymentType:
      description: A credit card payment type definition
      properties:
        paymentType:
          $ref: '#/components/schemas/PaymentType'
      example:
        name: giftCard
        label: Gift Card
        promoted: false
        fields:
        - name: gcAccountNo
          label: Account Number
          errorLabel: Gift card number
        - name: expDate
          label: Expiration Date
          errorLabel: Expiration date
        - name: pin
          label: PIN
          errorLabel: PIN
    ApplePayPaymentType:
      description: A credit card payment type definition
      properties:
        paymentType:
          $ref: '#/components/schemas/PaymentType'
      example:
        name: applePay
        label: ApplePay
        promoted: true
        fields:
        - name: applePay
        - label: applePay
        - errorLabel: applePay
    RejectAddressMismatch:
      type: boolean
      example: true
      description: Set custom avs protection rule to reject or allow credit card transactions with an address mismatch
    OrderID:
      type: string
      minLength: 1
      maxLength: 255
      pattern: ^\S(.*\S)?$
      example: 22A4IMSVNN9T
      description: The order ID returned by a POST to /sessions/{id}/sales
    UnifiedAuthorization:
      type: object
      description: Versapay authentication credentials
      required:
      - apiToken
      - apiKey
      properties:
        apiToken:
          type: string
          example: 1a2B345ZYx0987yYuiTr
          minLength: 1
          description: The API Token for the gateway
        apiKey:
          type: string
          example: 1a2B345ZYx0987yYuiTr
          minLength: 1
          description: The API Key for the gateway
    PaymentMethod:
      type: string
      enum:
      - creditCard
      - ach
      - giftCard
      - applePay
      example: creditCard
      description: The payment type
    WalletID:
      type: string
      example: BA25BVH5HCRI
      pattern: ^[0-9A-Z]{12}$
      description: The wallet ID returned by a POST to /wallets
    SaleResponse:
      type: object
      description: A response containing order identification information
      required:
      - orderId
      - finalized
      properties:
        orderId:
          $ref: '#/components/schemas/OrderID'
        finalized:
          type: boolean
          example: true
          description: The finalization status of the order (only finalized orders will be imported into the ERP)
        payment:
          $ref: '#/components/schemas/PaymentResponse'
    Payments:
      type: array
      minItems: 1
      description: The collection of payments
      items:
        $ref: '#/components/schemas/Payment'
    SimpleRequest:
      type: object
      description: A simple request
      required:
      - gatewayAuthorization
      properties:
        gatewayAuthorization:
          $ref: '#/components/schemas/GatewayAuthorization'
    RejectPostCodeMismatch:
      type: boolean
      example: true
      description: Set custom avs protection rule to reject or allow credit card transactions with a postal code mismatch
    ApplePayPayment:
      type: object
      description: Apple Pay payment details
      required:
      - payment
      - amount
      properties:
        payment:
          type: object
          description: Payment response from Apple Pay
          required:
          - token
          properties:
            token:
              type: object
              description: Tokenized payment data
              required:
              - paymentData
              - paymentMethod
              - transactionIdentifier
              properties:
                paymentData:
                  type: object
                  description: Encrypted payment data
                  required:
                  - data
                  - signature
                  - header
                  - version
                  properties:
                    data:
                      type: string
                      description: Encrypted payment data payload
                      example: encrypted_payment_data_payload
                    signature:
                      type: string
                      description: Encrypted signature for the payment data
                      example: encrypted_signature_for_the_payment_data
                    header:
                      type: object
                      description: Header information for the payment
                      required:
                      - publicKeyHash
                      - ephemeralPublicKey
                      - transactionId
                      properties:
                        publicKeyHash:
                          type: string
                          description: Hash of the public key
                          example: hash_of_the_public_key
                        ephemeralPublicKey:
                          type: string
                          description: Ephemeral public key used for encryption
                          example: ephemeral_key
                        transactionId:
                          type: string
                          description: Unique transaction identifier
                          example: transaction_id
                    version:
                      type: string
                      description: Payment data version
                      example: EC_v1
                paymentMethod:
                  type: object
                  description: Payment method details
                  required:
                  - displayName
                  - network
                  - type
                  properties:
                    displayName:
                      type: string
                      description: Display name of the payment method
                      example: MasterCard 1234
                    network:
                      type: string
                      description: Network of the payment method
                      example: MasterCard
                    type:
                      type: string
                      description: Type of the payment method
                      example: credit
                transactionIdentifier:
                  type: string
                  description: Identifier for the payment transaction
                  example: transaction_id
        amount:
          type: number
          format: float
          description: The payment amount, expressed in the currency of the current sale
          example: 6.85
          minimum: 0
    RejectAVSUnknown:
      type: boolean
      example: true
      description: Set custom avs protection rule to reject or allow credit card transactions with a avs unknown
    GatewayAuthorization:
      oneOf:
      - $ref: '#/components/schemas/UnifiedAuthorization'
    PaymentResponse:
      type: object
      description: A response containing payment details
      required:
      - accountNumberLastFour
      - accountType
      - token
      properties:
        approvalCode:
          type: string
          example: '123456'
          description: The payment transaction approval code
        avsResponseCode:
          type: string
          example: M
          description: The code representing the address validation status of the transaction
        fromAccount:
          type: string
          example: Acme Inc.
          description: The source account or wallet from which the payment was made
        accountNumberLastFour:
          type: string
          example: '1234'
          description: The last four digits of the account number
        accountType:
          type: string
          example: Visa
          description: The type or brand of account being used for payment
        token:
          $ref: '#/components/schemas/FundToken'
        amount:
          type: number
          format: float
          example: 10
          description: The amount approved by the payment processor, which may be less than the amount requested
        transactionId:
          type: string
          description: The transaction ID