Device Payment Validate Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/nmi/json-schema/nmi-payment-device-validate-request-schema.json",
  "title": "Device Payment Validate Request",
  "description": "Validate request when payment details are collected on the device. Include POI prompt fields here rather than on `/v5/payments/validate`.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nmi-devices-api-openapi.yml#/components/schemas/PaymentDeviceValidateRequest",
  "allOf": [
    {
      "$ref": "#/$defs/PoiDevicePromptFields"
    },
    {
      "type": "object",
      "properties": {
        "industry": {
          "type": "string",
          "enum": [
            "retail",
            "restaurant",
            "ecommerce",
            "moto",
            "lodging"
          ],
          "description": "Industry type for the transaction"
        },
        "signature_image": {
          "type": "string",
          "description": "Base64 encoded signature image"
        },
        "billing_address": {
          "$ref": "#/$defs/BillingAddressRest"
        },
        "merchant_defined_fields": {
          "$ref": "#/$defs/MerchantDefinedFields"
        }
      }
    }
  ],
  "$defs": {
    "BillingAddressRest": {
      "type": "object",
      "title": "Billing Address & Information",
      "description": "Billing address for a payment transaction request.",
      "properties": {
        "method": {
          "type": "string",
          "enum": [
            "initial_recurring",
            "recurring",
            "installment"
          ],
          "description": "Recurring or installment classification for the processor.\n\n- `initial_recurring`: First transaction in a recurring sequence only.\n- `recurring`: Later charges in that sequence.\n- `installment`: Installment transactions; use `number` and `total` on supported processors.\n\nWhich values apply depends on the processor."
        },
        "number": {
          "type": "integer",
          "minimum": 0,
          "maximum": 99,
          "description": "Specify installment billing number, on supported processors. For use when `billing.method` is set to \"installment\""
        },
        "total": {
          "type": "number",
          "minimum": 0,
          "description": "Specify installment billing total on supported processors. For use when `billing.method` is set to \"installment\""
        },
        "first_name": {
          "type": "string",
          "maxLength": 50,
          "description": "Cardholder's first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 50,
          "description": "Cardholder's last name"
        },
        "company": {
          "type": "string",
          "maxLength": 100,
          "description": "Cardholder's company"
        },
        "address1": {
          "type": "string",
          "maxLength": 100,
          "description": "Card billing address"
        },
        "address2": {
          "type": "string",
          "maxLength": 100,
          "description": "Card billing address, line 2"
        },
        "city": {
          "type": "string",
          "maxLength": 50,
          "description": "Card billing city"
        },
        "state": {
          "type": "string",
          "maxLength": 50,
          "description": "Card billing state. Format: `CC`"
        },
        "zip": {
          "type": "string",
          "maxLength": 20,
          "description": "Card billing zip code"
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "description": "Card billing country. Country codes are as shown in ISO 3166-1 alpha-2. Format: `CC`"
        },
        "phone": {
          "type": "string",
          "description": "Billing phone number"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Billing email address"
        },
        "fax": {
          "type": "string",
          "maxLength": 50,
          "description": "Billing fax number"
        },
        "cell_phone": {
          "type": "string",
          "description": "Billing cell phone number"
        },
        "website": {
          "type": "string",
          "maxLength": 255,
          "description": "Website (invoice-specific field)"
        },
        "drivers_license_number": {
          "type": "string",
          "maxLength": 20,
          "description": "Driver's license number"
        },
        "drivers_license_dob": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "Driver's license date of birth. Format: `YYYY-MM-DD`"
        },
        "drivers_license_state": {
          "type": "string",
          "maxLength": 2,
          "description": "Driver's license state. Format: `CC`"
        },
        "payment_details": {
          "$ref": "#/$defs/PaymentDetails"
        },
        "cardholder_auth": {
          "$ref": "#/$defs/CardholderAuth"
        }
      }
    },
    "CardholderAuth": {
      "type": "object",
      "title": "Cardholder Authentication",
      "description": "Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields.",
      "oneOf": [
        {
          "type": "object",
          "title": "3-D Secure",
          "description": "EMV 3-D Secure authentication result fields.",
          "additionalProperties": false,
          "required": [
            "status",
            "cavv"
          ],
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "verified",
                "attempted"
              ],
              "description": "Set 3D Secure condition. Value used to determine E-commerce indicator (ECI)."
            },
            "cavv": {
              "type": "string",
              "maxLength": 50,
              "description": "Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded."
            },
            "xid": {
              "type": "string",
              "maxLength": 50,
              "description": "Cardholder authentication transaction id. Format: base64 encoded."
            },
            "three_ds_version": {
              "type": "string",
              "maxLength": 10,
              "description": "3DSecure version (for example `2.1.0` or `2.2.0`)."
            },
            "directory_server_id": {
              "type": "string",
              "maxLength": 50,
              "description": "Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            }
          }
        },
        {
          "type": "object",
          "title": "Decrypted wallet (Apple Pay / Google Pay)",
          "description": "Wallet authentication for decrypted Apple Pay or Google Pay payments.",
          "additionalProperties": false,
          "required": [
            "cavv"
          ],
          "properties": {
            "cavv": {
              "type": "string",
              "maxLength": 50,
              "description": "Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field)."
            },
            "eci": {
              "type": "string",
              "maxLength": 10,
              "description": "Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field)."
            }
          }
        }
      ]
    },
    "MerchantDefinedFields": {
      "type": "object",
      "title": "Merchant Defined Fields",
      "description": "Custom fields configured in the merchant control panel under Settings → Merchant Defined Fields (`field_1` through `field_20`).",
      "properties": {
        "field_1": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 1"
        },
        "field_2": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 2"
        },
        "field_3": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 3"
        },
        "field_4": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 4"
        },
        "field_5": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 5"
        },
        "field_6": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 6"
        },
        "field_7": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 7"
        },
        "field_8": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 8"
        },
        "field_9": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 9"
        },
        "field_10": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 10"
        },
        "field_11": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 11"
        },
        "field_12": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 12"
        },
        "field_13": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 13"
        },
        "field_14": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 14"
        },
        "field_15": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 15"
        },
        "field_16": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 16"
        },
        "field_17": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 17"
        },
        "field_18": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 18"
        },
        "field_19": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 19"
        },
        "field_20": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 20"
        }
      }
    },
    "PaymentDetails": {
      "title": "Payment Details",
      "description": "Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, wallet payloads, or **retail card-present** data from a card reader. Do not combine fields from different variants.",
      "oneOf": [
        {
          "type": "object",
          "title": "Credit card",
          "description": "Non-tokenized credit card data.",
          "additionalProperties": false,
          "required": [
            "card_number",
            "card_exp"
          ],
          "properties": {
            "card_number": {
              "type": "string",
              "description": "Credit card number"
            },
            "card_exp": {
              "type": "string",
              "description": "Credit card expiration date. Format: `MMYY`"
            },
            "card_cvv": {
              "type": "string",
              "maxLength": 4,
              "description": "The card security code."
            }
          }
        },
        {
          "$ref": "#/$defs/RetailUnencryptedMagneticStripe"
        },
        {
          "$ref": "#/$defs/RetailMagTekMagensaEncryptedSwipe"
        },
        {
          "$ref": "#/$defs/RetailIdTechEncryptedSwipe"
        },
        {
          "$ref": "#/$defs/RetailIdTechEncryptedKeyed"
        },
        {
          "$ref": "#/$defs/RetailIngenicoChip"
        },
        {
          "$ref": "#/$defs/RetailIngenicoSwipe"
        },
        {
          "$ref": "#/$defs/RetailIngenicoNfc"
        },
        {
          "$ref": "#/$defs/RetailIngenicoKeyed"
        },
        {
          "$ref": "#/$defs/RetailMobileSdkEncryptedPayment"
        },
        {
          "type": "object",
          "title": "ACH / check",
          "description": "Bank account (ACH) details for this transaction.",
          "additionalProperties": false,
          "required": [
            "check_name",
            "check_aba",
            "check_account",
            "account_type",
            "account_holder_type",
            "sec_code"
          ],
          "properties": {
            "check_name": {
              "type": "string",
              "maxLength": 50,
              "description": "The name on the customer's ACH account"
            },
            "check_aba": {
              "type": "number",
              "description": "The customer's bank routing number"
            },
            "check_account": {
              "type": "number",
              "description": "The customer's bank account number"
            },
            "account_type": {
              "type": "string",
              "enum": [
                "checking",
                "savings"
              ],
              "description": "The type of ACH account the customer has"
            },
            "account_holder_type": {
              "type": "string",
              "enum": [
                "personal",
                "business"
              ],
              "description": "The type of ACH account the customer has"
            },
            "sec_code": {
              "type": "string",
              "enum": [
                "PPD",
                "WEB",
                "TEL",
                "CCD",
                "POP",
                "RCK"
              ],
              "description": "The Standard Entry Class code of the ACH transaction"
            },
            "check_number": {
              "type": "string",
              "maxLength": 20,
              "description": "Check number"
            }
          }
        },
        {
          "type": "object",
          "title": "Payment token",
          "description": "Single-use or vault token from [Payment Component](../docs/payment-component) or [Collect.js](https://secure.networkmerchants.com/merchants/resources/integration/integration_portal.php#cjs_methodology) (not Apple Pay / Google Pay).",
          "additionalProperties": false,
          "required": [
            "payment_token"
          ],
          "properties": {
            "payment_token": {
              "type": "string",
              "description": "The tokenized version of the customer's card or check information"
            }
          }
        },
        {
          "type": "object",
          "title": "Apple Pay",
          "description": "Encrypted payment data from the Apple Pay SDK.",
          "additionalProperties": false,
          "required": [
            "applepay_payment_data"
          ],
          "properties": {
            "applepay_payment_data": {
              "type": "string",
              "description": "The encrypted token created when integration directly to the Apple Pay SDK"
            }
          }
        },
        {
          "type": "object",
          "title": "Google Pay",
          "description": "Encrypted payment data from the Google Pay SDK.",
          "additionalProperties": false,
          "required": [
            "googlepay_payment_data"
          ],
          "properties": {
            "googlepay_payment_data": {
              "type": "string",
              "description": "The encrypted token created when integration directly to the Google Pay SDK"
            }
          }
        },
        {
          "type": "object",
          "title": "Decrypted Apple Pay",
          "description": "Merchant-decrypted Apple Pay payment data.",
          "additionalProperties": false,
          "required": [
            "decrypted_applepay_data",
            "card_number",
            "card_exp"
          ],
          "properties": {
            "decrypted_applepay_data": {
              "type": "boolean",
              "enum": [
                true
              ],
              "description": "Set to `true` when submitting merchant-decrypted Apple Pay data."
            },
            "card_number": {
              "type": "string",
              "description": "Credit card number"
            },
            "card_exp": {
              "type": "string",
              "description": "Credit card expiration date. Format: `MMYY`"
            }
          }
        },
        {
          "type": "object",
          "title": "Decrypted Google Pay",
          "description": "Merchant-decrypted Google Pay payment data.",
          "additionalProperties": false,
          "required": [
            "decrypted_googlepay_data",
            "card_number",
            "card_exp"
          ],
          "properties": {
            "decrypted_googlepay_data": {
              "type": "boolean",
              "enum": [
                true
              ],
              "description": "Set to `true` when submitting merchant-decrypted Google Pay data."
            },
            "card_number": {
              "type": "string",
              "description": "Credit card number"
            },
            "card_exp": {
              "type": "string",
              "description": "Credit card expiration date. Format: `MMYY`"
            }
          }
        }
      ]
    },
    "PoiDevicePromptFields": {
      "title": "POI Device Prompt Fields",
      "type": "object",
      "description": "Optional Cloud EMV POI device prompts for asynchronous device payment-request endpoints. New integrations should send these fields on `/v5/devices/{device_id}/payment-requests/{sale|auth|credit|validate}`, not on `/v5/payments/*`.",
      "properties": {
        "poi_prompt_tip": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "When set to `\"true\"`, allows the cardholder to enter or confirm a tip amount on the POI device."
        },
        "poi_prompt_quicktip_amounts": {
          "type": "string",
          "description": "Comma-delimited quick tip amount options to show on the POI device. Valid only when `poi_prompt_tip` is `\"true\"`."
        },
        "poi_prompt_quicktip_percentages": {
          "type": "string",
          "description": "Comma-delimited quick tip percentage options to show on the POI device. Valid only when `poi_prompt_tip` is `\"true\"`."
        },
        "poi_enable_keyed": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "When set to `\"true\"`, provides the option for the cardholder to key in card details on the POI device."
        },
        "poi_require_keyed": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "When set to `\"true\"`, requires keyed entry on the POI device. Cannot be `\"true\"` at the same time as `poi_enable_keyed`."
        },
        "poi_keyed_type": {
          "type": "string",
          "enum": [
            "cnp",
            "card_present",
            "ecommerce",
            "mail_order",
            "telephone_order"
          ],
          "description": "Keyed transaction type to use when keyed entry is enabled or required on the POI device."
        },
        "poi_prompt_cvv": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "Controls whether the POI device prompts for CVV during keyed entry."
        },
        "poi_prompt_zip": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "When set to `\"true\"`, requires ZIP or postal code entry on the POI device."
        },
        "poi_prompt_signature": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "Controls whether the POI device prompts for signature capture where supported."
        },
        "poi_prompt_amount_confirmation": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "When set to `\"true\"`, requires the cardholder to confirm the amount on the POI device."
        },
        "poi_automatic_fall_forward": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "Controls fall-forward behavior on supported POI devices."
        },
        "poi_enable_void": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "description": "When set to `\"true\"`, allows the device flow to void the transaction if the cardholder removes the card before finalization."
        }
      }
    },
    "RetailIdTechEncryptedKeyed": {
      "type": "object",
      "title": "Retail ID Tech M130 encrypted keyed",
      "description": "Card-present encrypted keyed entry data from an ID Tech M130 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "encrypted_data"
      ],
      "properties": {
        "encrypted_data": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIdTechEncryptedSwipe": {
      "type": "object",
      "title": "Retail ID Tech M130 encrypted swipe",
      "description": "Card-present encrypted swipe data from an ID Tech M130 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "encrypted_track_1",
        "encrypted_track_2"
      ],
      "properties": {
        "encrypted_track_1": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_3": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIngenicoChip": {
      "type": "object",
      "title": "Retail Ingenico Telium 2 chip (EMV)",
      "description": "Card-present EMV chip payment from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "entry_mode",
        "emv_auth_request_data",
        "emv_device",
        "verification_method",
        "encrypted_ksn",
        "encrypted_track_2"
      ],
      "properties": {
        "entry_mode": {
          "type": "string",
          "enum": [
            "emv_icc"
          ],
          "description": "The type of transaction data to be processed."
        },
        "emv_auth_request_data": {
          "type": "string",
          "description": "EMV data for the transaction as received from the EMV chip card SDK."
        },
        "emv_device": {
          "type": "string",
          "enum": [
            "ingenico_rba"
          ],
          "description": "The EMV-capable card reader."
        },
        "verification_method": {
          "type": "string",
          "enum": [
            "signature",
            "offline_pin",
            "offline_pin_signature",
            "none"
          ],
          "description": "Method used to verify the EMV transaction."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIngenicoKeyed": {
      "type": "object",
      "title": "Retail Ingenico Telium 2 keyed",
      "description": "Card-present encrypted keyed entry from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "entry_mode",
        "emv_device",
        "encrypted_ksn",
        "encrypted_track_2"
      ],
      "properties": {
        "entry_mode": {
          "type": "string",
          "enum": [
            "keyed"
          ],
          "description": "The type of transaction data to be processed."
        },
        "emv_device": {
          "type": "string",
          "enum": [
            "ingenico_rba"
          ],
          "description": "The EMV-capable card reader."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIngenicoNfc": {
      "type": "object",
      "title": "Retail Ingenico Telium 2 NFC",
      "description": "Card-present NFC payment from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "entry_mode",
        "emv_device",
        "encrypted_ksn",
        "encrypted_track_2"
      ],
      "properties": {
        "entry_mode": {
          "type": "string",
          "enum": [
            "nfc_msd"
          ],
          "description": "The type of transaction data to be processed."
        },
        "emv_device": {
          "type": "string",
          "enum": [
            "ingenico_rba"
          ],
          "description": "The EMV-capable card reader."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIngenicoSwipe": {
      "type": "object",
      "title": "Retail Ingenico Telium 2 swipe",
      "description": "Card-present encrypted swipe from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "entry_mode",
        "emv_device",
        "encrypted_ksn",
        "encrypted_track_1",
        "encrypted_track_2"
      ],
      "properties": {
        "entry_mode": {
          "type": "string",
          "enum": [
            "swiped",
            "swiped_emv_fallback"
          ],
          "description": "The type of transaction data to be processed."
        },
        "emv_device": {
          "type": "string",
          "enum": [
            "ingenico_rba"
          ],
          "description": "The EMV-capable card reader."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_1": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailMagTekMagensaEncryptedSwipe": {
      "type": "object",
      "title": "Retail MagTek Magensa encrypted swipe",
      "description": "Card-present payment using encrypted magnetic stripe data from a MagTek Magensa reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "magnesafe_track_1",
        "magnesafe_track_2"
      ],
      "properties": {
        "magnesafe_track_1": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        },
        "magnesafe_track_2": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        },
        "magnesafe_magneprint": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        },
        "magnesafe_ksn": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        },
        "magnesafe_magneprint_status": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        }
      }
    },
    "RetailMobileSdkEncryptedPayment": {
      "type": "object",
      "title": "Mobile SDK encrypted payment",
      "description": "RSA-encrypted card data from the NMI Mobile SDK (iOS/Android). Use in place of raw card number, expiration, and CVV. Set `industry` to `retail` on the payment request when processing as a card-present transaction.",
      "additionalProperties": false,
      "required": [
        "encrypted_payment"
      ],
      "properties": {
        "encrypted_payment": {
          "type": "string",
          "description": "Encrypted payment blob returned by the Mobile SDK."
        }
      }
    },
    "RetailUnencryptedMagneticStripe": {
      "type": "object",
      "title": "Retail unencrypted magnetic stripe",
      "description": "Card-present payment using raw magnetic stripe data from a card reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "track_1",
        "track_2"
      ],
      "properties": {
        "track_1": {
          "type": "string",
          "description": "Raw magnetic stripe data."
        },
        "track_2": {
          "type": "string",
          "description": "Raw magnetic stripe data."
        },
        "track_3": {
          "type": "string",
          "description": "Raw magnetic stripe data."
        }
      }
    }
  }
}