Classic: Invoice management
POST /transact.php · Invoice management
Classic protocol
This family uses POST /transact.php under the documented sandbox base https://sandbox.nmi.com/api. Send application/x-www-form-urlencoded fields with the private security_key on your server. Do not substitute a REST JSON body or REST Authorization header. Each named variant below has its own action selector and required fields. For maintenance of a Classic integration. Source examples are fixtures, not live credentials; replace their security_key before any authorized test. This reference sends no requests.
Choose the operation variant
Variant Selector fields Required fields CreateInvoice UpdateInvoice SendInvoice CloseInvoice
Request language templates
Original transport templates derived from this endpoint’s documented method, server, authentication and media type. Replace path/query/credential placeholders with authorized sandbox values. These examples print the raw status and response; they do not infer business success or retry a request. Save properly URL-encoded name=value pairs for your selected operation as request.form, including its private security_key when required. JSON example objects below describe these form fields; they are not the wire encoding. Node requires a runtime with fetch; PHP requires cURL. Generated source-based examples have not been executed against provider accounts. curl --request POST \ --url 'https://sandbox.nmi.com/api/transact.php' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-binary '@request.form' import { readFile } from 'node:fs/promises'; const body = await readFile('request.form', 'utf8'); const response = await fetch("https://sandbox.nmi.com/api/transact.php", { method: 'POST', headers: { "Content-Type": "application/x-www-form-urlencoded" }, body }); console.log(response.status, await response.text()); from urllib.request import Request, urlopen from urllib.error import HTTPError from pathlib import Path request = Request('https://sandbox.nmi.com/api/transact.php', method='POST', headers={'Content-Type': 'application/x-www-form-urlencoded'}, data=Path('request.form').read_bytes()) try: with urlopen(request, timeout=30) as response: print(response.status, response.read().decode()) except HTTPError as error: print(error.code, error.read().decode()) require 'net/http' require 'uri' uri = URI("https://sandbox.nmi.com/api/transact.php") request = Net::HTTP::Post.new(uri) request["Content-Type"] = "application/x-www-form-urlencoded" request.body = File.binread('request.form') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 30) { |http| http.request(request) } puts response.code puts response.body <?php $curl = curl_init('https://sandbox.nmi.com/api/transact.php'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'], CURLOPT_POSTFIELDS => file_get_contents('request.form') ]); $response = curl_exec($curl); if ($response === false) { throw new RuntimeException(curl_error($curl)); } echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $response; curl_close($curl);
Request fields
Choose one schema variant. Descriptions retain conditional requirements that are not always included in required arrays. Do not merge all variants into one request. Field Type Required Description Constraints [oneOf 1].[allOf 3].security_key string no API Security Key assigned to a merchant account. New keys can be generated from the merchant control panel in Settings > Security Keys [oneOf 1].[allOf 3].invoicing string no Create a new invoice and email it to the customer. enum: ["add_invoice"] [oneOf 1].[allOf 3].amount string no Total amount to be invoiced. Must be greater than 0.00. Format: x.xx [oneOf 1].[allOf 3].email string no Billing email address [oneOf 1].[allOf 3].payment_terms string no When the invoice should be paid. Values: 'upon_receipt', or integers from 0-999. Default - `upon_receipt`. [oneOf 1].[allOf 3].payment_methods_allowed string no What payment methods a customer may use when paying invoice. Defaults to all available payment methods available in your merchant account Values: 'cc', 'ck', and 'cs'. Multiple payment types can be selected by comma-separating values. [oneOf 1].[allOf 3].processor_id string no If using Multiple MIDs, route to this processor (processor_id is obtained under Settings → Transaction Routing in the Control Panel). If allowing multiple payment types, one processor_id can be selected per payment type by submitting comma-separated values. [oneOf 1].[allOf 3].currency string no The transaction currency. Format: ISO 4217 [oneOf 1].[allOf 3].order_description string no Order description. Legacy variable includes: orderdescription [oneOf 1].[allOf 3].orderid string no Order ID. [oneOf 1].[allOf 3].customer_id string no Customer ID. [oneOf 1].[allOf 3].customer_tax_id string no Customer Tax ID. [oneOf 1].[allOf 3].tax number no Total sales tax amount. format: "float" [oneOf 1].[allOf 3].shipping number no Total shipping amount. format: "float" [oneOf 1].[allOf 3].ponumber string no Original purchase order. [oneOf 1].[allOf 3].first_name string no Cardholder's first name. Legacy variable includes: firstname [oneOf 1].[allOf 3].last_name string no Cardholder's last name. Legacy variable includes: lastname [oneOf 1].[allOf 3].company string no Cardholder's company. [oneOf 1].[allOf 3].address1 string no Card billing address. [oneOf 1].[allOf 3].address2 string no Card billing address, line 2. [oneOf 1].[allOf 3].city string no Card billing city. [oneOf 1].[allOf 3].state string no Card billing state. Format: `CC` [oneOf 1].[allOf 3].zip string no Card billing zip code. [oneOf 1].[allOf 3].country string no Card billing country. *Country codes are as shown in ISO 3166-1 alpha-2*. Format: `CC` [oneOf 1].[allOf 3].phone string no Billing phone number. [oneOf 1].[allOf 3].fax string no Billing fax number. [oneOf 1].[allOf 3].website string no Customer website. [oneOf 1].[allOf 3].shipping_firstname string no Shipping first name. [oneOf 1].[allOf 3].shipping_lastname string no Shipping last name. [oneOf 1].[allOf 3].shipping_company string no Shipping company. [oneOf 1].[allOf 3].shipping_address1 string no Shipping address. [oneOf 1].[allOf 3].shipping_address2 string no Shipping address, line 2. [oneOf 1].[allOf 3].shipping_city string no Shipping city. [oneOf 1].[allOf 3].shipping_state string no Shipping state. Format: `CC` [oneOf 1].[allOf 3].shipping_zip string no Shipping zip code. [oneOf 1].[allOf 3].shipping_country string no Shipping country. *Country codes are as shown in ISO 3166-1 alpha-2*. Format: `CC` [oneOf 1].[allOf 3].shipping_email string no Shipping email address. [oneOf 1].[allOf 3].merchant_defined_field_1 string no Merchant defined field which can be set up in merchant control panel under Settings->Merchant Defined Fields. You can pass custom information in up to 20 fields. Format: `merchant_defined_field_1=Value1`, `merchant_defined_field_2=Value2`, etc... [oneOf 1].[allOf 4].item_product_code_1 string no Merchant defined description code of the item being purchased. [oneOf 1].[allOf 4].item_description_1 string no Description of the item(s) being supplied. [oneOf 1].[allOf 4].item_commodity_code_1 string no International description code of the individual good or service being supplied. The acquirer or processor will provide a list of current codes. [oneOf 1].[allOf 4].item_unit_of_measure_1 string no Code for units of measurement as used in international trade. Default: 'EACH' [oneOf 1].[allOf 4].item_unit_cost_1 number no Unit cost of item purchased, may contain up to 4 decimal places. format: "float" [oneOf 1].[allOf 4].item_quantity_1 integer no Quantity of the item(s) being purchased. Default: '1' [oneOf 1].[allOf 4].item_total_amount_1 number no Purchase amount associated with the item. Defaults to: 'item_unit_cost_#' x 'item_quantity_#' rounded to the nearest penny. format: "float" [oneOf 1].[allOf 4].item_tax_amount_1 number no Amount of sales tax on specific item. Amount should not be included in 'total_amount_#'. Default: '0.00' format: "float" [oneOf 1].[allOf 4].item_tax_rate_1 number no Percentage representing the value-added tax applied. Default: '0.00' format: "float" [oneOf 1].[allOf 4].item_discount_amount_1 number no 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_#'. format: "float" [oneOf 1].[allOf 4].item_discount_rate_1 number no Discount rate for the line item. 1% = 1.00. Default: '0.00' format: "float" [oneOf 1].[allOf 4].item_tax_type_1 string no Type of value-added taxes that are being used. [oneOf 1].[allOf 4].item_alternate_tax_id_1 string no Tax identification number of the merchant that reported the alternate tax amount. [oneOf 2].[allOf 3].security_key string no API Security Key assigned to a merchant account. New keys can be generated from the merchant control panel in Settings > Security Keys [oneOf 2].[allOf 3].invoicing string no Update invoice enum: ["update_invoice"] [oneOf 2].[allOf 3].invoice_id string no The invoice ID to be updated. [oneOf 2].[allOf 3].amount string no Total amount to be invoiced. Must be greater than 0.00. Format: x.xx [oneOf 2].[allOf 3].email string no Billing email address [oneOf 2].[allOf 3].payment_terms string no When the invoice should be paid. Values: 'upon_receipt', or integers from 0-999. Default - `upon_receipt`. [oneOf 2].[allOf 3].payment_methods_allowed string no What payment methods a customer may use when paying invoice. Defaults to all available payment methods available in your merchant account Values: 'cc', 'ck', and 'cs'. Multiple payment types can be selected by comma-separating values. [oneOf 2].[allOf 3].processor_id string no If using Multiple MIDs, route to this processor (processor_id is obtained under Settings → Transaction Routing in the Control Panel). If allowing multiple payment types, one processor_id can be selected per payment type by submitting comma-separated values. [oneOf 2].[allOf 3].order_description string no Order description. Legacy variable includes: orderdescription [oneOf 2].[allOf 3].orderid string no Order ID. [oneOf 2].[allOf 3].customer_id string no Customer ID. [oneOf 2].[allOf 3].customer_tax_id string no Customer Tax ID. [oneOf 2].[allOf 3].tax number no Total sales tax amount. format: "float" [oneOf 2].[allOf 3].shipping number no Total shipping amount. format: "float" [oneOf 2].[allOf 3].ponumber string no Original purchase order. [oneOf 2].[allOf 3].first_name string no Cardholder's first name. Legacy variable includes: firstname [oneOf 2].[allOf 3].last_name string no Cardholder's last name. Legacy variable includes: lastname [oneOf 2].[allOf 3].company string no Cardholder's company. [oneOf 2].[allOf 3].address1 string no Card billing address. [oneOf 2].[allOf 3].address2 string no Card billing address, line 2. [oneOf 2].[allOf 3].city string no Card billing city. [oneOf 2].[allOf 3].state string no Card billing state. Format: `CC` [oneOf 2].[allOf 3].zip string no Card billing zip code. [oneOf 2].[allOf 3].country string no Card billing country. *Country codes are as shown in ISO 3166-1 alpha-2*. Format: `CC` [oneOf 2].[allOf 3].phone string no Billing phone number. [oneOf 2].[allOf 3].fax string no Billing fax number. [oneOf 2].[allOf 3].website string no Customer website. [oneOf 2].[allOf 3].shipping_firstname string no Shipping first name. [oneOf 2].[allOf 3].shipping_lastname string no Shipping last name. [oneOf 2].[allOf 3].shipping_company string no Shipping company. [oneOf 2].[allOf 3].shipping_address1 string no Shipping address. [oneOf 2].[allOf 3].shipping_address2 string no Shipping address, line 2. [oneOf 2].[allOf 3].shipping_city string no Shipping city. [oneOf 2].[allOf 3].shipping_state string no Shipping state. Format: `CC` [oneOf 2].[allOf 3].shipping_zip string no Shipping zip code. [oneOf 2].[allOf 3].shipping_country string no Shipping country. *Country codes are as shown in ISO 3166-1 alpha-2*. Format: `CC` [oneOf 2].[allOf 3].shipping_email string no Shipping email address. [oneOf 2].[allOf 3].merchant_defined_field_1 string no Merchant defined field which can be set up in merchant control panel under Settings->Merchant Defined Fields. You can pass custom information in up to 20 fields. Format: `merchant_defined_field_1=Value1`, `merchant_defined_field_2=Value2`, etc... [oneOf 2].[allOf 4].item_product_code_1 string no Merchant defined description code of the item being purchased. [oneOf 2].[allOf 4].item_description_1 string no Description of the item(s) being supplied. [oneOf 2].[allOf 4].item_commodity_code_1 string no International description code of the individual good or service being supplied. The acquirer or processor will provide a list of current codes. [oneOf 2].[allOf 4].item_unit_of_measure_1 string no Code for units of measurement as used in international trade. Default: 'EACH' [oneOf 2].[allOf 4].item_unit_cost_1 number no Unit cost of item purchased, may contain up to 4 decimal places. format: "float" [oneOf 2].[allOf 4].item_quantity_1 integer no Quantity of the item(s) being purchased. Default: '1' [oneOf 2].[allOf 4].item_total_amount_1 number no Purchase amount associated with the item. Defaults to: 'item_unit_cost_#' x 'item_quantity_#' rounded to the nearest penny. format: "float" [oneOf 2].[allOf 4].item_tax_amount_1 number no Amount of sales tax on specific item. Amount should not be included in 'total_amount_#'. Default: '0.00' format: "float" [oneOf 2].[allOf 4].item_tax_rate_1 number no Percentage representing the value-added tax applied. Default: '0.00' format: "float" [oneOf 2].[allOf 4].item_discount_amount_1 number no 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_#'. format: "float" [oneOf 2].[allOf 4].item_discount_rate_1 number no Discount rate for the line item. 1% = 1.00. Default: '0.00' format: "float" [oneOf 2].[allOf 4].item_tax_type_1 string no Type of value-added taxes that are being used. [oneOf 2].[allOf 4].item_alternate_tax_id_1 string no Tax identification number of the merchant that reported the alternate tax amount. [oneOf 3].[allOf 2].security_key string no API Security Key assigned to a merchant account. New keys can be generated from the merchant control panel in Settings > Security Keys [oneOf 3].[allOf 2].invoicing string no Send an existing invoice to a customer. enum: ["send_invoice"] [oneOf 3].[allOf 2].invoice_id string no The invoice ID to be emailed. [oneOf 4].[allOf 2].security_key string no API Security Key assigned to a merchant account. New keys can be generated from the merchant control panel in Settings > Security Keys [oneOf 4].[allOf 2].invoicing string no The invoice to be closed. enum: ["close_invoice"] [oneOf 4].[allOf 2].invoice_id string no The invoice ID to be closed. { "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateInvoice" }, { "$ref": "#/components/schemas/UpdateInvoice" }, { "$ref": "#/components/schemas/SendInvoice" }, { "$ref": "#/components/schemas/CloseInvoice" } ] }, "examples": { "CreateInvoice": { "$ref": "#/components/examples/CreateInvoice" }, "UpdateInvoice": { "$ref": "#/components/examples/UpdateInvoice" }, "SendInvoice": { "$ref": "#/components/examples/SendInvoice" }, "CloseInvoice": { "$ref": "#/components/examples/CloseInvoice" } } } } } true
Response contract
The Classic methodology describes ampersand-delimited name/value responses. Where this schema advertises JSON media, that declaration is retained below as a source inconsistency; do not assume REST response parsing. For payments, response 1/2/3 distinguishes approval, decline and error. A transport success alone does not prove a payment was approved. { "200": { "description": "Invoice operation completed successfully", "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Response" }, "examples": { "InvoiceCreated": { "$ref": "#/components/examples/InvoiceCreated" }, "InvoiceUpdated": { "$ref": "#/components/examples/InvoiceUpdated" }, "InvoiceSent": { "$ref": "#/components/examples/InvoiceSent" }, "InvoiceClosed": { "$ref": "#/components/examples/InvoiceClosed" }, "InvoiceClosedAlready": { "$ref": "#/components/examples/InvoiceClosedAlready" }, "Declined Request": { "$ref": "#/components/examples/DeclinedResponse" } } } } } } true
Referenced schema definitions
All schemas and source example objects are preserved here, including descriptions, enums and references. Sample data may be historical. These JSON objects describe form parameters; they are not instructions to send JSON to Classic. { "schemas": { "SecurityKey": { "type": "string", "description": "API Security Key assigned to a merchant account. New keys can be generated from the merchant control panel in Settings > Security Keys" }, "ProductInformation": { "type": "object", "properties": { "item_product_code_1": { "type": "string", "description": "Merchant defined description code of the item being purchased." }, "item_description_1": { "type": "string", "description": "Description of the item(s) being supplied." }, "item_commodity_code_1": { "type": "string", "description": "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_1": { "type": "string", "description": "Code for units of measurement as used in international trade. Default: 'EACH'" }, "item_unit_cost_1": { "type": "number", "description": "Unit cost of item purchased, may contain up to 4 decimal places.", "format": "float" }, "item_quantity_1": { "type": "integer", "description": "Quantity of the item(s) being purchased. Default: '1'" }, "item_total_amount_1": { "type": "number", "description": "Purchase amount associated with the item. Defaults to: 'item_unit_cost_#' x 'item_quantity_#' rounded to the nearest penny.", "format": "float" }, "item_tax_amount_1": { "type": "number", "description": "Amount of sales tax on specific item. Amount should not be included in 'total_amount_#'. Default: '0.00'", "format": "float" }, "item_tax_rate_1": { "type": "number", "description": "Percentage representing the value-added tax applied. Default: '0.00'", "format": "float" }, "item_discount_amount_1": { "type": "number", "description": "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_#'.", "format": "float" }, "item_discount_rate_1": { "type": "number", "description": "Discount rate for the line item. 1% = 1.00. Default: '0.00'", "format": "float" }, "item_tax_type_1": { "type": "string", "description": "Type of value-added taxes that are being used." }, "item_alternate_tax_id_1": { "type": "string", "description": "Tax identification number of the merchant that reported the alternate tax amount." } } }, "CreateInvoice": { "title": "Create Invoice", "allOf": [ { "required": [ "invoicing", "amount", "email", "security_key" ] }, { "additionalProperties": { "type": "string", "description": "Up to 99 sets of item_* fields are allowed. Up to 20 merchant_defined_field_* are allowed." } }, { "type": "object", "properties": { "security_key": { "$ref": "#/components/schemas/SecurityKey" }, "invoicing": { "type": "string", "enum": [ "add_invoice" ], "description": "Create a new invoice and email it to the customer." }, "amount": { "type": "string", "description": "Total amount to be invoiced. Must be greater than 0.00.\n\nFormat: x.xx" }, "email": { "type": "string", "description": "Billing email address" }, "payment_terms": { "type": "string", "description": "When the invoice should be paid. Values: 'upon_receipt', or integers from 0-999. Default - `upon_receipt`." }, "payment_methods_allowed": { "type": "string", "description": "What payment methods a customer may use when paying invoice.\n\nDefaults to all available payment methods available in your merchant account\nValues: 'cc', 'ck', and 'cs'. Multiple payment types can be selected by comma-separating values." }, "processor_id": { "type": "string", "description": "If using Multiple MIDs, route to this processor (processor_id is obtained under Settings \u2192 Transaction Routing in the Control Panel).\n\nIf allowing multiple payment types, one processor_id can be selected per payment type by submitting comma-separated values." }, "currency": { "type": "string", "description": "The transaction currency.\n\nFormat: ISO 4217" }, "order_description": { "type": "string", "description": "Order description. Legacy variable includes: orderdescription" }, "orderid": { "type": "string", "description": "Order ID." }, "customer_id": { "type": "string", "description": "Customer ID." }, "customer_tax_id": { "type": "string", "description": "Customer Tax ID." }, "tax": { "type": "number", "description": "Total sales tax amount.", "format": "float" }, "shipping": { "type": "number", "description": "Total shipping amount.", "format": "float" }, "ponumber": { "type": "string", "description": "Original purchase order." }, "first_name": { "type": "string", "description": "Cardholder's first name. Legacy variable includes: firstname" }, "last_name": { "type": "string", "description": "Cardholder's last name. Legacy variable includes: lastname" }, "company": { "type": "string", "description": "Cardholder's company." }, "address1": { "type": "string", "description": "Card billing address." }, "address2": { "type": "string", "description": "Card billing address, line 2." }, "city": { "type": "string", "description": "Card billing city." }, "state": { "type": "string", "description": "Card billing state.\n \nFormat: `CC`" }, "zip": { "type": "string", "description": "Card billing zip code." }, "country": { "type": "string", "description": "Card billing country. *Country codes are as shown in ISO 3166-1 alpha-2*.\n \nFormat: `CC`" }, "phone": { "type": "string", "description": "Billing phone number." }, "fax": { "type": "string", "description": "Billing fax number." }, "website": { "type": "string", "description": "Customer website." }, "shipping_firstname": { "type": "string", "description": "Shipping first name." }, "shipping_lastname": { "type": "string", "description": "Shipping last name." }, "shipping_company": { "type": "string", "description": "Shipping company." }, "shipping_address1": { "type": "string", "description": "Shipping address." }, "shipping_address2": { "type": "string", "description": "Shipping address, line 2." }, "shipping_city": { "type": "string", "description": "Shipping city." }, "shipping_state": { "type": "string", "description": "Shipping state.\n \nFormat: `CC`" }, "shipping_zip": { "type": "string", "description": "Shipping zip code." }, "shipping_country": { "type": "string", "description": "Shipping country. *Country codes are as shown in ISO 3166-1 alpha-2*.\n \nFormat: `CC`" }, "shipping_email": { "type": "string", "description": "Shipping email address." }, "merchant_defined_field_1": { "type": "string", "description": "Merchant defined field which can be set up in merchant control panel under Settings->Merchant Defined Fields. You can pass custom information in up to 20 fields.\n\nFormat: `merchant_defined_field_1=Value1`, `merchant_defined_field_2=Value2`, etc..." } } }, { "$ref": "#/components/schemas/ProductInformation" } ] }, "UpdateInvoice": { "title": "Update Invoice", "allOf": [ { "required": [ "invoicing", "invoice_id", "security_key" ] }, { "additionalProperties": { "type": "string", "description": "Up to 99 sets of item_* fields are allowed. Up to 20 merchant_defined_field_* are allowed." } }, { "type": "object", "properties": { "security_key": { "$ref": "#/components/schemas/SecurityKey" }, "invoicing": { "type": "string", "enum": [ "update_invoice" ], "description": "Update invoice" }, "invoice_id": { "type": "string", "description": "The invoice ID to be updated." }, "amount": { "type": "string", "description": "Total amount to be invoiced. Must be greater than 0.00.\n\nFormat: x.xx" }, "email": { "type": "string", "description": "Billing email address" }, "payment_terms": { "type": "string", "description": "When the invoice should be paid. Values: 'upon_receipt', or integers from 0-999. Default - `upon_receipt`." }, "payment_methods_allowed": { "type": "string", "description": "What payment methods a customer may use when paying invoice.\n\nDefaults to all available payment methods available in your merchant account\nValues: 'cc', 'ck', and 'cs'. Multiple payment types can be selected by comma-separating values." }, "processor_id": { "type": "string", "description": "If using Multiple MIDs, route to this processor (processor_id is obtained under Settings \u2192 Transaction Routing in the Control Panel).\n\nIf allowing multiple payment types, one processor_id can be selected per payment type by submitting comma-separated values." }, "order_description": { "type": "string", "description": "Order description. Legacy variable includes: orderdescription" }, "orderid": { "type": "string", "description": "Order ID." }, "customer_id": { "type": "string", "description": "Customer ID." }, "customer_tax_id": { "type": "string", "description": "Customer Tax ID." }, "tax": { "type": "number", "description": "Total sales tax amount.", "format": "float" }, "shipping": { "type": "number", "description": "Total shipping amount.", "format": "float" }, "ponumber": { "type": "string", "description": "Original purchase order." }, "first_name": { "type": "string", "description": "Cardholder's first name. Legacy variable includes: firstname" }, "last_name": { "type": "string", "description": "Cardholder's last name. Legacy variable includes: lastname" }, "company": { "type": "string", "description": "Cardholder's company." }, "address1": { "type": "string", "description": "Card billing address." }, "address2": { "type": "string", "description": "Card billing address, line 2." }, "city": { "type": "string", "description": "Card billing city." }, "state": { "type": "string", "description": "Card billing state.\n \nFormat: `CC`" }, "zip": { "type": "string", "description": "Card billing zip code." }, "country": { "type": "string", "description": "Card billing country. *Country codes are as shown in ISO 3166-1 alpha-2*.\n \nFormat: `CC`" }, "phone": { "type": "string", "description": "Billing phone number." }, "fax": { "type": "string", "description": "Billing fax number." }, "website": { "type": "string", "description": "Customer website." }, "shipping_firstname": { "type": "string", "description": "Shipping first name." }, "shipping_lastname": { "type": "string", "description": "Shipping last name." }, "shipping_company": { "type": "string", "description": "Shipping company." }, "shipping_address1": { "type": "string", "description": "Shipping address." }, "shipping_address2": { "type": "string", "description": "Shipping address, line 2." }, "shipping_city": { "type": "string", "description": "Shipping city." }, "shipping_state": { "type": "string", "description": "Shipping state.\n \nFormat: `CC`" }, "shipping_zip": { "type": "string", "description": "Shipping zip code." }, "shipping_country": { "type": "string", "description": "Shipping country. *Country codes are as shown in ISO 3166-1 alpha-2*.\n \nFormat: `CC`" }, "shipping_email": { "type": "string", "description": "Shipping email address." }, "merchant_defined_field_1": { "type": "string", "description": "Merchant defined field which can be set up in merchant control panel under Settings->Merchant Defined Fields. You can pass custom information in up to 20 fields.\n\nFormat: `merchant_defined_field_1=Value1`, `merchant_defined_field_2=Value2`, etc..." } } }, { "$ref": "#/components/schemas/ProductInformation" } ] }, "SendInvoice": { "title": "Send Invoice", "allOf": [ { "required": [ "invoicing", "invoice_id", "security_key" ] }, { "type": "object", "properties": { "security_key": { "$ref": "#/components/schemas/SecurityKey" }, "invoicing": { "type": "string", "enum": [ "send_invoice" ], "description": "Send an existing invoice to a customer." }, "invoice_id": { "type": "string", "description": "The invoice ID to be emailed." } } } ] }, "CloseInvoice": { "title": "Close Invoice", "allOf": [ { "required": [ "invoicing", "invoice_id", "security_key" ] }, { "type": "object", "properties": { "security_key": { "$ref": "#/components/schemas/SecurityKey" }, "invoicing": { "type": "string", "enum": [ "close_invoice" ], "description": "The invoice to be closed." }, "invoice_id": { "type": "string", "description": "The invoice ID to be closed." } } } ] }, "Response": { "type": "object", "title": "Response", "properties": { "response": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Status code for the operation. (1) - success, (2) - failed, (3) system error" }, "responsetext": { "type": "string", "description": "Textual description of the operation's result." }, "authcode": { "type": "string", "description": "Authorization code for the operation." }, "amount_authorized": { "type": "string", "description": "(Conditional) This will optionally come back when requesting partial payment. Authorization amount." }, "transactionid": { "type": "string", "description": "(Conditional - Payment) Payment gateway transaction id." }, "invoice_id": { "type": "string", "description": "(Conditional - Invoice) Identifier for the invoice." }, "avsresponse": { "type": "string", "description": "Address Verification Service response code." }, "cvvresponse": { "type": "string", "description": "Card Verification Value response." }, "orderid": { "type": "string", "description": "Identifier for an order related to this invoice." }, "type": { "type": "string", "enum": [ "sale", "auth", "validate", "credit", "offline", "capture", "void", "refund", "complete_partial_payment", "add_invoice", "update_invoice", "send_invoice", "close_invoice", "add_plan", "edit_plan", "add_subscription", "" ], "description": "Type of operation that this response is for." }, "partial_payment_id": { "type": "string", "description": "(Conditional) This will optionally come back when requesting partial payment. A numeric identifier which is used when submitting subsequent transactions." }, "partial_payment_balance": { "type": "string", "description": "(Conditional) This will optionally come back when requesting partial payment. The payment's remaining balance." }, "platform_id": { "type": "string", "description": "Platform ID associated with the transaction." }, "response_code": { "type": "string", "description": "Another status or result code for the operation. See [Response Code Table](#section/Appendixes/Payment-API-Response-Codes)" }, "subscription_id": { "type": "string", "description": "(Conditional - Subscription) The subscription ID that was created" }, "emv_auth_response_data": { "type": "string", "description": "(Conditional) This will optionally come back when any chip card data is provided on the authorization. This data needs to be sent back to the SDK after an authorization." }, "payment_terms": { "type": "string", "description": "(Conditional - Invoice) The terms of payment for the invoice." }, "customer_vault_id": { "type": "string", "description": "(Conditional - Customer Vault) The original customer_vault_id passed in the transaction request or the resulting customer_vault_id created on an approved transaction.\n\nNote: Only returned when the \"Customer Vault\" service is active." }, "kount_score": { "type": "string", "description": "The Kount \"Omniscore\" indicating the level of risk on a given transaction. The higher the score, the lower the risk.\n\nNote: Only returned when the \"Kount\" service is active." } } } }, "examples": { "CreateInvoice": { "summary": "Create Invoice", "description": "Create Invoice for test@example.com ($1.0)", "value": { "invoicing": "add_invoice", "amount": "1.0", "email": "test@example.com", "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm" } }, "UpdateInvoice": { "summary": "Update Invoice", "description": "Change amount to $2.0", "value": { "invoicing": "update_invoice", "invoice_id": "8543919398", "amount": "2.0", "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm" } }, "SendInvoice": { "summary": "Send Invoice", "description": "Send the given invoice to a billing email", "value": { "invoicing": "send_invoice", "invoice_id": "8543919398", "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm" } }, "CloseInvoice": { "summary": "Close Invoice", "description": "Close the given invoice", "value": { "invoicing": "close_invoice", "invoice_id": "8543919398", "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm" } }, "InvoiceCreated": { "summary": "Invoice Created", "description": "Invoice has been created successfully", "value": { "response": "1", "responsetext": "Invoice Sent To test@example.com", "authcode": "", "invoice_id": "8543919398", "avsresponse": "", "cvvresponse": "", "orderid": "", "type": "add_invoice", "response_code": "100", "payment_terms": "Due Upon Receipt" } }, "InvoiceUpdated": { "summary": "Invoice Updated", "description": "Invoice has been updated successfully", "value": { "response": "1", "responsetext": "Invoice Updated Successfully", "authcode": "", "invoice_id": "8543919398", "avsresponse": "", "cvvresponse": "", "orderid": "", "type": "update_invoice", "response_code": "100", "payment_terms": "Due Upon Receipt" } }, "InvoiceSent": { "summary": "Invoice Sent", "description": "Invoice has been sent successfully", "value": { "response": "1", "responsetext": "Invoice Sent To test@example.com", "authcode": "", "invoice_id": "8543919398", "avsresponse": "", "cvvresponse": "", "orderid": "", "type": "send_invoice", "response_code": "100" } }, "InvoiceClosed": { "summary": "Invoice Closed", "description": "Invoice has been closed successfully", "value": { "response": "1", "responsetext": "Invoice Closed Successfully", "authcode": "", "invoice_id": "8543919398", "avsresponse": "", "cvvresponse": "", "orderid": "", "type": "close_invoice", "response_code": "100" } }, "InvoiceClosedAlready": { "summary": "Error - Invoice Closed Already", "description": "[ERROR] Invoice is Closed already", "value": { "response": "3", "responsetext": "Invoice is already closed. REFID:1122290008", "authcode": "", "invoice_id": "8543919398", "avsresponse": "", "cvvresponse": "", "orderid": "", "type": "close_invoice", "response_code": "300" } }, "DeclinedResponse": { "summary": "Failed to Create Plan", "description": "Failed to create a new plan", "value": { "response": "3", "responsetext": "There is already a plan using the SKU you have specified. REFID:1203610329", "authcode": "", "transactionid": "", "avsresponse": "", "cvvresponse": "", "orderid": "", "type": "", "response_code": "100" } } } } true
Published operation notes
Additional operation-specific source notes, including legacy outcome tables where published. Read alongside the family guidance above; source marketing claims are not compliance guarantees. <details> <summary>Methodology</summary> **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. </details> <details> <summary>Click to see invoice related notes</summary> **Update Invoice** All variables (besides currency) on an invoice may be updated. Updating an invoice will not result in a new invoice being sent to the customer. **Send Invoice** To send the invoice after updating an invoice, use the send_invoice request after making changes. </details> <details> <summary>Response Code Table</summary> | Code | Description | |:------|:-------------------------------------------------------------------| | 100 | Transaction was approved. | | 200 | Transaction was declined by processor. | | 201 | Do not honor. | | 202 | Insufficient funds. | | 203 | Over limit. | | 204 | Transaction not allowed. | | 220 | Incorrect payment information. | | 221 | No such card issuer. | | 222 | No card number on file with issuer. | | 223 | Expired card. | | 224 | Invalid expiration date. | | 225 | Invalid card security code. | | 226 | Invalid PIN. | | 240 | Call issuer for further information. | | 250 | Pick up card. | | 251 | Lost card. | | 252 | Stolen card. | | 253 | Fraudulent card. | | 260 | Declined with further instructions available. (See response text) | | 261 | Declined-Stop all recurring payments. | | 262 | Declined-Stop this recurring program. | | 263 | Declined-Update cardholder data available. | | 264 | Declined-Retry in a few days. | | 300 | Transaction was rejected by gateway. | | 400 | Transaction error returned by processor. | | 410 | Invalid merchant configuration. | | 411 | Merchant account is inactive. | | 420 | Communication error. | | 421 | Communication error with issuer. | | 430 | Duplicate transaction at processor. | | 440 | Processor format error. | | 441 | Invalid transaction information. | | 460 | Processor feature not available. | | 461 | Unsupported card type. | </details> true
Reconcile outcomes
Persist the returned transaction or object identifier and inspect the operation result before changing application state. Investigate interrupted financial responses before retrying. Saved methods, invoice delivery, schedules and refunds have different side effects; select the corresponding variant explicitly. Account and processor behavior have not been executed in this audit.