API Reference
Explore SandboxPartner PortalMerchant Portal

Transaction Processing

post
https://sandbox.nmi.com/api/transact.php

Never Use Real API Keys

Never use real API Keys when testing. The gateway allows Partners to create Test Merchant Accounts. Testing should always use keys from the Test Accounts and never keys from a Standard Account.

Methodology

Steps:

  1. The customer sends their payment information to the merchant's web site.
  2. The merchant web site posts the payment data to the Payment Gateway.
  3. The Payment Gateway responds immediately with the results of the transactions.
  4. The merchant web site displays the appropriate message to the customer.

The communication method used to send messages to the Payment Gateway's server is the standard HTTP protocol over an SSL connection.

In the Payment API method, the communications with the cardholder (Steps 1 and 4) are developed completely by the merchant and therefore are not defined by the Payment Gateway. Step 1 should simply collect the payment data from the cardholder and Step 4 should display the appropriate transaction receipt or declined message.

In Step 2, transaction details should be delivered to the Payment Gateway using the POST method with the appropriate variables defined below posted along with the request.

In Step 3, the transaction responses are returned in the body of the HTTP response in a query string name/value format delimited by ampersands. For example: variable1=value1&variable2=value2&variable3=value3

Customer Vault

The Customer Vault was designed specifically for businesses of any size to address concerns about handling customer payment information. Visa and MasterCard have instituted the Payment Card Industry (PCI) Data Security to protect cardholder data, wherever it resides, ensuring that members, merchants, and service providers maintain the highest information security standards.

These associations have also deemed that merchants will be held liable for any breach of cardholder data. This has become a major concern for merchants who handle credit card or electronic check payments. The Customer Vault is designed for these merchants who desire to avoid the tremendous costs and resources involved in becoming PCI compliant under these circumstances.

The Customer Vault does this by allowing merchants to transmit their payment information through a Secure Sockets Layer (SSL) connection for storage in our Level 1 PCI certified data facility. Once the customer record has been securely transmitted to the Customer Vault, the merchant can then initiate transactions remotely without having to access cardholder information directly. This process is accomplished without the merchant storing the customer's payment information in their local database or payment application.

Response Code Table
CodeDescription
100Transaction was approved.
200Transaction was declined by processor.
201Do not honor.
202Insufficient funds.
203Over limit.
204Transaction not allowed.
220Incorrect payment information.
221No such card issuer.
222No card number on file with issuer.
223Expired card.
224Invalid expiration date.
225Invalid card security code.
226Invalid PIN.
240Call issuer for further information.
250Pick up card.
251Lost card.
252Stolen card.
253Fraudulent card.
260Declined with further instructions available. (See response text)
261Declined-Stop all recurring payments.
262Declined-Stop this recurring program.
263Declined-Update cardholder data available.
264Declined-Retry in a few days.
300Transaction was rejected by gateway.
400Transaction error returned by processor.
410Invalid merchant configuration.
411Merchant account is inactive.
420Communication error.
421Communication error with issuer.
430Duplicate transaction at processor.
440Processor format error.
441Invalid transaction information.
460Processor feature not available.
461Unsupported card type.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Form Data
string
required

API Security Key assigned to a merchant account. New keys can be generated from the merchant control panel in Settings > Security Keys

string
required

The type of transaction to be processed. Must be sale

string
enum

settle_partial: Settles any amount of tender collected (captured partial auth's and approved partial sales) at cut off.

payment_in_full: Required that any split tendered transaction is collected in-full before settlement gets initiated.

Allowed:
string

Unique identifier returned when making the original transaction. This should only be used for secondary transactions.

string
enum
required

Credit card number.

Allowed Card Numbers:
Card TypeTest Card Number
Visa4111111111111111
MasterCard5431111111111111
Discover6011000991300009
American Express341111111111111
Diner's Club30205252489926
JCB3541963594572595
Maestro6799990100000000019
Allowed:
string
required

Credit card expiration date.

Format: MMYY

string

The card security code. While this is not required, it is strongly recommended.

string
required

Total amount to be charged.

Format: x.xx

string

The tokenized version of the customer's card or check information. This will be generated by Collect.js and is usable only once.

string
length between 32 and 32

A single use session ID used by Kount to link the transaction and Data Collector information together.

  • Should be generated every time a payment form is loaded by the cardholder.
  • Should be random/unpredictable (do not use sequential IDs).
  • Should not be reused within a 30 day period.

This can be used with Collect.js or the Payment API when using the Kount DDC with Gateway.js.

Format: alphanumeric

string

The encrypted token created when integration directly to the Google Pay SDK.

string

Surcharge amount.

Format: x.xx

string

Convenience fee amount.

Format: x.xx

string

Miscellaneous fee amount.

Format: x.xx

string

Custom miscellaneous fee name.

Default: Miscellaneous Fee

number

The final tip amount, included in the transaction, associated with the purchase.

Format: x.xx

string

The transaction currency.

Format: ISO 4217

string

If using Multiple MIDs, route to this processor (processor_id is obtained under Settings → Transaction Routing in the Control Panel).

integer
≤ 7862400

Sets the time in seconds for duplicate transaction checking on supported processors. Set to 0 to disable duplicate checking.

string

Set payment descriptor on supported processors.

string

Set payment descriptor phone on supported processors.

string

Set payment descriptor address on supported processors.

string

Set payment descriptor city on supported processors.

string

Set payment descriptor state on supported processors.

string

Set payment descriptor postal code on supported processors.

string

Set payment descriptor country on supported processors.

string

Set payment descriptor mcc on supported processors.

string

Set payment descriptor merchant id on supported processors.

string

Set payment descriptor url on supported processors.

string
enum

Can be set to 'recurring' to mark payment as a recurring transaction or 'installment' to mark payment as an installment transaction.

Allowed:
integer
0 to 99

Specify installment billing number, on supported processors. For use when billing_method is set to "installment".

string

Specify installment billing total on supported processors. For use when billing_method is set to "installment".

string

Order template ID.

string

Order description.

string

Level III - Order Field: Identifier assigned by the merchant. This defaults to gateway transaction id.

string

IP address of cardholder, this field is recommended.

Format: xxx.xxx.xxx.xxx

string

Cardholder's first name.

string

Cardholder's last name

string

Cardholder's company

string

Card billing address

string

Card billing address, line 2

string

Card billing city

string

Card billing state.

Format: CC

string

Card billing zip code

string

Card billing country. Country codes are as shown in ISO 3166-1 alpha-2.

Format: CC

string

Billing phone number

string

Billing fax number

string

Billing email address

string

Driver's license number.

string

Driver's license date of birth.

string

The state that issued the customer's driver's license.

string

Shipping first name

string

Shipping last name

string

Shipping company

string

Shipping address

string

Shipping address, line 2

string

Shipping city

string

Shipping state.

Format: CC

string

Shipping zip code

string

Level III - Order Field: Shipping country (e.g. US).

Format: CC - ISO 3166-1 alpha-2

string

Shipping email address

string

Merchant defined field. You can pass custom information in up to 20 fields.

Format: merchant_defined_field_1=Value1, merchant_defined_field_2=Value2, etc...

string
enum

If set to true, when the customer is charged, they will be sent a transaction receipt.

Allowed:
string
enum

Set 3D Secure condition. Value used to determine E-commerce indicator (ECI).

Required for 3D Secure transactions

Allowed:
string

Cardholder authentication verification value.

Format: base64 encoded Required for 3D Secure transactions

string

Cardholder authentication transaction id.

Format: base64 encoded Required for 3D Secure transactions

string
enum

3DSecure version. Required for 3D Secure transactions

Allowed:
string

Directory Server Transaction ID. May be provided as part of 3DSecure 2.0 authentication.

Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

string

Specifies a payment gateway transaction id in order to associate payment information with a Subscription or Customer Vault record. Must be set with a 'recurring' or 'customer_vault' action.

string

Set to 'Y' if you have Pinless Debit Conversion enabled but want to opt out for this transaction. Feature applies to selected processors only.

string
enum

Recurring Field: Recurring action to be processed.

Allowed:
string

Recurring Field: Create a subscription tied to a Plan ID if the sale/auth transaction is successful.

Required when recurring variable is set to add_subscription

integer

Recurring Field: The number of payments before the recurring plan is complete.

Note: Use '0' for until canceled

Required when recurring variable is set to add_subscription

number

Recurring Field: The plan amount to be charged each billing cycle.

Format: x.xx

Required when recurring variable is set to add_subscription

integer
1 to 24

Recurring Field: How often, in months, to charge the customer. Cannot be set with 'day_frequency'. Must be set with 'day_of_month'.

Required when recurring variable is set to add_subscription

integer
1 to 31

Recurring Field: The day that the customer will be charged. Cannot be set with 'day_frequency'. Must be set with 'month_frequency'. For months without 29, 30, or 31 days, the charge will be on the last day

Required when recurring variable is set to add_subscription

integer

Recurring Field: How often, in days, to charge the customer. Cannot be set with 'month_frequency' or 'day_of_month'.

Required when recurring variable is set to add_subscription

date

Recurring Field: The first day that the customer will be charged.

Format: YYYYMMDD

Required when recurring variable is set to add_subscription

string
enum

Associate payment information with a Customer Vault record if the transaction is successful.

Allowed:
string

Specifies a Customer Vault id. If not set, the payment gateway will randomly generate a Customer Vault id.

string
enum

Stored Credentials (CIT/MIT): Who initiated the transaction.

Allowed:
string

Stored Credentials (CIT/MIT): Original payment gateway transaction id.

string
enum

Stored Credentials (CIT/MIT): The indicator of the stored credential.

Use 'stored' when processing the initial transaction in which you are storing a customer's payment details (customer credentials) in the Customer Vault or other third-party payment storage system.

Use 'used' when processing a subsequent or follow-up transaction using the customer payment details (customer credentials) you have already stored to the Customer Vault or third-party payment storage method.

Allowed:
number

Level II/III - Order Field: Freight or shipping amount included in the transaction amount. Default - 0.00.

Format: x.xx

number

Level II/III - Order Field: The sales tax, included in the transaction amount, associated with the purchase. Setting tax equal to '-1' indicates an order that is exempt from sales tax. Default - 0.00.

Format: x.xx

string

Level II/III - Order Field: Purchase order number

string

Level III - Order Field: Postal/ZIP code of the address where purchased goods will be delivered. This field can be identical to the 'ship_from_postal' if the customer is present and takes immediate possession of the goods.

string

Level III - Order Field: Postal/ZIP code of the address from where purchased goods are being shipped, defaults to merchant profile postal code.

string

Level III - Order Field: 4 character international description code of the overall goods or services being supplied. The acquirer or processor will provide a list of current codes.

number

Level III - Order Field: Amount included in the transaction amount associated with the import of purchased goods. Default - 0.00.

Format: x.xx

number

Level III - Order Field: Amount included in the transaction amount of any discount applied to complete order by the merchant. Default - 0.00.

Format: x.xx

number

Level III - Order Field: The national tax amount included in the transaction amount. Default - 0.00.

Format: x.xx

number

Level III - Order Field: Second tax amount included in the transaction amount in countries where more than one type of tax can be applied to the purchases. Default - 0.00.

Format: x.xx

string

Level III - Order Field: Tax identification number of the merchant that reported the alternate tax amount.

number

Level III - Order Field: Contains the amount of any value added taxes which can be associated with the purchased item. Default - 0.00.

Format: x.xx

number

Level III - Order Field: Contains the tax rate used to calculate the sales tax amount appearing. Can contain up to 2 decimal places, e.g. 1% = 1.00. Default - 0.00.

Format: x.xx

string

Level III - Order Field: Invoice number that is associated with the VAT invoice.

string

Level III - Order Field: Value added tax registration number supplied by the cardholder.

string

Level III - Order Field: Government assigned tax identification number of the merchant for whom the goods or services were purchased from.

date

Level III - Order Field: Purchase order date, defaults to the date of the transaction.

Format: YYMMDD

string

Level III - Line Item: Merchant defined description code of the item being purchased.

Up to 99 sets of item_ fields are allowed.*

string

Level III - Line Item: Description of the item(s) being supplied.

string

Level III - Line Item: International description code of the individual good or service being supplied. The acquirer or processor will provide a list of current codes.

string

Level III - Line Item: Code for units of measurement as used in international trade. Default - EACH.

number

Level III - Line Item: Unit cost of item purchased, may contain up to 4 decimal places.

integer

Level III - Line Item: Quantity of the item(s) being purchased. Default - 1.

number

Level III - Line Item: Purchase amount associated with the item. Defaults to: 'item_unit_cost_#' x 'item_quantity_#' rounded to the nearest penny.

number

Level III - Line Item: Amount of sales tax on specific item. Amount should not be included in 'total_amount_#'. Default - 0.00.

Format: x.xx

number

Level III - Line Item: Percentage representing the value-added tax applied. Default - 0.00.

Format: x.xx

number

Level III - Line Item: Discount amount which can have been applied by the merchant on the sale of the specific item. Amount should not be included in 'total_amount_#'.

number

Level III - Line Item: Discount rate for the line item. Default - 0.00.

Format: x.xx

string

Level III - Line Item: Type of value-added taxes that are being used.

string

Level III - Line Item: Tax identification number of the merchant that reported the alternate tax amount.

string

Payment Facilitator: Payment Facilitator/Aggregator/ISO's ID Number

string

Payment Facilitator: Sub-merchant Account ID

string

Payment Facilitator: Sub-merchant's Name

string

Payment Facilitator: Sub-merchant's Address

string

Payment Facilitator: Sub-merchant's City

string

Payment Facilitator: Sub-merchant's State

string

Payment Facilitator: Sub-merchant's Zip/Postal Code

string

Payment Facilitator: Sub-merchant's Country

string

Payment Facilitator: Sub-merchant's Phone Number

string

Payment Facilitator: Sub-merchant's Email Address

string
enum

The industry parameter is supported across multiple transaction types. Its purpose is to identify the merchant industry type for processing

Allowed:
string

Cardholder signature image.

Format: base64 encoded raw PNG image. (16kiB maximum)

string
enum

Overrides the Customer Token Vault settings and tokenizes the transaction if eligible. Default - 0.

Allowed:
Response

Updated 3 months ago

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/x-www-form-urlencoded

Updated 3 months ago