---
title: "Create Sale Payment Request on Device"
method: POST
path: "/v5/devices/{device_id}/payment-requests/sale"
tags: ["Devices"]
---

# Create Sale Payment Request on Device

`POST /v5/devices/{device_id}/payment-requests/sale`

## Request

- Base URL: `https://sandbox.nmi.com/api`
- URL: `https://sandbox.nmi.com/api/v5/devices/{device_id}/payment-requests/sale`
- Auth: API key in header `Authorization`

Initiate an asynchronous sale 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/sale with device_id in the request body. This endpoint uses the same underlying functionality as POST /api/v5/payments/sale.

## Path parameters

- `device_id` string, required

## Request body

- DevicePaymentRequest: 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/*`.
  - `amount` number, required: Total amount to be charged. Format: `x.xx`
  - `surcharge` number: Surcharge amount. Format: `x.xx`
  - `convenience_fee` number: Convenience fee amount. Format: `x.xx`
  - `misc_fee` number: Miscellaneous fee amount. Format: `x.xx`
  - `misc_fee_name` string: Custom miscellaneous fee name. Default: `Miscellaneous Fee`
  - `tip` number: The final tip amount, included in the payment. Format: `x.xx`
  - `currency` string: The ISO 4217 currency code. Example: `USD`
  - `processor_id` string: If using multiple processors, route to the specified processor ID. Omit for default processor or when using a single processor.
  - `dup_seconds` integer: Sets the time in seconds for duplicate checking on supported processors. Set to 0 to disable duplicate checking
  - `transaction_session_id` string: A single use session ID used by Kount to link the payment and Data Collector information together
  - `customer_receipt` boolean: If set to true, when the customer is charged, they will be sent a receipt
  - `pinless_debit_override` boolean: Set to true if you have Pinless Debit Conversion enabled but want to opt out for this payment
  - `industry` 'retail' | 'restaurant' | 'ecommerce' | 'moto' | 'lodging': Industry type for the payment
  - `signature_image` string: Base64 encoded signature image
  - `network_tokenize` boolean: Enable network tokenization
  - `partial_payments` 'settle_partial' | 'payment_in_full': `settle_partial`: Settles any amount of tender collected at cut off. `payment_in_full`: Required that any split tendered payment is collected in-full before settlement gets initiated
  - `partial_payment_id` string: A numeric identifier which is used when submitting subsequent payments for partial payments
  - `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).
  - `shipping_address` ShippingAddressRest: Shipping address and information
    - `id` string: Shipping address ID (max 32 characters). Generated if omitted on create.
    - `first_name` string: Shipping first name
    - `last_name` string: Shipping last name
    - `company` string: Shipping company
    - `address1` string: Shipping address
    - `address2` string: Shipping address, line 2
    - `city` string: Shipping city
    - `state` string: Shipping state.
    - `zip` string: Shipping zip code
    - `country` string: ISO 3166-1 alpha-2 country code. Example: `US`
    - `email` string, email: Shipping email address
    - `carrier` 'ups' | 'fedex' | 'dhl' | 'usps': Shipping carrier
  - `order_details` OrderDetailsRest: Order details and line items
    - `template_id` string: Order template ID
    - `description` string: Order description
    - `id` string: Order ID (for payment requests)
    - `order_id` string: Order ID (for invoice requests and responses)
    - `customer_id` string: Customer ID (invoice-specific)
    - `customer_tax_id` string: Customer tax ID (invoice-specific)
    - `tax` number: Tax amount
    - `shipping` number: Shipping amount
    - `po_number` string: Purchase order number (maxLength 50 for payments, 255 for invoices)
    - `shipping_postal_code` string: Shipping postal code
    - `ship_from_postal_code` string: Ship from postal code
    - `summary_commodity_code` string: Summary commodity code
    - `duty_amount` number: Duty amount
    - `discount_amount` number: Discount amount
    - `national_tax_amount` number: National tax amount
    - `alternate_tax_amount` number: Alternate tax amount
    - `alternate_tax_id` string: Alternate tax ID
    - `vat_tax_amount` number: VAT tax amount
    - `vat_tax_rate` number: VAT tax rate
    - `vat_invoice_reference_number` string: VAT invoice reference number
    - `customer_vat_registration` string: Customer VAT registration
    - `merchant_vat_registration` string: Merchant VAT registration
    - `order_date` string, date: Order date
    - `order_description` string: Order description (maxLength 255 for both payments and invoices)
    - `ip_address` string: IP address of cardholder (IPv4 or IPv6). Format validated as IP address
    - `line_items` LineItem[]
      - `product_code` string: Product code
      - `description` string: Line item description
      - `commodity_code` string: Commodity code
      - `unit_of_measure` string: Unit of measure
      - `unit_cost` number: Unit cost
      - `quantity` integer: Quantity
      - `total_amount` number: Total amount
      - `tax_amount` number: Tax amount
      - `tax_rate` number: Tax rate
      - `discount_amount` number: Discount amount
      - `discount_rate` number: Discount rate
      - `tax_type` string: Tax type
      - `alternate_tax_id` string: Alternate tax ID
  - `payment_facilitator` PaymentFacilitator: Payment facilitator information for submerchant transactions
    - `id` string: Payment facilitator ID
    - `submerchant_id` string: Submerchant ID
    - `submerchant_name` string: Submerchant name
    - `submerchant_address` string: Submerchant address
    - `submerchant_city` string: Submerchant city
    - `submerchant_state` string: Submerchant state
    - `submerchant_postal` string: Submerchant postal code
    - `submerchant_country` string: Submerchant country
    - `submerchant_phone` string: Submerchant phone
    - `submerchant_email` string, email: Submerchant email
  - `payment_descriptor` PaymentDescriptor: Payment descriptor information for transaction statements
    - `descriptor` string: Payment descriptor
    - `phone` string: Payment descriptor phone
    - `address` string: Payment descriptor address
    - `city` string: Payment descriptor city
    - `state` string: Payment descriptor state
    - `postal_code` string: Payment descriptor postal code
    - `country` string: Payment descriptor country
    - `mcc` string: Merchant category code
    - `merchant_id` string: Merchant ID
    - `url` string, uri: Merchant URL (must be HTTPS)
  - `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
  - `cit_mit` CitMit: Credential on File information
    - `initiated_by` 'customer' | 'merchant': Whether the transaction was initiated by the customer or merchant
    - `initial_transaction_id` string: Initial payment ID from the stored credentials payment request. Used on subsequent follow up payments.
    - `stored_credential_indicator` 'stored' | 'used': Stored credential indicator
  - `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.

## 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)