Supported Functionality

[x] Authorize Payments
[x] Refund Payments
[ ] Accepts $0 Transactions
[ ] ACH Support
[ ] Digital Wallet Support
[x] Capture Payments
[x] 3DS Support
[x] Card Tokenization
[ ] CVV Required
[x] Dynamic Merchant Descriptors (API only)

Adding an NMI Merchant

To connect a Merchant using NMI Gateway,

First add Merchant
Select NMI as the Gateway
Add Gateway Details as outlined below

Gateway Details	Description
API User Name*	API Username - provided by NMI
API Password*	API Password - Provided by NMI
Attempt 3D Secure	NMI's 3-step redirect for initial transactions
Processor ID	Setting the Processor ID is an advanced feature that may be required if you have multiple processors setup in your NMI account.
Customer Vault Enabled**	If checked, Vrio will follow Vault Parameters for NMI. This includes passing the following parameters: initiated_by initial_transaction_id stored_credential_indicator Customer Vault must be enabled within NMI, check this box. For recurring payments, transactions will flow in this order: Vault (if applicable) -> Gateway transaction ID -> Full Card
Bypass $0 transaction authorizations	The NMI gateway will decline $0 sales. Vrio will run a $1 authorization (and void it immediately) for $0 sale transactions, the authorization request will determine if the sale is successful. When Checked - Vrio will bypass any $0 transaction, no attempt will be made at the gateway, and treat all $0 transactions as successful.
Pass Merchant Descriptor**	When checked, the merchant descriptor setup within the Merchant Account will post to NMI with the charge details. NMI supports Dynamic Descriptors. The merchant descriptor can be passed as a dynamic API variable for supported gateways. The API method impacted is /orders The goal of this feature is to simplify merchant descriptor updates without needing to reconfigure the merchant gateway. The dynamic descriptor will appear on the credit card statement of the customer.
Pass Additional Merchant Data**	When Checked - this Merchant will pass the merchant details from the Merchant Account setup with the transaction payload.
Pass Stored Credentials (CIT/MIT) Data and Billing Method**	When Checked - this Merchant will pass Stored Credentials (CIT/MIT) and Billing Method to NMI.

initiated_by ( customer for cycle 1, merchant for cycle 2+ )
initial_transaction_id ( passing first successful transactionid for order/merchant )
stored_credential_indicator (stored for cycle 1, used for cycle 2+)
billing_method (recurring when charge is recurring only)


Merchant Payment Methods*	The types of payment methods this merchant accepts - Credit card, check, ach, etc.
Merchant Card Types*	Card types to be accepted on this Merchant
Merchant Default Currency*	Default currency that will be used, if currency is not specified
Merchant Currencies*	All currencies accepted on this merchant

*Required

**Additional Data values available be passed with the transaction payload - when checked.

Why would I pass additional data?

Depending on the banks and type of program you are running, passing additional data with the initial and/or subsequent renewal transactions can increase approval rates.

Request

Required Data Mapping

Below is a table that will show how Vrio maps its data to the requested payment gateway API. Values in bold are hard coded values, the rest are dynamic based on the payment.

DataAction=Auth/Sale

NMI Gateway	VRIO
currency	transactions.currency_value
amount	transactions.transaction_total
orderid	transactions.transaction_id
firstname	customers_address.billing_fname
lastname	customers_address.billing_lname
company	customers_address.billing_organization
email	customers.email
phone	customers_address.billing_telephone
address1	customers_address.billing_address1
address2	customers_address.billing_address2
city	customers_address.billing_city
state	customers_address.billing_state
zip	customers_address.billing_zipcode
country	customers_address.billing_country
ipaddress	orders.ipaddress
shipping_firstname	customers_address.shipping_fname
shipping_lastname	customers_address.shipping_lname
shipping_email	customers_address.shipping_email
shipping_company	customers_address.shipping_organization
shipping_address1	customers_address.shipping_address1
shipping_address2	customers_address.shipping_address2
shipping_city	customers_address.shipping_city
shipping_state	customers_address.shipping_state
shipping_zip	customers_address.shipping_zipcode
shipping_country	customers_address.shipping_country

Optional Data Mapping

3DS Variables

3DS Values will always be passed if exist on the order for the current cycle.

Three Step Redirect for Initial Transactions through NMI.

When checked, API Key is required
For recurring charges, no 3DS parameters are passed

Pay Attention
If using a Paay.co or Payon for 3DS, do not check the "Attempt 3D Secure" on the merchant. Learn more about third-party 3DS integrations here.

NMI Gateway	VRIO
cardholder_auth	orders_3ds.cardholder_auth
eci	orders_3ds.eci
cavv	orders_3ds.cavv
xid	orders_3ds.xid
three_ds_version	orders_3ds.three_ds_version
directory_server_id	orders_3ds.directory_server_id

Credit Card Data Recurring Variables

NMI Gateway	VRIO
customer_vault_id	Will pass the customer_vault_id if Customer Vault Enabled is checked and we have a token from the initial charge
transactionid	If we above is false, and we do not have any credit card information, we will pass the gateway_response_id from the initial charge for the merchant/card/order
ccnumber	customers_card.card_number
cvv	customers_card.card_cvv ( if exists, else will pass null )
ccexp	customers_card.card_exp_month customers_card.card_exp_year

Pass Merchant Descriptor

If Pass Merchant Descriptor is Checked

NMI Gateway	Vrio
descriptor	If in the API call there is a transaction_descriptor passed, we will send that, if not, we will send the Merchant Descriptor (merchant_descriptor)

Pass Additional Merchant Data

If Pass Additional Merchant Data is Checked, all of the following values will be passed with the transaction payload to NMI.

NMI Gateway	Vrio
descriptor_merchant_id	Merchant Identification Number (merchant_mid_id)
descriptor_address	Merchant Address (merchant_address)
descriptor_city	Merchant City (merchant_city)
descriptor_state	Merchant State (merchant_state)
descriptor_postal	Merchant Postal Code (merchant_postal_code)
descriptor_country	Merchant Country (merchant_country)
descriptor_mcc	MCC Code (merchant_mcc_code)
descriptor_url	Merchant URL (merchant_url)
descriptor_phone	Merchant Phone Number (merchant_phone)

Pass Stored Credentials (CIT/MIT)

Pass Stored Credentials (CIT/MIT) Data and Billing Method OR Customer Vault is Checked

Prerequisite
Customer Vault enabled must be checked.

NMI Gateway	Vrio
initial_transaction_id	The initial Gateway Response ID (gateway_response_id) for the card/merchant/order
initiated_by	customer if an initial charge (cycle 1) merchant if a renewal charge (cycle 2+)
stored_credential_indicator	stored if an initial charge (cycle 1) used if a renewal charge (cycle 2+)
billing_method	recurring only if there is a recurring order offer on the charge

Response Data Mapping

Below is a table that will show how Vrio maps its data in the API response

NMI Gateway	VRIO
response_code	100 = Success
transactionid	gateway_response_id
orderid	gateway_response_gateway_id
response_code	gateway_response_code
authcode	gateway_auth_code
cvvresponse	gateway_response_cvv
avsresponse	gateway_response_avs
responsetext	processor_response_text
customer_vault_id	customer_card_merchant_token

Testing Capabilities and Results

What we can / cannot test for based on the gateway’s sandbox and test card capabilities.

Testing Tips
When testing Gateways, ensure to use the NMI Test Cards to test through to the Gateway.
Vrio recommends placing multiple test scenarios, confirming in the Vrio Gateway API Log what data is passed.
Then confirm within the NMI Portal.
Follow full transaction testing and validation steps here.

Testing Capability	Available
Auth	Y
Capture	Y
Auth & Capture	Y
One Time Sales	Y
Recurring Sale	Y
$0 Transaction	N ( if Bypass $0 transaction authorizations, we will always return this response Successful zero $type, gateway was bypassed.), if its not, we will attempt a $1 auth and return the response from that
Decline	Y
Voids	Y
Refunds	Y
3DS	Y

Note: Placing test orders with a NMI sandbox account or using NMI test cards will not automatically set the order as a test in Vrio. Be sure to flag the order as a test using the is_test flag after the order is processed. For more details on placing test orders, click here.

For NMI test cards, check here.

FAQ

Q: I am using Paay.co, do I check the "Attempt 3DS" on the Merchant Setup?

A: No. For Paay.co you will pass all 3DS variables through the API with the. Learn more here.

Q: I am getting a response_code=101 returned, what does that mean?

A: A response_code=101 will indicate that there are more actions that need to be done in order to complete the charge. This is typical when using PayPal, AfterPay, Klarna or when using a 3 step redirect for 3DS transactions. To complete the transaction you will need to use the /order/{order_id}/complete method. Learn more here.

Q: What does this decline reason mean?

A: See a full list of NMI Bank Errors and Declines here.

Q: I am "By Passing $0" and passing stored credentials (CIT/MIT), what happens on the first renewal?

A: Because the initial is not hitting the gateway at all, no CIT has been passed. On the renewal initiated_by:merchant however the initial_transaction_id:"", this will be blank due to the initial never hitting the gateway and thus no intial transaction id was created.