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 Internal 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: internal
  description: Operations intended only to the iframe front end
paths:
  /sessions/{id}:
    get:
      tags:
      - internal
      summary: get a session
      operationId: getSessionById
      security: []
      description: 'Retrieve a session and its options for constructing an iframe

        '
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      responses:
        '200':
          description: The session was found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionOptionGet'
        '404':
          description: The sesssion was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{id}/tokens:
    post:
      tags:
      - internal
      summary: get a token
      operationId: getToken
      security: []
      description: 'Get the token for a plaintext account number

        '
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '201':
          description: The token was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The session was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          description: Payment method verification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{id}/wallet/{walletid}/creditcards/{creditcardid}:
    patch:
      operationId: updateWalletCreditCard
      security: []
      tags:
      - internal
      summary: update a credit card wallet entry
      description: This operation will update an existing credit card wallet entry with information collected from the buyer.
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      - name: walletid
        in: path
        description: Wallet ID
        required: true
        schema:
          $ref: '#/components/schemas/WalletID'
      - name: creditcardid
        in: path
        description: Credit Card Token
        required: true
        schema:
          $ref: '#/components/schemas/FundToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditCardTokenUpdate'
      responses:
        '202':
          description: The wallet has been updated
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session or wallet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteWalletCreditCard
      security: []
      tags:
      - internal
      summary: remove a credit card wallet entry
      description: This operation will remove an existing credit card entry from a wallet.
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      - name: walletid
        in: path
        description: Wallet ID
        required: true
        schema:
          $ref: '#/components/schemas/WalletID'
      - name: creditcardid
        in: path
        description: Credit Card Token
        required: true
        schema:
          $ref: '#/components/schemas/FundToken'
      responses:
        '202':
          description: The wallet has been updated
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session or wallet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{id}/wallet/{walletid}/bankaccounts/{bankaccountid}:
    patch:
      operationId: updateWalletBankAccount
      security: []
      tags:
      - internal
      summary: update a bank account wallet entry
      description: This operation will update an existing bank account wallet entry with information collected from the buyer.
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      - name: walletid
        in: path
        description: Wallet ID
        required: true
        schema:
          $ref: '#/components/schemas/WalletID'
      - name: bankaccountid
        in: path
        description: Bank Account Token
        required: true
        schema:
          $ref: '#/components/schemas/FundToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountTokenUpdate'
      responses:
        '202':
          description: The wallet has been updated
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session or wallet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteWalletBankAccount
      security: []
      tags:
      - internal
      summary: remove a bank account wallet entry
      description: This operation will remove an existing bank account entry from a wallet.
      parameters:
      - name: id
        in: path
        description: Session ID
        required: true
        schema:
          $ref: '#/components/schemas/SessionID'
      - name: walletid
        in: path
        description: Wallet ID
        required: true
        schema:
          $ref: '#/components/schemas/WalletID'
      - name: bankaccountid
        in: path
        description: Bank Account Token
        required: true
        schema:
          $ref: '#/components/schemas/FundToken'
      responses:
        '202':
          description: The wallet has been updated
        '400':
          description: Bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session or wallet not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SessionOptionGet:
      allOf:
      - type: object
        properties:
          wallet:
            $ref: '#/components/schemas/WalletOptionsGet'
      - $ref: '#/components/schemas/SessionOptionBase'
    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
    GiftCard:
      description: Account information for a gift card transaction
      required:
      - accountNumber
      - expirationMonth
      - expirationYear
      properties:
        accountNumber:
          $ref: '#/components/schemas/CardAccountNumber'
        expirationMonth:
          $ref: '#/components/schemas/CardExpirationMonth'
        expirationYear:
          $ref: '#/components/schemas/CardExpirationYear'
        pin:
          $ref: '#/components/schemas/PIN'
    PIN:
      type: string
      pattern: ^\d{3,12}$
      example: '123'
      description: The PIN
    FundToken:
      type: string
      example: 1NQGAW7N4S7H
      pattern: ^[0-9A-Z]{12}$
      description: The token associated with a funding source
    CardExpirationMonth:
      type: integer
      example: 12
      minimum: 1
      maximum: 12
      description: The expiration month, expressed as an integer from 1 (January) to 12 (December)
    BankRoutingNumber:
      type: string
      example: '123456780'
      pattern: ^\d{8,9}$
      description: The routing number of the financial institution
    CardVerificationValue:
      type: string
      pattern: ^\d{3,4}$
      example: '123'
      description: The card verification value
    TokenRequest:
      description: A request for a new token for the provided payment method
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/PaymentMethod'
        addToWallet:
          type: boolean
          example: false
          description: Set this to true to add the payment method to the customer's wallet
        captchaToken:
          type: string
          example: abc123
          description: Send the Google reCaptcha token for verification.
      anyOf:
      - $ref: '#/components/schemas/CreditCard'
      - $ref: '#/components/schemas/ACH'
      - $ref: '#/components/schemas/GiftCard'
    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
    BankAccountToken:
      description: Token information for a bank acocunt
      required:
      - token
      properties:
        token:
          $ref: '#/components/schemas/FundToken'
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        routingNumber:
          $ref: '#/components/schemas/BankRoutingNumber'
        accountNumberLastFour:
          $ref: '#/components/schemas/AccountNumberLastFour'
        currency:
          $ref: '#/components/schemas/Currency'
        editable:
          type: boolean
          example: true
          description: Set to true if the payment method should be editable by the customer
    CreditCardTokens:
      type: array
      description: A collection of credit card tokens
      items:
        $ref: '#/components/schemas/CreditCardToken'
    BankAccountTokens:
      type: array
      items:
        $ref: '#/components/schemas/BankAccountToken'
    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
    FieldOptions:
      type: array
      description: A collection of field options
      items:
        $ref: '#/components/schemas/FieldOption'
    WalletOptionsGet:
      allOf:
      - $ref: '#/components/schemas/WalletOptionsBase'
      - type: object
        properties:
          creditCardTokens:
            $ref: '#/components/schemas/CreditCardTokens'
          bankAccountTokens:
            $ref: '#/components/schemas/BankAccountTokens'
    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
    AVSOption:
      description: Merchant defined AVS fraud protection settings
      properties:
        rejectAddressMismatch:
          $ref: '#/components/schemas/RejectAddressMismatch'
        rejectPostCodeMismatch:
          $ref: '#/components/schemas/RejectPostCodeMismatch'
        rejectUnknown:
          $ref: '#/components/schemas/RejectAVSUnknown'
    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'
    CreditCardTokenUpdate:
      description: Information for updating an existing credit card token
      properties:
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        expirationMonth:
          $ref: '#/components/schemas/CardExpirationMonth'
        expirationYear:
          $ref: '#/components/schemas/CardExpirationYear'
        cardVerificationValue:
          $ref: '#/components/schemas/CardVerificationValue'
    TokenResponse:
      type: object
      description: A response containing a token
      required:
      - token
      properties:
        token:
          $ref: '#/components/schemas/FundToken'
    CreditCardToken:
      description: Token information for a credit card
      required:
      - token
      properties:
        token:
          $ref: '#/components/schemas/FundToken'
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        accountNumberLastFour:
          $ref: '#/components/schemas/AccountNumberLastFour'
        expirationMonth:
          $ref: '#/components/schemas/CardExpirationMonth'
        expirationYear:
          $ref: '#/components/schemas/CardExpirationYear'
        brand:
          $ref: '#/components/schemas/CardBrand'
        editable:
          type: boolean
          example: true
          description: Set to true if the payment method should be editable by the customer
    CardBrand:
      type: string
      example: visa
      enum:
      - visa
      - master
      - american_express
      - discover
      description: The card brand
    CreditCard:
      description: Account information for a credit card transaction
      required:
      - accountNumber
      - expirationMonth
      - expirationYear
      properties:
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        accountNumber:
          $ref: '#/components/schemas/CardAccountNumber'
        expirationMonth:
          $ref: '#/components/schemas/CardExpirationMonth'
        expirationYear:
          $ref: '#/components/schemas/CardExpirationYear'
        cardVerificationValue:
          $ref: '#/components/schemas/CardVerificationValue'
    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
    CardExpirationYear:
      type: integer
      example: 2030
      minimum: 2020
      maximum: 2099
      description: The expiration year, expressed as a 4-digit year
    AccountHolder:
      type: string
      example: Jane Smith
      minLength: 1
      maxLength: 50
      pattern: ^\S(.*\S)?$
      description: The name of the cardholder
    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
    AccountNumberLastFour:
      type: string
      example: '1234'
      pattern: ^\d{4}$
      description: The last four digits of the account number
    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
    ACH:
      description: Account information for an ACH transaction
      required:
      - accountNumber
      - routingNumber
      - checkType
      - accountType
      - accountHolder
      - currency
      properties:
        accountNumber:
          $ref: '#/components/schemas/BankAccountNumber'
        routingNumber:
          $ref: '#/components/schemas/BankRoutingNumber'
        checkType:
          $ref: '#/components/schemas/CheckType'
        accountType:
          $ref: '#/components/schemas/BankAccountType'
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'
        currency:
          $ref: '#/components/schemas/Currency'
    WalletID:
      type: string
      example: BA25BVH5HCRI
      pattern: ^[0-9A-Z]{12}$
      description: The wallet ID returned by a POST to /wallets
    PaymentMethod:
      type: string
      enum:
      - creditCard
      - ach
      - giftCard
      - applePay
      example: creditCard
      description: The payment type
    CardAccountNumber:
      type: string
      example: '4111111111111111'
      pattern: ^\d{8,19}$
      description: The card account number
    BankAccountType:
      type: string
      enum:
      - checking
      - savings
      example: checking
      description: The type of account (checking or savings)
    RejectPostCodeMismatch:
      type: boolean
      example: true
      description: Set custom avs protection rule to reject or allow credit card transactions with a postal code mismatch
    BankAccountNumber:
      type: string
      example: '123456789'
      pattern: ^\d{4,34}$
      description: The demand deposit account number
    RejectAVSUnknown:
      type: boolean
      example: true
      description: Set custom avs protection rule to reject or allow credit card transactions with a avs unknown
    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
    CheckType:
      type: string
      enum:
      - business
      - personal
      example: business
      description: The type of account (business or personal)
    BankAccountTokenUpdate:
      description: Information for updating an existing bank account token
      properties:
        accountHolder:
          $ref: '#/components/schemas/AccountHolder'