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

# Create Credit Payment Request on Device

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

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

## Path parameters

- `device_id` string, required

## Request body

- PaymentCreditRequest
  - `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
  - `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`
  - `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).
  - `shipping_address` ShippingAddressRest — Shipping address and information
    - `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 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
  - `customer_vault` CustomerVault — Customer vault information for storing payment methods
    - `add_to_vault` boolean — Add customer to vault
    - `id` string — Customer vault ID
  - `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

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