POST
| POST URL: | https://api.openpath.io/v1/nmi |
The Openpath NMI Emulation API can receive Transactions posted in any of the following formats listed below:
| Query String (Not Recommended) |
A query string is a part of a uniform resource locator (URL) that assigns values to specified parameters. A query string commonly includes fields added to a base URL by a Web browser or other client application, for example as part of an HTML, choosing the appearance of a page, or jumping to positions in multimedia content. |
| Form Data | The FormData interface provides a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using the XMLHttpRequest.send() method. It uses the same format a form would use if the encoding type were set to "multipart/form-data". |
| X-WWW Form URL Encoded (Recommended) |
"application/x-www-form-urlencoded" is the default encoding (in HTTP terms Content-Type) a web form uses to transfer data, not multipart/form-data. To send an HTTP post request on form submission with a Content Type of multipart/form-data, one must explicitly specify this as the enctype value. |
Sale (sale)
Transaction sales are submitted and immediately flagged for settlement.
Authorization (auth)
Transaction authorizations are authorized immediately but are not flagged for settlement. These transactions must be flagged for settlement using the capture transaction type.
Credit (credit)
Transaction credits apply an amount to the cardholder's card that was not originally processed through the Gateway. In most situations credits are disabled as transaction refunds should be used instead.
Validate (validate)
This action is used for doing an "Account Verification" on the cardholder's credit card without actually doing an authorization.
| Variable Name | Description |
|---|---|
| type* | The type of transaction to be processed. Values: 'sale', 'auth', 'credit', 'validate' |
| username* | Site Username assigned to a merchant Site account as API Login ID. |
| password* | Site Password assigned to a merchant Site account as Transaction Key. |
| ccnumber** | Credit card number. |
| ccexp** | Credit card expiration date. Format: MMYY |
| cvv | The card security code. While this is not required, it is strongly recommended. |
| checkname*** | The name on the customer's ACH account. |
| checkaba*** | The customer's bank routing number. |
| checkaccount*** | The customer's bank account number. |
| account_holder_type | The type of ACH account the customer has. Values: 'business' or 'personal' |
| account_type | The ACH account entity of the customer. Values: 'checking' or 'savings' |
| sec_code | The Standard Entry Class code of the ACH transaction. Values: 'PPD', 'WEB', 'TEL', or 'CCD' |
| amount | Total amount to be charged. For validate, the amount must be omitted or set to 0.00. Format: x.xx |
| surcharge | Surcharge amount. Format: x.xx |
| cash_discount | How much less a customer paid due to a cash discount. Format: x.xx, only applicable to cash and check transactions |
| tip | The final tip amount, included in the transaction, associated with the purchase Format: x.xx |
| currency | The transaction currency. Format: ISO 4217 |
| payment*** | The type of payment. Default: 'creditcard' Values: 'creditcard', 'check', or 'cash' |
| processor_id | If using Multiple MIDs, route to this processor (processor_id is obtained under Settings → Transaction Routing in the Control Panel). |
| authorization_code‡ | Specify authorization code. For use with "offline" action only. |
| dup_seconds | Sets the time in seconds for duplicate transaction checking on supported processors. Set to 0 to disable duplicate checking. This value should not exceed 7862400. |
| descriptor | Set payment descriptor on supported processors. |
| descriptor_phone | Set payment descriptor phone on supported processors. |
| descriptor_address | Set payment descriptor address on supported processors. |
| descriptor_city | Set payment descriptor city on supported processors. |
| descriptor_state | Set payment descriptor state on supported processors. |
| descriptor_postal | Set payment descriptor postal code on supported processors. |
| descriptor_country | Set payment descriptor country on supported processors. |
| descriptor_mcc | Set payment descriptor mcc on supported processors. |
| descriptor_merchant_id | Set payment descriptor merchant id on supported processors. |
| descriptor_url | Set payment descriptor url on supported processors. |
| billing_method | Should be set to 'recurring' to mark payment as a recurring transaction or 'installment' to mark payment as an installment transaction. Values: 'recurring', 'installment' |
| billing_number | Specify installment billing number, on supported processors. For use when "billing_method" is set to installment. Values: 0-99 |
| billing_total | Specify installment billing total on supported processors. For use when "billing_method" is set to installment. |
| order_description | Order description. Legacy variable includes: orderdescription |
| orderid | Order Id |
| ipaddress | IP address of cardholder, this field is recommended. Format: xxx.xxx.xxx.xxx |
| tax**** | 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 |
| shipping**** | Total shipping amount. |
| ponumber**** | Original purchase order. |
| first_name | Cardholder's first name. Legacy variable includes: firstname |
| last_name | Cardholder's last name Legacy variable includes: lastname |
| company | Cardholder's company |
| address1 | Card billing address |
| address2 | Card billing address, line 2 |
| city | Card billing city |
| state | Card billing state. Format: CC |
| zip | Card billing zip code |
| country | Card billing country. Country codes are as shown in ISO 3166. Format: CC |
| phone | Billing phone number |
| fax | Billing fax number |
| Billing email address | |
| social_security_number | Customer's social security number, checked against bad check writers database if check verification is enabled. |
| drivers_license_number | Driver's license number. |
| drivers_license_dob | Driver's license date of birth. |
| drivers_license_state | The state that issued the customer's driver's license. |
| shipping_firstname | Shipping first name |
| shipping_lastname | Shipping last name |
| shipping_company | Shipping company |
| shipping_address1 | Shipping address |
| shipping_address2 | Shipping address, line 2 |
| shipping_city | Shipping city |
| shipping_state | Shipping state Format: CC |
| shipping_zip | Shipping zip code |
| shipping_country | Shipping country Country codes are as shown in ISO 3166. Format: CC |
| shipping_email | Shipping email address |
| merchant_defined_field_# | You can pass custom information in up to 20 fields. Format: merchant_defined_field_1=Value |
| customer_receipt | If set to true, when the customer is charged, they will be sent a transaction receipt. Values: 'true' or 'false' |
| signature_image | Cardholder signature image. For use with "sale" and "auth" actions only. Format: base64 encoded raw PNG image. (16kiB maximum) |
| cardholder_auth‡‡ | Set 3D Secure condition. Value used to determine E-commerce indicator (ECI). Values: 'verified' or 'attempted' |
| cavv‡‡ | Cardholder authentication verification value. Format: base64 encoded |
| xid‡‡ | Cardholder authentication transaction id. Format: base64 encoded |
| three_ds_version‡‡ | 3DSecure version. Examples: "1.0.2" or "2.2.0" |
| directory_server_id | Directory Server Transaction ID. May be provided as part of 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| source_transaction_id | 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. |
| pinless_debit_override | Set to 'Y' if you have Pinless Debit Conversion enabled but want to opt out for this transaction. Feature applies to selected processors only. |
| Recurring specific fields | |
| recurring | Recurring action to be processed. Values: add_subscription |
| plan_id | Create a subscription tied to a Plan ID if the sale/auth transaction is successful. |
| plan_payments | The number of payments before the recurring plan is complete. Note: Use '0' for 'until canceled' |
| plan_amount | The plan amount to be charged each billing cycle. Format: x.xx |
| day_frequency | How often, in days, to charge the customer. Cannot be set with 'month_frequency' or 'day_of_month'. |
| month_frequency | How often, in months, to charge the customer. Cannot be set with 'day_frequency'. Must be set with 'day_of_month'. Values: 1 through 24 |
| day_of_month | The day that the customer will be charged. Cannot be set with 'day_frequency'. Must be set with 'month_frequency'. Values: 1 through 31 - for months without 29, 30, or 31 days, the charge will be on the last day |
| start_date | The first day that the customer will be charged. Format: YYYYMMDD |
| Customer Vault specific fields | |
| customer_vault | Associate payment information with a Customer Vault record if the transaction is successful. Values: 'add_customer' or 'update_customer' |
| customer_vault_id | Specifies a Customer Vault id. If not set, the payment gateway will randomly generate a Customer Vault id. |
| Stored Credentials (CIT/MIT) | |
| initiated_by | Who initiated the transaction. Values: 'customer' or 'merchant' |
| initial_transaction_id | Original payment gateway transaction id. |
| stored_credential_indicator | The indicator of the stored credential. Values: 'stored' or 'used' 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. |
| Level III specific order fields | |
| shipping† | Freight or shipping amount included in the transaction amount. Default: '0.00' Format: x.xx |
| tax† | 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 |
| ponumber† | Purchase order number supplied by cardholder |
| orderid† | Identifier assigned by the merchant. This defaults to gateway transaction id. |
| shipping_country† | Shipping country (e.g. US) Format: CC |
| shipping_postal† | 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. |
| ship_from_postal† | Postal/ZIP code of the address from where purchased goods are being shipped, defaults to merchant profile postal code. |
| summary_commodity_code† | 4 character international description code of the overall goods or services being supplied. The acquirer or processor will provide a list of current codes. |
| duty_amount | Amount included in the transaction amount associated with the import of purchased goods. Default: '0.00' Format: x.xx |
| discount_amount | Amount included in the transaction amount of any discount applied to complete order by the merchant. Default: '0.00' Format: x.xx |
| national_tax_amount | The national tax amount included in the transaction amount. Default: '0.00' Format: x.xx |
| alternate_tax_amount | 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 |
| alternate_tax_id | Tax identification number of the merchant that reported the alternate tax amount. |
| vat_tax_amount | Contains the amount of any value added taxes which can be associated with the purchased item. Default: '0.00' Format: x.xx |
| vat_tax_rate | 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 |
| vat_invoice_reference_number | Invoice number that is associated with the VAT invoice. |
| customer_vat_registration | Value added tax registration number supplied by the cardholder. |
| merchant_vat_registration | Government assigned tax identification number of the merchant for whom the goods or services were purchased from. |
| order_date | Purchase order date, defaults to the date of the transaction. Format: YYMMDD |
| Level III specific line item detail fields | |
| item_product_code_#† | Merchant defined description code of the item being purchased. |
| item_description_#† | Description of the item(s) being supplied. |
| item_commodity_code_#† | International description code of the individual good or service being supplied. The acquirer or processor will provide a list of current codes. |
| item_unit_of_measure_#† | Code for units of measurement as used in international trade. Default: 'EACH' |
| item_unit_cost_#† | Unit cost of item purchased, may contain up to 4 decimal places. |
| item_quantity_#† | Quantity of the item(s) being purchased. Default: '1' |
| item_total_amount_#† | Purchase amount associated with the item. Defaults to: 'item_unit_cost_#' x 'item_quantity_#' rounded to the nearest penny. |
| item_tax_amount_#† | Amount of sales tax on specific item. Amount should not be included in 'total_amount_#'. Default: '0.00' Format: x.xx |
| item_tax_rate_#† | Percentage representing the value-added tax applied. Default: '0.00' |
| item_discount_amount_# | 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_#'. |
| item_discount_rate_# | Discount rate for the line item. 1% = 1.00. Default: '0.00' |
| item_tax_type_# | Type of value-added taxes that are being used. |
| item_alternate_tax_id_# | Tax identification number of the merchant that reported the alternate tax amount. |
| * | Always required |
| ** | Required for credit card transactions |
| *** | Required for ACH transactions |
| **** | Required for Level 2 transactions |
| † | Required for Level 3 transactions |
| ‡ | Required for offline transactions |
| ‡‡ | Required for 3D Secure transactions |
Notes:
- Level II fields are required for Level II processing.
- Level II and Level III fields are required for Level III processing.
- You can pass only credit card or e-check transaction variables in a request, not in the same request.
- Certain banks may require some optional fields.
- Some characters output from base64 encoding cannot be passed directly into the API (i.e., "+") so ensure these fields are also properly URL encoded.
Comments
0 comments
Please sign in to leave a comment.