Device REST API: asynchronous payments
Create sale, authorization, credit, and validation requests on a device; inspect their outcome and cancel unfinished requests.
Environment and authentication
Base URL for every operation on this page: https://sandbox.nmi.com/api/v5. Send the private key directly as the Authorization header value, without a Bearer prefix. JSON requests use Content-Type: application/json. Keep credentials on your backend and select the merchant and device through your own authorized session. These paths are v5; do not substitute v2 camelCase fields or Classic security_key request bodies. Authorization: YOUR_SANDBOX_PRIVATE_KEY Content-Type: application/json Examples here describe sandbox request shapes only. They do not create a device, prompt a customer, or move money.
Choose the operation
All four device payment-requests endpoints are asynchronous. device_id is a required string in the URL. Card details are collected on the device: omit payment_details, card number, expiration and CVV. Do not repeat device_id in the body. Method and path Operation Minimum body POST /devices/{device_id}/payment-requests/sale Sale amount: number, x.xx POST /devices/{device_id}/payment-requests/auth Authorization amount: number, x.xx POST /devices/{device_id}/payment-requests/credit Credit to a card collected on the device amount: number, x.xx POST /devices/{device_id}/payment-requests/validate Validate payment details No amount field exposed in the reviewed schema For the synchronous route, NMI directs integrations to /api/v5/payments/{operation} with device_id in the body. POI prompt fields belong on these asynchronous device request routes, not /v5/payments/*. Credit is not a linked refund reference.
Sale, auth and credit amount fields
These three operations share the exposed request fields below. All are optional except amount. Parameter Type / requirement Meaning or constraint amount number; required Total, x.xx. surcharge / convenience_fee / misc_fee number ≥0 Respective fee amounts, x.xx; program eligibility still applies. misc_fee_name string ≤50 Default Miscellaneous Fee. tip number ≥0 Final tip included in payment. currency 3-character string ISO 4217 code. processor_id string ≤50 Routing override; omit to use default. dup_seconds integer 0–7862400 Duplicate-check window on supported processors; 0 disables it. transaction_session_id 32-character string Single-use Kount correlation identifier.
Additional sale, auth and credit controls
These are optional properties in the shared request. Parameter Type / requirement Meaning or constraint customer_receipt boolean Send customer receipt when charged. pinless_debit_override boolean Opt out of configured Pinless Debit Conversion. network_tokenize boolean Enable network tokenization. industry string enum retail, restaurant, ecommerce, moto, lodging. signature_image string Base64 signature image. partial_payments string enum settle_partial or payment_in_full. partial_payment_id string ≤50 Identifier for a subsequent partial payment. billing_address / shipping_address / order_details objects Billing, shipping and order data. payment_facilitator / payment_descriptor objects Submerchant and statement descriptor data. cardholder_auth / merchant_defined_fields / cit_mit structured objects Authentication, merchant custom fields, credential-on-file data. The detailed local contracts below contain the nested billing, shipping, order, facilitator, descriptor, authentication and credential-on-file schemas. Use the contract for the chosen operation rather than copying a similarly named Classic object.
POI collection controls
Flags in this table are string enums "true" or "false", not JSON booleans. The validation route also exposes these controls. Parameter Type / requirement Meaning or constraint poi_prompt_tip string flag Prompt for or confirm tip. poi_prompt_quicktip_amounts string Comma-separated amounts; requires poi_prompt_tip="true". poi_prompt_quicktip_percentages string Comma-separated percentages; requires poi_prompt_tip="true". poi_enable_keyed string flag Offer keyed card entry. poi_require_keyed string flag Require keyed entry; cannot also enable poi_enable_keyed. poi_keyed_type enum cnp, card_present, ecommerce, mail_order, telephone_order. poi_prompt_cvv / poi_prompt_zip string flags Prompt CVV / require postal code. poi_prompt_signature string flag Capture signature where supported. poi_prompt_amount_confirmation string flag Ask customer to confirm amount. poi_automatic_fall_forward string flag Supported device fall-forward behavior. poi_enable_void string flag Allow void if card removed before finalization.
Validation request scope
POST /devices/{device_id}/payment-requests/validate exposes the POI fields above plus industry, signature_image, billing_address and merchant_defined_fields. It does not expose the sale/auth/credit monetary body fields. Do not construct validation by copying an entire sale payload.
Minimal sale request
The response creates a pending request. HTTP 200 does not prove approval. These create endpoints also document 400 validation errors, 401 unauthorized and 404 device not found. POST /api/v5/devices/YOUR_DEVICE_ID/payment-requests/sale HTTP/1.1 Host: sandbox.nmi.com Authorization: YOUR_SANDBOX_PRIVATE_KEY Content-Type: application/json { "amount": 12.00, "currency": "USD", "poi_prompt_amount_confirmation": "true" }
Read outcome — GET /devices/{device_id}/payment-requests/{request_id}
Both path identifiers are required strings. request_id comes from the create response, and device_id must match the originating device. HTTP 200 can mean ongoing interaction, approval, decline, error, another request already active, customer cancellation, or API cancellation. Other documented responses are 400, 401, 404 and 500. Do not map every HTTP 200 to an order marked paid.
Cancel — DELETE /devices/{device_id}/payment-requests
The required device_id identifies the device with an in-flight request; there is no request_id segment on this DELETE path. Cancellation applies before authorization finishes. HTTP 200 means the cancellation request was processed; 401, 404 and 500 are documented errors. Poll the original request to resolve the outcome; an API cancellation may appear as cancelledByApi. If the transaction has already completed and cannot be cancelled, NMI directs a subsequent void when applicable.
Preserve payment and interaction state separately
PaymentRequestStatusResponse requires object="payment-request", id and status. Initial status is pending. Subsequent statuses are inFlight, interactionComplete, cancelled, cancelledAtTerminal, cancelledByApi, cancelledByTimeout, poiDeviceInUse, poiDeviceDisconnected and terminatedBadCardRead. On interactionComplete, inspect transaction.success and transaction.condition or the error object; completion alone is not approval. transaction may include its integer id, type, approval, authorized_amount, auth_code, customer_vault_id, emv_metadata and card_tokens. error contains code, ref_id and message. Recommended application behavior: preserve the request id and reconcile uncertainty instead of submitting a replacement sale. Register and inspect devices Separate device prompts
Detailed local operation contracts
Expand the corresponding local contract for full request and response structures, including nested fields. These contracts preserve the v5 operation boundary. create device payment request sale v5 create device payment request auth v5 create device payment request credit v5 create device payment request validate v5 get device payment request status v5 cancel device payment request v5