Card Insight Router - Gateway Overview

The Card Insight Router gateway exposes an NMI-compatible transaction endpoint for card sales, authorizations, captures, refunds, voids, and validation.

Endpoint

Send all transaction requests to:

POST https://api.cirouter.com/nmi/transact

This route is POST only. GET /nmi/transact is not supported.

Content Types

The gateway accepts either of these request formats:

application/x-www-form-urlencoded
application/json

For JSON requests, send a single flat JSON object. Arrays and null request bodies are rejected.

Protocol Behavior

The gateway preserves NMI-style semantics on the wire:

Requests use standard NMI field names such as type, amount, ccnumber, and transactionid.
Responses are always returned as application/x-www-form-urlencoded.
Application errors still return HTTP 200, with failure details in the NMI response body.
Use the response field in the body, not just the HTTP status, to determine success or failure.

Quick Start

curl --request POST "https://api.cirouter.com/nmi/transact" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "type=sale" \
  --data "username=your-entrypoint-username" \
  --data "password=your-entrypoint-password" \
  --data "amount=10.00" \
  --data "ccnumber=4111111111111111" \
  --data "ccexp=1225" \
  --data "cvv=999"

Example response:

response=1&responsetext=SUCCESS&authcode=123456&transactionid=txn_100001&type=sale&response_code=100&amount=10.00

Authentication

Use the credentials provisioned for your gateway account.

Required Fields

username: your gateway username
password: your gateway password

Authentication Example

curl --request POST "https://api.cirouter.com/nmi/transact" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "type=validate" \
  --data "username=your-entrypoint-username" \
  --data "password=your-entrypoint-password" \
  --data "ccnumber=4111111111111111" \
  --data "ccexp=1225" \
  --data "cvv=999"

If the username or password is wrong, the gateway responds with an NMI-style error body such as:

response=3&responsetext=Invalid%20Password&transactionid=&response_code=300

Transaction Reference

Each transaction type below includes the fields that can be sent for that request. Some fields are duplicated across sections intentionally so each transaction type can be read on its own.

At a Glance

Type	Purpose	Required Core Fields
`sale`	Authorize and capture in one request.	`type`, `username`, `password`, `amount`, and card or vault data
`auth`	Authorize only.	`type`, `username`, `password`, `amount`, and card or vault data
`validate`	Validate payment credentials without charging.	`type`, `username`, `password`, and card or vault data
`capture`	Capture a prior auth or sale.	`type`, `username`, `password`, `transactionid`
`refund`	Refund a prior transaction.	`type`, `username`, `password`, `transactionid`
`void`	Void a prior transaction.	`type`, `username`, `password`, `transactionid`

Sale

Use type=sale for an authorization plus capture in one request.

Field	Required	Description
`type`	Yes	Must be `sale`.
`username`	Yes	Your gateway username.
`password`	Yes	Your gateway password.
`amount`	Yes	Transaction amount.
`ccnumber`	Conditional	Card number. Required unless using `customer_vault_id`.
`ccexp`	Conditional	Card expiration in `MMYY` format. Required unless using `customer_vault_id`.
`customer_vault_id`	Conditional	Vault identifier for tokenized card use. Required if not sending card data.
`cvv`	No	Card verification value.
`currency`	No	Currency code such as `USD`.
`tax`	No	Tax amount.
`shipping`	No	Shipping amount.
`ponumber`	No	Purchase order number.
`orderid`	No	Merchant order identifier.
`ipaddress`	No	End-user IP address.
`merchant_defined_field_0` ... `merchant_defined_field_19`	No	Merchant-defined custom fields.
`first_name`	No	Billing first name.
`last_name`	No	Billing last name.
`address1`	No	Billing address line 1.
`address2`	No	Billing address line 2.
`city`	No	Billing city.
`state`	No	Billing state or region.
`zip`	No	Billing postal code.
`country`	No	Billing country code.
`phone`	No	Billing phone number.
`email`	No	Billing email address.
`company`	No	Billing company name.
`shipping_firstname`	No	Shipping first name.
`shipping_lastname`	No	Shipping last name.
`shipping_address1`	No	Shipping address line 1.
`shipping_address2`	No	Shipping address line 2.
`shipping_city`	No	Shipping city.
`shipping_state`	No	Shipping state or region.
`shipping_zip`	No	Shipping postal code.
`shipping_country`	No	Shipping country code.
`shipping_phone`	No	Shipping phone number.
`shipping_email`	No	Shipping email address.
`shipping_company`	No	Shipping company name.
`industry`	No	`ecommerce` or `moto`.
`cit_mit`	No	Transaction initiation source: `customer` or `merchant`.
`billing_mode`	No	Billing mode: `recurring` or `installment`.
`installment_number`	No	Current installment number when `billing_mode=installment`.
`installment_total`	No	Total installments when `billing_mode=installment`.
`shipping_postal`	No	Level 3 B2B field: shipment destination postal code.
`ship_from_postal`	No	Level 3 B2B field: ship-from postal code.
`summary_commodity_code`	No	Level 3 B2B field: commodity code for the order summary.
`duty_amount`	No	Level 3 B2B field: duty amount.
`discount_amount`	No	Level 3 B2B field: total discount amount.
`national_tax_amount`	No	Level 3 B2B field: national tax amount.
`alternate_tax_amount`	No	Level 3 B2B field: alternate tax amount.
`alternate_tax_id`	No	Level 3 B2B field: alternate tax identifier.
`vat_tax_amount`	No	Level 3 B2B field: VAT tax amount.
`vat_tax_rate`	No	Level 3 B2B field: VAT tax rate.
`vat_invoice_reference_number`	No	Level 3 B2B field: VAT invoice reference number.
`customer_vat_registration`	No	Level 3 B2B field: customer VAT registration identifier.
`merchant_vat_registration`	No	Level 3 B2B field: merchant VAT registration identifier.
`order_date`	No	Level 3 B2B field: order date.
`item_product_code_{n}`	No	Level 3 B2B line-item product code for line item `n`.
`item_description_{n}`	No	Level 3 B2B line-item description for line item `n`.
`item_commodity_code_{n}`	No	Level 3 B2B line-item commodity code for line item `n`.
`item_unit_of_measure_{n}`	No	Level 3 B2B line-item unit of measure for line item `n`.
`item_unit_cost_{n}`	No	Level 3 B2B line-item unit cost for line item `n`.
`item_quantity_{n}`	No	Level 3 B2B line-item quantity for line item `n`.
`item_total_amount_{n}`	No	Level 3 B2B line-item total amount for line item `n`.
`item_tax_amount_{n}`	No	Level 3 B2B line-item tax amount for line item `n`.
`item_tax_rate_{n}`	No	Level 3 B2B line-item tax rate for line item `n`.
`item_discount_amount_{n}`	No	Level 3 B2B line-item discount amount for line item `n`.
`item_discount_rate_{n}`	No	Level 3 B2B line-item discount rate for line item `n`.
`item_tax_type_{n}`	No	Level 3 B2B line-item tax type for line item `n`.
`item_alternate_tax_id_{n}`	No	Level 3 B2B line-item alternate tax ID for line item `n`.
`healthcare_amount`	No	HSA/FSA healthcare amount classification.
`prescription_amount`	No	HSA/FSA prescription amount classification.
`vision_amount`	No	HSA/FSA vision amount classification.
`dental_amount`	No	HSA/FSA dental amount classification.
`hsa_other_amount`	No	Other HSA/FSA amount classification.

curl --request POST "https://api.cirouter.com/nmi/transact" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "type=sale" \
  --data "username=your-entrypoint-username" \
  --data "password=your-entrypoint-password" \
  --data "amount=10.00" \
  --data "ccnumber=4111111111111111" \
  --data "ccexp=1225" \
  --data "cvv=999"

Auth

Use type=auth to authorize without capturing.

Field	Required	Description
`type`	Yes	Must be `auth`.
`username`	Yes	Your gateway username.
`password`	Yes	Your gateway password.
`amount`	Yes	Transaction amount.
`ccnumber`	Conditional	Card number. Required unless using `customer_vault_id`.
`ccexp`	Conditional	Card expiration in `MMYY` format. Required unless using `customer_vault_id`.
`customer_vault_id`	Conditional	Vault identifier for tokenized card use. Required if not sending card data.
`cvv`	No	Card verification value.
`currency`	No	Currency code such as `USD`.
`tax`	No	Tax amount.
`shipping`	No	Shipping amount.
`ponumber`	No	Purchase order number.
`orderid`	No	Merchant order identifier.
`ipaddress`	No	End-user IP address.
`merchant_defined_field_0` ... `merchant_defined_field_19`	No	Merchant-defined custom fields.
`first_name`	No	Billing first name.
`last_name`	No	Billing last name.
`address1`	No	Billing address line 1.
`address2`	No	Billing address line 2.
`city`	No	Billing city.
`state`	No	Billing state or region.
`zip`	No	Billing postal code.
`country`	No	Billing country code.
`phone`	No	Billing phone number.
`email`	No	Billing email address.
`company`	No	Billing company name.
`shipping_firstname`	No	Shipping first name.
`shipping_lastname`	No	Shipping last name.
`shipping_address1`	No	Shipping address line 1.
`shipping_address2`	No	Shipping address line 2.
`shipping_city`	No	Shipping city.
`shipping_state`	No	Shipping state or region.
`shipping_zip`	No	Shipping postal code.
`shipping_country`	No	Shipping country code.
`shipping_phone`	No	Shipping phone number.
`shipping_email`	No	Shipping email address.
`shipping_company`	No	Shipping company name.
`industry`	No	`ecommerce` or `moto`.
`cit_mit`	No	Transaction initiation source: `customer` or `merchant`.
`billing_mode`	No	Billing mode: `recurring` or `installment`.
`installment_number`	No	Current installment number when `billing_mode=installment`.
`installment_total`	No	Total installments when `billing_mode=installment`.
`shipping_postal`	No	Level 3 B2B field: shipment destination postal code.
`ship_from_postal`	No	Level 3 B2B field: ship-from postal code.
`summary_commodity_code`	No	Level 3 B2B field: commodity code for the order summary.
`duty_amount`	No	Level 3 B2B field: duty amount.
`discount_amount`	No	Level 3 B2B field: total discount amount.
`national_tax_amount`	No	Level 3 B2B field: national tax amount.
`alternate_tax_amount`	No	Level 3 B2B field: alternate tax amount.
`alternate_tax_id`	No	Level 3 B2B field: alternate tax identifier.
`vat_tax_amount`	No	Level 3 B2B field: VAT tax amount.
`vat_tax_rate`	No	Level 3 B2B field: VAT tax rate.
`vat_invoice_reference_number`	No	Level 3 B2B field: VAT invoice reference number.
`customer_vat_registration`	No	Level 3 B2B field: customer VAT registration identifier.
`merchant_vat_registration`	No	Level 3 B2B field: merchant VAT registration identifier.
`order_date`	No	Level 3 B2B field: order date.
`item_product_code_{n}`	No	Level 3 B2B line-item product code for line item `n`.
`item_description_{n}`	No	Level 3 B2B line-item description for line item `n`.
`item_commodity_code_{n}`	No	Level 3 B2B line-item commodity code for line item `n`.
`item_unit_of_measure_{n}`	No	Level 3 B2B line-item unit of measure for line item `n`.
`item_unit_cost_{n}`	No	Level 3 B2B line-item unit cost for line item `n`.
`item_quantity_{n}`	No	Level 3 B2B line-item quantity for line item `n`.
`item_total_amount_{n}`	No	Level 3 B2B line-item total amount for line item `n`.
`item_tax_amount_{n}`	No	Level 3 B2B line-item tax amount for line item `n`.
`item_tax_rate_{n}`	No	Level 3 B2B line-item tax rate for line item `n`.
`item_discount_amount_{n}`	No	Level 3 B2B line-item discount amount for line item `n`.
`item_discount_rate_{n}`	No	Level 3 B2B line-item discount rate for line item `n`.
`item_tax_type_{n}`	No	Level 3 B2B line-item tax type for line item `n`.
`item_alternate_tax_id_{n}`	No	Level 3 B2B line-item alternate tax ID for line item `n`.
`healthcare_amount`	No	HSA/FSA healthcare amount classification.
`prescription_amount`	No	HSA/FSA prescription amount classification.
`vision_amount`	No	HSA/FSA vision amount classification.
`dental_amount`	No	HSA/FSA dental amount classification.
`hsa_other_amount`	No	Other HSA/FSA amount classification.

curl --request POST "https://api.cirouter.com/nmi/transact" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "type=auth" \
  --data "username=your-entrypoint-username" \
  --data "password=your-entrypoint-password" \
  --data "amount=10.00" \
  --data "ccnumber=4111111111111111" \
  --data "ccexp=1225"

Validate

Use type=validate to validate payment credentials without charging.

Field	Required	Description
`type`	Yes	Must be `validate`.
`username`	Yes	Your gateway username.
`password`	Yes	Your gateway password.
`ccnumber`	Conditional	Card number. Required unless using `customer_vault_id`.
`ccexp`	Conditional	Card expiration in `MMYY` format. Required unless using `customer_vault_id`.
`customer_vault_id`	Conditional	Vault identifier for tokenized card use. Required if not sending card data.
`cvv`	No	Card verification value.
`amount`	No	Optional amount value. No funds are captured by a validate request.
`currency`	No	Currency code such as `USD`.
`tax`	No	Tax amount.
`shipping`	No	Shipping amount.
`ponumber`	No	Purchase order number.
`orderid`	No	Merchant order identifier.
`ipaddress`	No	End-user IP address.
`merchant_defined_field_0` ... `merchant_defined_field_19`	No	Merchant-defined custom fields.
`first_name`	No	Billing first name.
`last_name`	No	Billing last name.
`address1`	No	Billing address line 1.
`address2`	No	Billing address line 2.
`city`	No	Billing city.
`state`	No	Billing state or region.
`zip`	No	Billing postal code.
`country`	No	Billing country code.
`phone`	No	Billing phone number.
`email`	No	Billing email address.
`company`	No	Billing company name.
`shipping_firstname`	No	Shipping first name.
`shipping_lastname`	No	Shipping last name.
`shipping_address1`	No	Shipping address line 1.
`shipping_address2`	No	Shipping address line 2.
`shipping_city`	No	Shipping city.
`shipping_state`	No	Shipping state or region.
`shipping_zip`	No	Shipping postal code.
`shipping_country`	No	Shipping country code.
`shipping_phone`	No	Shipping phone number.
`shipping_email`	No	Shipping email address.
`shipping_company`	No	Shipping company name.
`industry`	No	`ecommerce` or `moto`.
`cit_mit`	No	Transaction initiation source: `customer` or `merchant`.
`billing_mode`	No	Billing mode: `recurring` or `installment`.
`installment_number`	No	Current installment number when `billing_mode=installment`.
`installment_total`	No	Total installments when `billing_mode=installment`.
`shipping_postal`	No	Level 3 B2B field: shipment destination postal code.
`ship_from_postal`	No	Level 3 B2B field: ship-from postal code.
`summary_commodity_code`	No	Level 3 B2B field: commodity code for the order summary.
`duty_amount`	No	Level 3 B2B field: duty amount.
`discount_amount`	No	Level 3 B2B field: total discount amount.
`national_tax_amount`	No	Level 3 B2B field: national tax amount.
`alternate_tax_amount`	No	Level 3 B2B field: alternate tax amount.
`alternate_tax_id`	No	Level 3 B2B field: alternate tax identifier.
`vat_tax_amount`	No	Level 3 B2B field: VAT tax amount.
`vat_tax_rate`	No	Level 3 B2B field: VAT tax rate.
`vat_invoice_reference_number`	No	Level 3 B2B field: VAT invoice reference number.
`customer_vat_registration`	No	Level 3 B2B field: customer VAT registration identifier.
`merchant_vat_registration`	No	Level 3 B2B field: merchant VAT registration identifier.
`order_date`	No	Level 3 B2B field: order date.
`item_product_code_{n}`	No	Level 3 B2B line-item product code for line item `n`.
`item_description_{n}`	No	Level 3 B2B line-item description for line item `n`.
`item_commodity_code_{n}`	No	Level 3 B2B line-item commodity code for line item `n`.
`item_unit_of_measure_{n}`	No	Level 3 B2B line-item unit of measure for line item `n`.
`item_unit_cost_{n}`	No	Level 3 B2B line-item unit cost for line item `n`.
`item_quantity_{n}`	No	Level 3 B2B line-item quantity for line item `n`.
`item_total_amount_{n}`	No	Level 3 B2B line-item total amount for line item `n`.
`item_tax_amount_{n}`	No	Level 3 B2B line-item tax amount for line item `n`.
`item_tax_rate_{n}`	No	Level 3 B2B line-item tax rate for line item `n`.
`item_discount_amount_{n}`	No	Level 3 B2B line-item discount amount for line item `n`.
`item_discount_rate_{n}`	No	Level 3 B2B line-item discount rate for line item `n`.
`item_tax_type_{n}`	No	Level 3 B2B line-item tax type for line item `n`.
`item_alternate_tax_id_{n}`	No	Level 3 B2B line-item alternate tax ID for line item `n`.
`healthcare_amount`	No	HSA/FSA healthcare amount classification.
`prescription_amount`	No	HSA/FSA prescription amount classification.
`vision_amount`	No	HSA/FSA vision amount classification.
`dental_amount`	No	HSA/FSA dental amount classification.
`hsa_other_amount`	No	Other HSA/FSA amount classification.

curl --request POST "https://api.cirouter.com/nmi/transact" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "type=validate" \
  --data "username=your-entrypoint-username" \
  --data "password=your-entrypoint-password" \
  --data "ccnumber=4111111111111111" \
  --data "ccexp=1225"

Capture

Use type=capture with the transactionid returned by a prior successful auth or sale response.

Field	Required	Description
`type`	Yes	Must be `capture`.
`username`	Yes	Your gateway username.
`password`	Yes	Your gateway password.
`transactionid`	Yes	Prior gateway transaction ID to capture.
`amount`	No	Amount to capture.
`total_captures`	No	Optional capture count hint.
`orderid`	No	Merchant order identifier.
`ipaddress`	No	End-user IP address.
`merchant_defined_field_0` ... `merchant_defined_field_19`	No	Merchant-defined custom fields.
`industry`	No	`ecommerce` or `moto`.
`cit_mit`	No	Transaction initiation source: `customer` or `merchant`.

curl --request POST "https://api.cirouter.com/nmi/transact" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "type=capture" \
  --data "username=your-entrypoint-username" \
  --data "password=your-entrypoint-password" \
  --data "transactionid=txn_100001" \
  --data "amount=10.00"

Refund

Use type=refund with the transactionid returned by the original successful transaction response.

Field	Required	Description
`type`	Yes	Must be `refund`.
`username`	Yes	Your gateway username.
`password`	Yes	Your gateway password.
`transactionid`	Yes	Prior gateway transaction ID to refund.
`amount`	No	Amount to refund.
`orderid`	No	Merchant order identifier.
`ipaddress`	No	End-user IP address.
`merchant_defined_field_0` ... `merchant_defined_field_19`	No	Merchant-defined custom fields.
`industry`	No	`ecommerce` or `moto`.
`cit_mit`	No	Transaction initiation source: `customer` or `merchant`.

curl --request POST "https://api.cirouter.com/nmi/transact" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "type=refund" \
  --data "username=your-entrypoint-username" \
  --data "password=your-entrypoint-password" \
  --data "transactionid=txn_100001" \
  --data "amount=5.00"

Void

Use type=void with the transactionid returned by the original successful transaction response.

Field	Required	Description
`type`	Yes	Must be `void`.
`username`	Yes	Your gateway username.
`password`	Yes	Your gateway password.
`transactionid`	Yes	Prior gateway transaction ID to void.
`orderid`	No	Merchant order identifier.
`ipaddress`	No	End-user IP address.
`merchant_defined_field_0` ... `merchant_defined_field_19`	No	Merchant-defined custom fields.
`industry`	No	`ecommerce` or `moto`.
`cit_mit`	No	Transaction initiation source: `customer` or `merchant`.

curl --request POST "https://api.cirouter.com/nmi/transact" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "type=void" \
  --data "username=your-entrypoint-username" \
  --data "password=your-entrypoint-password" \
  --data "transactionid=txn_100001"

Responses and Errors

All responses are returned as URL-encoded key/value pairs with HTTP status 200.

Response Fields

Field	Description
`response`	`1` for approved, `2` for declined, `3` for error.
`responsetext`	Human-readable result text.
`transactionid`	Gateway transaction identifier.
`type`	The transaction type echoed back by the gateway.
`response_code`	Gateway response code.
`authcode`	Present for approved sale and capture responses.
`amount`	Present on sale/auth/validate responses when available.
`avsresponse`	AVS result code.
`cvvresponse`	CVV result code.
`customer_vault_id`	Present when a vault record is created.

Interpreting Results

Treat response=1 as approved.
Treat response=2 as declined.
Treat response=3 as an error.
Persist the returned transactionid if you may need to capture, refund, or void later.

Successful Response

response=1&responsetext=SUCCESS&authcode=123456&transactionid=txn_100001&type=sale&response_code=100&amount=10.00&avsresponse=Y&

Decline Response

response=2&responsetext=DECLINE&transactionid=txn_100001&type=sale&response_code=200

Error Response

response=3&responsetext=Amount%20is%20required&transactionid=&response_code=300

Error Handling Notes

Invalid or missing type returns an NMI error body.
Invalid JSON returns response=3 with a validation message.
Unknown usernames return responsetext=Invalid username.
Invalid passwords return responsetext=Invalid Password.
Some server-side failures may return An error has occurred.