---
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`

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

- PaymentValidateRequest
  - `payment_details` union, required — Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, Apple Pay encrypted payload, or Google Pay encrypted payload. 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.
    - 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 or Collect.js (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 — Merchant-decrypted Apple Pay flag.
      - `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 — Merchant-decrypted Google Pay flag.
      - `card_number` string, required — Credit card number
      - `card_exp` string, required — Credit card expiration date. Format: `MMYY`
  - `industry` 'retail' | 'restaurant' | 'ecommerce' | 'moto' | 'lodging' — Industry type for the transaction
  - `signature_image` string — Base64 encoded signature image
  - `billing_address` BillingAddressRest — Billing address and information
    - `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**, Apple Pay encrypted payload, or Google Pay encrypted payload. 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.
      - 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 or Collect.js (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 — Merchant-decrypted Apple Pay flag.
        - `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 — Merchant-decrypted Google Pay flag.
        - `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 that can be set up in merchant control panel under Settings->Merchant Defined Fields
    - `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 status response matching the structure returned by GET /api/v5/devices/{deviceId}/payment-requests/{request_id}
  - `object` 'payment-request', required — Resource type identifier
  - `id` string, required — Payment request ID
  - `status` 'pending' | 'completed' | 'error', required — Status of the payment request
  - `transaction` object, required — 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.net/nmi/apis/embedded-components-api.md) · [All operations](https://skmtc.net/nmi/apis/embedded-components-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nmi/embedded-components-api/versions/45c2ecda3685/schema)