NMI integration guide

NMI NMI is a gateway that allows you to collect card and eCheck payments. This guide is intended to help you implement NMI based on your preferred integration workflow.

Services and compatibility

Supported payment types
  • Card
  • eCheck
Supported transaction types
  • Sale (saved card token or full card number) ( API )
  • Auth Only (saved card token or full card number) ( API )
  • Capture (partial and greater than) ( API )
  • Void ( API )
  • Refund (partial and multiple) ( API )
Supported processing currenciesAUD, CAD, EUR, GBP, HKD, JPY, MYR, PLN, THB, TWD, USD
3D Secure 1.x supportedYes
3D Secure 2.x supportedYes
External 3D Secure supportedYes
Installments supportedYes
Supported terminalsIngenico Link/2500

Gateway-specific information

  • NMI supports the Address Verification Service (AVS) feature.
  • NMI supports the Security code verification feature.
  • NMI supports terminal transactions: Configuring your terminal for NMI
  • NMI supports adding a surcharge amount to a transaction.
    • This feature is for merchants who want to pass on the cost of credit card acceptance to the customer.
    • This is only supported for transactions with cards issued from the United States.
    • The surcharge can only be used with a sale transaction and not with an auth-only to capture workflow.

Configuration

Work with Integrations Support to add NMI as a connection. You will need the following credentials from NMI:

  • username
  • password
  • processor ID

OR

  • security key
  • processor ID

📘

Note

If you will be using cloud-based terminals with NMI, you must provide the security key and processor ID values.

Required and optional fields

The following table shows the optional fields for NMI transactions in the Create one-time-use token or Run card transaction request.

FieldRequired?Description
data.surchargeNoFor card transactions, NMI supports the addition of a surcharge to the transaction. When doing so, you include a value for this parameter and you update the data.amount to include that surcharge amount as well.
data.descriptor.nameNoFor NMI card transactions, include this parameter to dynamically change the descriptor on the customer's statement. If this parameter is not included, the system uses the default descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.addressNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the street address of the merchant. If this parameter is not included, the system uses the default street address descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.cityNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the city of the merchant. If this parameter is not included, the system uses the default city descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.stateNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the state of the merchant. If this parameter is not included, the system uses the default state descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.postalNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the postal code of the merchant. If this parameter is not included, the system uses the default postal code descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.countryNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the country of the merchant. If this parameter is not included, the system uses the default country descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.phoneNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the phone number of the merchant. If this parameter is not included, the system uses the default phone number descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.urlNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the website URL of the merchant. If this parameter is not included, the system uses the default URL descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.merchantIdNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the NMI ID of the merchant. If this parameter is not included, the system uses the default ID descriptor (as set up on the merchant account that is originating the transactions).
data.descriptor.mccNoFor NMI card transactions only, include this parameter to dynamically change the descriptor on the customer's statement for the merchant category code (MCC). If this parameter is not included, the system uses the default MCC descriptor (as set up on the merchant account that is originating the transactions).

Example requests

The following is an example run card transaction request for NMI.

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "surcharge": 1.50,
    "descriptor": {
    	"name": "Our Company Name",
			"address": "123 Main St.",
			"city": "New York City",
      "state": "NY",
      "postal": "10001",
      "country": "US",
      "phone": "1555555555",
      "url": "https://your-ecommerce-website.example.com",
      "merchantId": "1234",
      "mcc": "5964"
		}
  },
  "paymentMethod": "card",
  "tokenex": {
		"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
  }
}'

The following is an example run echeck transaction request for NMI.

curl -X POST https://api.nexiopaysandbox.com/pay/v3/processECheck \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD"
  },
  "tokenex": {
		"token": "eb50a022-d6de-4244-a1e6-dcb8522b2d19"
  }
}'

Testing data

If you do not have Advanced Testing Triggers enabled on your account, use the following test cards to test your NMI configuration.

BrandCard numberExp dateSecurity codeCardholder name3DSTransaction result
Visa4111111111111111Any future dateAnyAnyN/ASuccess
Mastercard5431111111111111Any future dateAnyAnyN/ASuccess
American Express341111111111111Any future dateAny (ex: 1234)AnyN/ASuccess
Discover6011601160116611Any future dateAnyAnyN/ASuccess

If you do have Advanced Testing Triggers enabled on your account, use the following test cards to test your NMI configuration.

BrandCard numberExp dateSecurity codeCardholder name3DSTransaction result
Visa4111110208009428Any future dateAnyAnyN/ASuccess
Mastercard5412750109056250Any future dateAnyAnyN/ASuccess
American Express375987004003245Any future dateAny (ex: 1234)AnyN/ASuccess
Discover6011000011020538Any future dateAnyAnyN/ASuccess

Testing terminal transactions

NMIs testing workflow uses the same card information for every transaction. Change the amount value in order to create different testing situations:

AmountTransaction result
Any amount greater than or equal to $1.00Success
Any amount less than $1.00Failure

Status workflows

The status of a successful transaction with NMI varies, depending on the options you choose.

SaleWhen isAuthOnly is false, successful sale transactions will have the following statuses:
  • pending* or authorized
  • settled
Auth onlyWhen isAuthOnly is true, successful sale transactions will have the following status:
  • authOnly
CaptureSuccessful capture transactions will have the following statuses:
  • pending* or authorized
  • settled
VoidSuccessful void transactions will have the following status:
  • voided
RefundSuccessful refund transactions will have the following statuses:
  • pending* or authorized
  • settled

*Pending status displays as "authorized" or "AUTHORIZED" in the Nexio Dashboard; it displays as 10, meaning "authorized", in the response when querying transactions (for more information about transactionStatus, see the appropriate transactionStatus table).

If you have any additional questions or feedback, contact us.