--- title: "Create Validation Payment Request on Device" method: POST path: "/v5/devices/{device_id}/payment-requests/validate" tags: ["Devices"] --- # Create Validation Payment Request on Device `POST /v5/devices/{device_id}/payment-requests/validate` ## Request - Base URL: `https://sandbox.nmi.com/api` - URL: `https://sandbox.nmi.com/api/v5/devices/{device_id}/payment-requests/validate` - Auth: API key in header `Authorization` Initiate an asynchronous validation payment request on a specific cloud device. The device_id is specified in the URL path. Payment details (card number, expiration, CVV) are collected by the device itself, so they should not be included in the request body. This endpoint always operates in asynchronous mode. For synchronous payment processing with a device, use POST /api/v5/payments/validate with device_id in the request body. This endpoint uses the same underlying functionality as POST /api/v5/payments/validate. ## Path parameters - `device_id` string, required ## Request body - PaymentDeviceValidateRequest: 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/*`. - `poi_prompt_tip` 'true' | 'false': When set to `"true"`, allows the cardholder to enter or confirm a tip amount on the POI device. - `poi_prompt_quicktip_amounts` string: Comma-delimited quick tip amount options to show on the POI device. Valid only when `poi_prompt_tip` is `"true"`. - `poi_prompt_quicktip_percentages` string: Comma-delimited quick tip percentage options to show on the POI device. Valid only when `poi_prompt_tip` is `"true"`. - `poi_enable_keyed` 'true' | 'false': When set to `"true"`, provides the option for the cardholder to key in card details on the POI device. - `poi_require_keyed` 'true' | 'false': 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` 'cnp' | 'card_present' | 'ecommerce' | 'mail_order' | 'telephone_order': Keyed transaction type to use when keyed entry is enabled or required on the POI device. - `poi_prompt_cvv` 'true' | 'false': Controls whether the POI device prompts for CVV during keyed entry. - `poi_prompt_zip` 'true' | 'false': When set to `"true"`, requires ZIP or postal code entry on the POI device. - `poi_prompt_signature` 'true' | 'false': Controls whether the POI device prompts for signature capture where supported. - `poi_prompt_amount_confirmation` 'true' | 'false': When set to `"true"`, requires the cardholder to confirm the amount on the POI device. - `poi_automatic_fall_forward` 'true' | 'false': Controls fall-forward behavior on supported POI devices. - `poi_enable_void` 'true' | 'false': When set to `"true"`, allows the device flow to void the transaction if the cardholder removes the card before finalization. - `industry` 'retail' | 'restaurant' | 'ecommerce' | 'moto' | 'lodging': Industry type for the transaction - `signature_image` string: Base64 encoded signature image - `billing_address` BillingAddressRest: Billing address for a payment transaction request. - `method` 'initial_recurring' | 'recurring' | 'installment': Recurring or installment classification for the processor. - `initial_recurring`: First transaction in a recurring sequence only. - `recurring`: Later charges in that sequence. - `installment`: Installment transactions; use `number` and `total` on supported processors. Which values apply depends on the processor. - `number` integer: Specify installment billing number, on supported processors. For use when `billing.method` is set to "installment" - `total` number: Specify installment billing total on supported processors. For use when `billing.method` is set to "installment" - `first_name` string: Cardholder's first name - `last_name` string: Cardholder's last name - `company` string: Cardholder's company - `address1` string: Card billing address - `address2` string: Card billing address, line 2 - `city` string: Card billing city - `state` string: Card billing state. Format: `CC` - `zip` string: Card billing zip code - `country` string: Card billing country. Country codes are as shown in ISO 3166-1 alpha-2. Format: `CC` - `phone` string: Billing phone number - `email` string, email: Billing email address - `fax` string: Billing fax number - `cell_phone` string: Billing cell phone number - `website` string: Website (invoice-specific field) - `drivers_license_number` string: Driver's license number - `drivers_license_dob` string: Driver's license date of birth. Format: `YYYY-MM-DD` - `drivers_license_state` string: Driver's license state. Format: `CC` - `payment_details` union: 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. - object: Non-tokenized credit card data. - `card_number` string, required: Credit card number - `card_exp` string, required: Credit card expiration date. Format: `MMYY` - `card_cvv` string: The card security code. - RetailUnencryptedMagneticStripe: Card-present payment using raw magnetic stripe data from a card reader. Set `industry` to `retail` on the payment request. - `track_1` string, required: Raw magnetic stripe data. - `track_2` string, required: Raw magnetic stripe data. - `track_3` string: Raw magnetic stripe data. - RetailMagTekMagensaEncryptedSwipe: Card-present payment using encrypted magnetic stripe data from a MagTek Magensa reader. Set `industry` to `retail` on the payment request. - `magnesafe_track_1` string, required: Raw MagTek Magensa data. - `magnesafe_track_2` string, required: Raw MagTek Magensa data. - `magnesafe_magneprint` string: Raw MagTek Magensa data. - `magnesafe_ksn` string: Raw MagTek Magensa data. - `magnesafe_magneprint_status` string: Raw MagTek Magensa data. - RetailIdTechEncryptedSwipe: Card-present encrypted swipe data from an ID Tech M130 reader. Set `industry` to `retail` on the payment request. - `encrypted_track_1` string, required: Raw encrypted data. - `encrypted_track_2` string, required: Raw encrypted data. - `encrypted_track_3` string: Raw encrypted data. - `encrypted_ksn` string: Raw encrypted data. - RetailIdTechEncryptedKeyed: Card-present encrypted keyed entry data from an ID Tech M130 reader. Set `industry` to `retail` on the payment request. - `encrypted_data` string, required: Raw encrypted data. - RetailIngenicoChip: Card-present EMV chip payment from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request. - `entry_mode` 'emv_icc', required: The type of transaction data to be processed. - `emv_auth_request_data` string, required: EMV data for the transaction as received from the EMV chip card SDK. - `emv_device` 'ingenico_rba', required: The EMV-capable card reader. - `verification_method` 'signature' | 'offline_pin' | 'offline_pin_signature' | 'none', required: Method used to verify the EMV transaction. - `encrypted_ksn` string, required: Raw encrypted data. - `encrypted_track_2` string, required: Raw encrypted data. - RetailIngenicoSwipe: Card-present encrypted swipe from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request. - `entry_mode` 'swiped' | 'swiped_emv_fallback', required: The type of transaction data to be processed. - `emv_device` 'ingenico_rba', required: The EMV-capable card reader. - `encrypted_ksn` string, required: Raw encrypted data. - `encrypted_track_1` string, required: Raw encrypted data. - `encrypted_track_2` string, required: Raw encrypted data. - RetailIngenicoNfc: Card-present NFC payment from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request. - `entry_mode` 'nfc_msd', required: The type of transaction data to be processed. - `emv_device` 'ingenico_rba', required: The EMV-capable card reader. - `encrypted_ksn` string, required: Raw encrypted data. - `encrypted_track_2` string, required: Raw encrypted data. - RetailIngenicoKeyed: Card-present encrypted keyed entry from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request. - `entry_mode` 'keyed', required: The type of transaction data to be processed. - `emv_device` 'ingenico_rba', required: The EMV-capable card reader. - `encrypted_ksn` string, required: Raw encrypted data. - `encrypted_track_2` string, required: Raw encrypted data. - RetailMobileSdkEncryptedPayment: 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. - `encrypted_payment` string, required: Encrypted payment blob returned by the Mobile SDK. - object: Bank account (ACH) details for this transaction. - `check_name` string, required: The name on the customer's ACH account - `check_aba` number, required: The customer's bank routing number - `check_account` number, required: The customer's bank account number - `account_type` 'checking' | 'savings', required: The type of ACH account the customer has - `account_holder_type` 'personal' | 'business', required: The type of ACH account the customer has - `sec_code` 'PPD' | 'WEB' | 'TEL' | 'CCD' | 'POP' | 'RCK', required: The Standard Entry Class code of the ACH transaction - `check_number` string: Check number - object: 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). - `payment_token` string, required: The tokenized version of the customer's card or check information - object: Encrypted payment data from the Apple Pay SDK. - `applepay_payment_data` string, required: The encrypted token created when integration directly to the Apple Pay SDK - object: Encrypted payment data from the Google Pay SDK. - `googlepay_payment_data` string, required: The encrypted token created when integration directly to the Google Pay SDK - object: Merchant-decrypted Apple Pay payment data. - `decrypted_applepay_data` true, required: Set to `true` when submitting merchant-decrypted Apple Pay data. - `card_number` string, required: Credit card number - `card_exp` string, required: Credit card expiration date. Format: `MMYY` - object: Merchant-decrypted Google Pay payment data. - `decrypted_googlepay_data` true, required: Set to `true` when submitting merchant-decrypted Google Pay data. - `card_number` string, required: Credit card number - `card_exp` string, required: Credit card expiration date. Format: `MMYY` - `cardholder_auth` union: 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. - object: EMV 3-D Secure authentication result fields. - `status` 'verified' | 'attempted', required: Set 3D Secure condition. Value used to determine E-commerce indicator (ECI). - `cavv` string, required: Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded. - `xid` string: Cardholder authentication transaction id. Format: base64 encoded. - `three_ds_version` string: 3DSecure version (for example `2.1.0` or `2.2.0`). - `directory_server_id` string: Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - object: Wallet authentication for decrypted Apple Pay or Google Pay payments. - `cavv` string, required: Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field). - `eci` string: Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field). - `merchant_defined_fields` MerchantDefinedFields: Custom fields configured in the merchant control panel under Settings → Merchant Defined Fields (`field_1` through `field_20`). - `field_1` string: Merchant defined field 1 - `field_2` string: Merchant defined field 2 - `field_3` string: Merchant defined field 3 - `field_4` string: Merchant defined field 4 - `field_5` string: Merchant defined field 5 - `field_6` string: Merchant defined field 6 - `field_7` string: Merchant defined field 7 - `field_8` string: Merchant defined field 8 - `field_9` string: Merchant defined field 9 - `field_10` string: Merchant defined field 10 - `field_11` string: Merchant defined field 11 - `field_12` string: Merchant defined field 12 - `field_13` string: Merchant defined field 13 - `field_14` string: Merchant defined field 14 - `field_15` string: Merchant defined field 15 - `field_16` string: Merchant defined field 16 - `field_17` string: Merchant defined field 17 - `field_18` string: Merchant defined field 18 - `field_19` string: Merchant defined field 19 - `field_20` string: Merchant defined field 20 ## Response `200` Payment request created successfully - PaymentRequestStatusResponse: Payment request response. Returned when creating an asynchronous payment request or polling for its status. - `object` 'payment-request', required: Resource type identifier - `id` string, required: Payment request ID - `status` 'pending' | 'inFlight' | 'interactionComplete' | 'cancelled' | 'cancelledAtTerminal' | 'cancelledByApi' | 'cancelledByTimeout' | 'poiDeviceInUse' | 'poiDeviceDisconnected' | 'terminatedBadCardRead', required: Status of the payment request. When a payment request is first created, the status is always `pending`. When polling for status, values are more granular to show the progress of the transaction based on the device's status or customer's interaction. - `transaction` object: Transaction details if the payment request has been processed - `id` integer, nullable: Transaction ID - `type` string: Transaction type (e.g., 'sale', 'auth', 'credit', 'validate') - `success` boolean: Whether the transaction was successful - `condition` string: Transaction condition/status - `approval` string: Approval code - `authorized_amount` string: Authorized amount. Format: `x.xx` - `auth_code` string: Authorization code - `customer_vault_id` string: Customer vault ID associated with the transaction - `emv_metadata` object: EMV (chip card) metadata - `customer_verification_method` string: Customer verification method used - `application_id` string: EMV application ID - `application_label` string: EMV application label - `application_preferred_name` string: EMV application preferred name - `application_pan_sequence_number` string: EMV application PAN sequence number - `transaction_status_information` string: EMV transaction status information - `masked_merchant_number` string: Masked merchant number - `masked_terminal_number` string: Masked terminal number - `card_tokens` object[]: Card tokens associated with the transaction - `token` string: Card token - `type` string: Token type - `error` object: Error information if the payment request failed - `code` string: Error code - `ref_id` string: Error reference ID - `message` string: Error message ## Other responses - `400`: Bad Request - Validation Error - `401`: Unauthorized - `404`: Device not found --- [API](https://skmtc.dev/nmi/apis/payments-api.md) - [All operations](https://skmtc.dev/nmi/apis/payments-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nmi/apis/payments-api/revisions/c03727f27e27?raw)