---
updatedAt: 2026-09-02T15:10:31.000Z
agentTools:
  projectIndex: https://docs.nmi.com/llms.txt
---

# Product Management

> This documentation is intended for existing Classic API integrations. For new integrations, use the [Payment Component](../docs/payment-component) with the [REST API](../reference/create-sale-v5). If you're migrating from the Classic API, follow the [Classic API migration playbook](../docs/payment-migration-playbook).
<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>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>

<div class="alert alert-blue">
  ### **Never Use Real API Keys**

Use Sandbox keys with the Try It feature. Do not enter production API keys when testing.

</div>

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "Payments",
    "x-logo": {
      "url": "https://www.nmi.com/app/themes/nmi/images/NMI_Logo_Primary.webp"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.nmi.com/api"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Products",
      "description": "Product catalog management with image support and inventory tracking"
    }
  ],
  "externalDocs": {
    "url": "https://www.postman.com/nmi-integration-support/workspace/nmi-public-documentation/request/5480015-f4b0ec7b-bd84-4094-98c2-67c0b6508a7f",
    "description": "Public Documentation (Postman)"
  },
  "paths": {
    "/transact.php": {
      "post": {
        "tags": [
          "Products"
        ],
        "summary": "Product Management",
        "description": "<details>\n<summary>Methodology</summary>\n\n**Steps:**\n1. The customer sends their payment information to the merchant's web site.\n2. The merchant web site posts the payment data to the Payment Gateway.\n3. The Payment Gateway responds immediately with the results of the transactions.\n4. The merchant web site displays the appropriate message to the customer.\n\nThe communication method used to send messages to the Payment Gateway's server is the standard HTTP protocol over an SSL connection.\n\nIn 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.\n\nIn 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.\n\nIn 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`\n\n### Customer Vault\nThe 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.\n\nThese 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.\n\nThe 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.\n</details>\n\n<details>\n<summary>Response Code Table</summary>\n\n| Code  | Description                                                        |\n|:------|:-------------------------------------------------------------------|\n| 100   | Transaction was approved.                                          |\n| 200   | Transaction was declined by processor.                             |\n| 201   | Do not honor.                                                      |\n| 202   | Insufficient funds.                                                |\n| 203   | Over limit.                                                        |\n| 204   | Transaction not allowed.                                           |\n| 220   | Incorrect payment information.                                     |\n| 221   | No such card issuer.                                               |\n| 222   | No card number on file with issuer.                                |\n| 223   | Expired card.                                                      |\n| 224   | Invalid expiration date.                                           |\n| 225   | Invalid card security code.                                        |\n| 226   | Invalid PIN.                                                       |\n| 240   | Call issuer for further information.                               |\n| 250   | Pick up card.                                                      |\n| 251   | Lost card.                                                         |\n| 252   | Stolen card.                                                       |\n| 253   | Fraudulent card.                                                   |\n| 260   | Declined with further instructions available. (See response text)  |\n| 261   | Declined-Stop all recurring payments.                              |\n| 262   | Declined-Stop this recurring program.                              |\n| 263   | Declined-Update cardholder data available.                         |\n| 264   | Declined-Retry in a few days.                                      |\n| 300   | Transaction was rejected by gateway.                               |\n| 400   | Transaction error returned by processor.                           |\n| 410   | Invalid merchant configuration.                                    |\n| 411   | Merchant account is inactive.                                      |\n| 420   | Communication error.                                               |\n| 421   | Communication error with issuer.                                   |\n| 430   | Duplicate transaction at processor.                                |\n| 440   | Processor format error.                                            |\n| 441   | Invalid transaction information.                                   |\n| 460   | Processor feature not available.                                   |\n| 461   | Unsupported card type.                                             |\n\n</details>",
        "operationId": "manageProducts",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/AddProductRequest"
                  },
                  {
                    "$ref": "#/components/schemas/UpdateProductRequest"
                  },
                  {
                    "$ref": "#/components/schemas/DeleteProductRequest"
                  }
                ]
              },
              "examples": {
                "Add Product": {
                  "$ref": "#/components/examples/AddProduct"
                },
                "Add Product With Image": {
                  "$ref": "#/components/examples/AddProductWithImage"
                },
                "Update Product": {
                  "$ref": "#/components/examples/UpdateProduct"
                },
                "Update Product Image": {
                  "$ref": "#/components/examples/UpdateProductImage"
                },
                "Delete Product": {
                  "$ref": "#/components/examples/DeleteProduct"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Product operation completed successfully",
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Response"
                    },
                    {
                      "$ref": "#/components/schemas/ProductResponse"
                    }
                  ]
                },
                "examples": {
                  "Product Added": {
                    "$ref": "#/components/examples/ProductAdded"
                  },
                  "Product Added Fail": {
                    "$ref": "#/components/examples/ProductAddedFail"
                  },
                  "Product Updated": {
                    "$ref": "#/components/examples/ProductUpdated"
                  },
                  "Product Update Failed": {
                    "$ref": "#/components/examples/ProductUpdatedFail"
                  },
                  "Product Deleted": {
                    "$ref": "#/components/examples/ProductDeleted"
                  },
                  "Declined Request": {
                    "$ref": "#/components/examples/DeclinedResponse"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "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"
      },
      "ProductCommon": {
        "type": "object",
        "properties": {
          "product_description": {
            "type": "string",
            "description": "The user-facing name of the product.\n\nExamples: `1 Gallon Milk` or `Phone Case`"
          },
          "product_cost": {
            "type": "number",
            "format": "float",
            "description": "The cost of the product before any tax or discounts.\n\nMust be greater than `0.00`"
          },
          "product_currency": {
            "type": "string",
            "enum": [
              "USD",
              "EUR"
            ],
            "description": "The currency for the product’s price."
          },
          "product_unit_of_measure": {
            "type": "string",
            "enum": [
              "NAR",
              "TDK",
              "MTQ"
            ],
            "description": "The unit of measure for the product. Default - `NAR`"
          },
          "product_tax_amount": {
            "type": "number",
            "format": "float",
            "description": "The tax that should be added to the product cost. This is a fixed amount, not a percentage.\nExample: `1.54`"
          },
          "product_discount_amount": {
            "type": "number",
            "format": "float",
            "description": "The discount that will subtracted from the cost of the product."
          },
          "product_image_data": {
            "type": "string",
            "description": "Image for the product, size must be 2MB or smaller.\n\nFormat: `base64 encoded JPG, PNG, or GIF`\n\n`Required` for image upload."
          },
          "product_image_name": {
            "type": "string",
            "description": "The file name of the image being added with product_image_data.\n\nExamples: `product.png` or `sku-1234.jpg`\n\n`Required` for image upload."
          }
        }
      },
      "AddProductRequest": {
        "title": "Add Product",
        "allOf": [
          {
            "type": "object",
            "required": [
              "products",
              "product_sku",
              "product_description",
              "product_cost",
              "product_currency",
              "security_key"
            ],
            "properties": {
              "security_key": {
                "$ref": "#/components/schemas/SecurityKey"
              },
              "products": {
                "type": "string",
                "enum": [
                  "add_product"
                ],
                "description": "Add a product to the Product Manager."
              },
              "product_sku": {
                "type": "string",
                "description": "The unique alpha-numeric SKU for this product. An error will be returned if the SKU is already in use by another product.\n\nExamples: `000001`"
              }
            }
          },
          {
            "$ref": "#/components/schemas/ProductCommon"
          }
        ]
      },
      "UpdateProductRequest": {
        "title": "Update Product",
        "allOf": [
          {
            "type": "object",
            "required": [
              "products",
              "product_id",
              "security_key"
            ],
            "properties": {
              "security_key": {
                "$ref": "#/components/schemas/SecurityKey"
              },
              "products": {
                "type": "string",
                "enum": [
                  "update_product"
                ],
                "description": "Update a product already in the Product Manager."
              },
              "product_id": {
                "type": "string",
                "description": "The automatically generated ID for the product. This was returned in the `add_product` API response, or can be found in the UI under the Product Details page in the Product Manager.\n\nExample: `5538585252`"
              }
            }
          },
          {
            "$ref": "#/components/schemas/ProductCommon"
          }
        ]
      },
      "DeleteProductRequest": {
        "title": "Delete Product",
        "allOf": [
          {
            "type": "object",
            "required": [
              "products",
              "product_id",
              "security_key"
            ],
            "properties": {
              "security_key": {
                "$ref": "#/components/schemas/SecurityKey"
              },
              "products": {
                "type": "string",
                "enum": [
                  "delete_product"
                ],
                "description": "Update a product already in the Product Manager."
              },
              "product_id": {
                "type": "string",
                "description": "The automatically generated ID for the product. This was returned in the `add_product` API response, or can be found in the UI under the Product Details page in the Product Manager.\n\nExample: `5538585252`"
              }
            }
          }
        ]
      },
      "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."
          }
        }
      },
      "ProductResponse": {
        "type": "object",
        "title": "Response - Products",
        "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."
          },
          "product_id": {
            "type": "string",
            "description": "Product ID."
          },
          "product_sku": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) The unique alpha-numeric SKU for this product."
          },
          "product_description": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) The user-facing name of the product."
          },
          "product_cost": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) The cost of the product before any tax or discounts."
          },
          "product_currency": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) The currency for the product’s price"
          },
          "product_commodity_code": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) Product commodity code."
          },
          "product_unit_of_measure": {
            "type": "string",
            "enum": [
              "NAR",
              "TDK",
              "MTQ"
            ],
            "description": "(Conditional - returned for create/update requests) The unit of measure for the product. Default - `NAR`"
          },
          "product_tax_amount": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) The tax that should be added to the product cost."
          },
          "product_discount_amount": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) The discount that will subtracted from the cost of the product."
          },
          "product_image_name": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) The file name of the image being added with product_image_data."
          },
          "product_category": {
            "type": "string",
            "description": "(Conditional - returned for create/update requests) Product category."
          }
        }
      }
    },
    "examples": {
      "AddProduct": {
        "summary": "Add Product",
        "description": "Add new product",
        "value": {
          "products": "add_product",
          "product_sku": "32463230005",
          "product_description": "Phone Case",
          "product_cost": 15.5,
          "product_currency": "USD",
          "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm"
        }
      },
      "AddProductWithImage": {
        "summary": "Add Product With Image",
        "description": "Add new product with image",
        "value": {
          "products": "add_product",
          "product_sku": "32463230005",
          "product_description": "Phone Case",
          "product_cost": 15.5,
          "product_currency": "USD",
          "product_image_data": "base64_encoded_content",
          "product_image_name": "product-123.png",
          "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm"
        }
      },
      "UpdateProduct": {
        "summary": "Update Product",
        "description": "Update product - set new description",
        "value": {
          "products": "update_product",
          "product_id": "5538585252",
          "description": "1 Gallon Milk",
          "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm"
        }
      },
      "UpdateProductImage": {
        "summary": "Update Product Image",
        "description": "Update product image",
        "value": {
          "products": "update_product",
          "product_id": "5538585252",
          "product_image_data": "base64_encoded_content",
          "product_image_name": "product-123.jpg",
          "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm"
        }
      },
      "DeleteProduct": {
        "summary": "Update Product",
        "description": "Update product - set new description",
        "value": {
          "products": "delete_product",
          "product_id": "5538585252",
          "security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm"
        }
      },
      "ProductAdded": {
        "summary": "Product Added",
        "description": "Product added successfully",
        "value": {
          "response": "1",
          "responsetext": "Product Added",
          "product_id": "8610653943",
          "product_sku": "32463230005",
          "product_description": "Phone Case",
          "product_cost": "15.50",
          "product_currency": "USD",
          "product_commodity_code": "",
          "product_unit_of_measure": "NAR",
          "product_tax_amount": "",
          "product_discount_amount": "",
          "product_image_name": "",
          "product_category": ""
        }
      },
      "ProductAddedFail": {
        "summary": "Product Added Fail",
        "description": "Product not added",
        "value": {
          "response": "3",
          "responsetext": "Product SKU, description, cost, and currency are required.\nREFID:1185534822",
          "authcode": "",
          "transactionid": "",
          "avsresponse": "",
          "cvvresponse": "",
          "orderid": "",
          "type": "",
          "response_code": "300"
        }
      },
      "ProductUpdated": {
        "summary": "Product Updated",
        "description": "Product updated successfully",
        "value": {
          "response": "1",
          "responsetext": "Product Updated",
          "product_id": "8610675975",
          "product_sku": "32463230006",
          "product_description": "1 Gallon Milk",
          "product_cost": "15.5000",
          "product_currency": "USD",
          "product_commodity_code": "",
          "product_unit_of_measure": "NAR",
          "product_tax_amount": "0.00",
          "product_discount_amount": "0.00",
          "product_image_name": "",
          "product_category": ""
        }
      },
      "ProductUpdatedFail": {
        "summary": "Product Update Failed",
        "description": "Product update failed",
        "value": {
          "response": "3",
          "responsetext": "Object not found REFID:1159407847",
          "authcode": "",
          "transactionid": "",
          "avsresponse": "",
          "cvvresponse": "",
          "orderid": "",
          "type": "",
          "response_code": "300"
        }
      },
      "ProductDeleted": {
        "summary": "Product Deleted",
        "description": "Product deleted successfully",
        "value": {
          "response": "1",
          "responsetext": "Product Deleted",
          "product_id": "8610675975"
        }
      },
      "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"
        }
      }
    }
  }
}
```