--- title: NMI API Integration on Truto slug: nmi category: Payment Gateway canonical: "https://truto.one/integrations/detail/nmi/" --- # NMI API Integration on Truto **Category:** Payment Gateway **Status:** Beta ## MCP-ready AI tools Truto exposes 68 tools for NMI that AI agents can call directly. - **nmi_payments_sale** — Process a sale transaction in NMI — an authorization and capture in a single step. Pay with raw card details, an ACH bank account, a Collect.js payment_token, or a stored customer via customer_vault_id. Amounts are decimal strings (e.g. 10.00). Returns the transaction result including id, status, response (1 approved / 2 declined / 3 error), auth_code and response_text. Required: amount and a payment_details variant. - **nmi_payments_auth** — Process an authorization for a payment in NMI, to be used in conjunction with the capture endpoint to prepare the payment for settlement. Returns: transaction_id, condition, transaction_type, requested_amount, currency, authorization_code. - **nmi_payments_credit** — Process a credit in NMI without a prior payment, crediting funds directly to the customer's payment method. Returns: merchant, features, transaction_id, transaction_type, condition, processor_id, ponumber, order_description, order_id, customerid, customertaxid, website, shipping, currency, tax, surcharge, convenience_fee, misc_fee, misc_fee_name, cash_discount, tip, requested_amount,… - **nmi_payments_validate** — Validate a payment method in NMI without processing a payment. Returns the validation result including transaction_id, transaction_type, condition, response_code, and response_text. - **nmi_payments_capture** — Capture a previously authorized payment in NMI. Returns the transaction object including transaction_id, condition, currency, requested_amount, and an action block with amount, action_type, success, response_code, and response_text. Required: payment_id. - **nmi_payments_void** — Void an unsettled NMI payment. Returns the transaction object including transaction_id, condition, transaction_type, requested_amount, currency, card, and action. Required: payment_id. Only payments that have not yet been settled can be voided; send an empty JSON body when no void_reason applies. - **nmi_payments_refund** — Refund a previously settled NMI payment back to the customer's payment method. Returns: transaction_id, condition, amount. Required: payment_id. Only settled transactions can be refunded. - **get_single_nmi_payment_by_id** — Get a specific NMI payment by payment ID. Returns: transaction_id, transaction_type, condition, currency, requested_amount, billing_address, card, and action details. Required: id. - **create_a_nmi_invoice** — Create a new invoice in NMI and email it to the customer. Returns the created invoice object including its id. A JSON request body is required. - **list_all_nmi_invoices** — List all invoices for the merchant in NMI with optional filtering. Returns a collection of invoices including id, created_at, and updated_at for each record. Supports pagination. - **get_single_nmi_invoice_by_id** — Get a specific NMI invoice by id. Returns the invoice object including its id and currency. Required: id. - **update_a_nmi_invoice_by_id** — Update an existing NMI invoice by id. All variables besides currency may be updated; updating does not resend the invoice to the customer. Returns: id, currency, created_at, updated_at. Required: id. - **nmi_invoices_close** — Close an existing NMI invoice by invoice_id. Once closed, the invoice cannot be modified or paid. Returns: id, currency, created_at, updated_at. Required: invoice_id. - **nmi_invoices_send** — Email an existing NMI invoice to the customer. Takes no request body — send an empty JSON object. The invoice is addressed via the invoice_id parameter, and the email goes to the address on the invoice's billing contact. Returns the Invoice object. Required: invoice_id. - **create_a_nmi_subscription** — Create a recurring subscription in NMI. Attach the subscription to an existing plan via plan_id, or define the schedule inline with a plan object (amount plus day_frequency, or month_frequency with day_of_month). Pay with a stored customer (customer_vault_id in payment_details), raw card, ACH or payment_token. Returns the created Subscription including subscription_id and next_charge_date. Required: a plan reference and a payment_details variant. - **list_all_nmi_subscriptions** — List all NMI webhook subscriptions. Returns: id, callback_url, status, events, created_at, updated_at. Max 100 per page. - **get_single_nmi_subscription_by_id** — Get a specific webhook subscription in NMI by id. Returns the subscription object including its id, callback_url, status, events, created_at, and updated_at. Required: id. - **update_a_nmi_subscription_by_id** — Update an existing NMI subscription by id, modifying the subscribed events list or callback URL. Returns the updated subscription object including id, callback_url, events, status, created_at, and updated_at. Required: id. - **delete_a_nmi_subscription_by_id** — Delete an NMI subscription by id. The customer will no longer be charged. Returns: code, message. Required: id. - **create_a_nmi_plan** — Create a new recurring payment plan in NMI. Plans define recurring billing schedules that subscriptions can be associated with. Returns: id, name, amount, day_frequency, payments, month_frequency, day_of_month. Required: id, name, amount. - **list_all_nmi_plans** — List all recurring payment plans in NMI. Returns each plan's id, name, amount, day_frequency, payments, month_frequency, and day_of_month. Max 100 per page. - **get_single_nmi_plan_by_id** — Get a specific NMI recurring payment plan by id. Returns: id, name, amount, day_frequency, payments, month_frequency, day_of_month. Required: id. - **update_a_nmi_plan_by_id** — Update an existing NMI recurring payment plan. Returns the updated plan including id, name, amount, day_frequency, month_frequency, day_of_month, and payments. Required: id. Exercise caution — all customers subscribed to this plan will have their billing changed based on your edits. - **delete_a_nmi_plan_by_id** — Delete an NMI recurring payment plan by id. Returns an empty 204 response on success. Required: id. - **create_a_nmi_customer** — Create a customer in the NMI Customer Vault with one or more billing addresses and stored payment methods (card, ACH or Collect.js payment_token). Returns the created Customer including the vault id used for later charges. Required: billing (with payment_details). - **list_all_nmi_customers** — List customers stored in the NMI Customer Vault. Filter by customer vault id (exact or partial), name, company, email, billing or shipping address id, payment account number, creation date range, or expiring cards. Returns Customer objects with their billing and shipping addresses. - **get_single_nmi_customer_by_id** — Get a single NMI customer from the Customer Vault by id. Returns the customer record including its customer vault id, billing addresses, and associated payment method details. Required: id. - **update_a_nmi_customer_by_id** — Update an existing NMI customer in the customer vault, including bulk updates of billing and shipping addresses. Returns: customer_vault_id, billing, shipping. Required: id. All provided billing and shipping addresses will be updated. - **delete_a_nmi_customer_by_id** — Delete a customer from the NMI customer vault by id. This removes the customer and all associated billing and shipping addresses. Returns an empty 204 response on success. Required: id. - **create_a_nmi_billing_address** — Add a new billing address to an existing NMI customer vault record. Returns the customer object including the billing address with first_name, last_name, address_1, city, state, postal_code, and country. Required: customer_id. - **get_single_nmi_billing_address_by_id** — Retrieve a specific billing address for an NMI customer vault customer. Returns: id, first_name, last_name, address_1, address_2, company, city, state, postal_code, country, email, phone, cell_phone, fax. Required: customer_id, id. - **update_a_nmi_billing_address_by_id** — Update an existing billing address for an NMI customer. Returns the updated billing address including first_name, last_name, address_1, city, state, postal_code, country, email, and phone. Required: customer_id, id. - **delete_a_nmi_billing_address_by_id** — Delete a billing address from an NMI customer. The customer must retain at least one billing address after deletion. Returns an empty 204 response on success. Required: customer_id, id. - **create_a_nmi_shipping_address** — Add a shipping address to an existing NMI Customer Vault customer. All address fields are optional strings. Returns the created shipping address including its id. Required: customer_id. - **get_single_nmi_shipping_address_by_id** — Get a specific NMI customer shipping address by id. Returns: id, first_name, last_name, address_1, address_2, company, city, state, postal_code, country, email, phone, fax. Required: customer_id, id. - **update_a_nmi_shipping_address_by_id** — Update an existing shipping address for an NMI customer. Returns the updated shipping address object including its id. Required: customer_id, id. - **delete_a_nmi_shipping_address_by_id** — Delete a shipping address from an NMI customer. Returns an empty 204 response on success. Required: customer_id, id. - **create_a_nmi_product** — Create a product in the NMI product catalog, identified by a unique SKU, with cost, currency, optional category, tax/discount amounts and an optional base64 image. Returns the created Product. Required: product_sku, product_description, product_cost, product_currency. - **list_all_nmi_products** — List all products in NMI's Product Manager. Returns a list of product records including id, created_at, and updated_at. - **get_single_nmi_product_by_id** — Get a single NMI product by id (SKU) from the Product Manager. Returns: id. Required: id. - **update_a_nmi_product_by_id** — Update an existing product in the NMI Product Manager by id. Products can be used in invoices and other payment flows. Returns the updated product object. Required: id. - **delete_a_nmi_product_by_id** — Delete an NMI product from the Product Manager by id. Returns an empty 204 response on success. Required: id. - **create_a_nmi_embedded_component_session** — Create a short-lived session token for NMI embedded components that can be used to authenticate and fetch data. Returns: session_token, expires_at. The optional body accepts either gateway credentials (api_key, merchant_id) or merchant-central credentials (api_key, tenant_id, merchant_id). - **list_all_nmi_affiliates** — List sub-affiliate accounts under your NMI partner account. Returns: objectType, id, firstName, lastName, company, email, replyToEmail, phone, fax, url, address1, address2, city, state, zip, country, timezone, features, status, created, updated, parentAffiliateId, support, branding, accountInfo, billTo, rejectedCertificates. - **create_a_nmi_merchant** — Create a merchant account under your NMI partner account (v4 partner API). Field names are camelCase. Requires company and primary contact details, address, timezone, language, a username for the merchant's primary user, and accountInfo with the bank account used to bill the merchant. Returns the created Merchant object. Required: type, company, country, address1, city, state, zip, timezone, firstName, lastName, email, phone, language, username, accountInfo. - **list_all_nmi_merchants** — List all merchant accounts under your NMI partner account. Returns merchant records including id, company, email, status, type, created, and updated. The type filter accepts only gateway, test, splitFunding, or mobile. - **get_single_nmi_merchant_by_id** — Get all details of a specific NMI merchant account by id. Returns: objectType, id, type, created, updated, firstName, lastName, company, email, phone, fax, url, address1, address2, city, state, zip, country, timezone, costPlan, status, externalIdentifier, lastTransactionDate, parentAffiliateId, accountInfo, features, needsPendingServicesActivated, payFacBillingPeriod, rejectedCertificates.… - **update_a_nmi_merchant_by_id** — Update an NMI merchant by id — this PATCH endpoint supports three operations: assign a fee schedule, complete & send the welcome email, or agree to TOS and fees. Returns: objectType, id, type, created, updated, firstName, lastName, company, email, phone, fax, url, address1, address2, city, state, zip, country, timezone, costPlan, status, externalIdentifier, lastTransactionDate, parentAffiliateId,… - **nmi_fee_schedules_get_fees** — List all fees currently set on an existing NMI fee schedule. Returns each fee's objectType, feeType, name, sort, description, processor details, billMe flag, value, and applyTo targets. Required: fee_schedule_id. - **list_all_nmi_fee_schedules** — Search all fee schedules available on your NMI account. Returns a list of fee schedule records including id, name, costPlan, currency, merchants, affiliates, isDefault, and isCustom. Required: maxResults (1-1000). Optionally filter by parentAffiliateId to narrow results to a specific affiliate's fee schedules. - **create_a_nmi_ctv_onboarding** — Add (or upgrade) Customer Token Vault to an NMI gateway account. Returns per-network onboarding results including requestStatus, requestStatusCode, onboardStatus, and onboardId for each card network. Required: merchantId, applications. If upgrading from Customer Vault to Customer Token Vault, the old vault extension does not need to be disabled first. - **nmi_signup_auth_get_token** — Request an OAuth access token from NMI using the client_credentials grant. Returns: access_token, token_type, expires_in. Required: grant_type, client_id, client_secret. The token is valid for 60 minutes. - **list_all_nmi_packages** — List all available application packages in NMI. Returns: id, name, description. - **get_single_nmi_package_by_id** — Get a single NMI application package by id, including the full package rules, field definitions, and collections required for creating an application. Returns: id, name, description, package_rules, fields, collections. Required: id. - **list_all_nmi_applications** — List NMI merchant applications with optional filtering by status, date range, package, and sort direction. Returns: id, package_id, status, created_at, updated_at. - **create_a_nmi_application** — Create a new NMI merchant application with a package, fields, and collections. Returns the full application object including id, package_id, status, fields, collections, created_at, and updated_at. Required: package_id. - **get_single_nmi_application_by_id** — Get a single NMI merchant application by id. Returns the full application object including id, package_id, status, fields, collections, created_at, and updated_at. Required: id. - **update_a_nmi_application_by_id** — Partially update an NMI merchant application by id with fields and collections. An application can only be updated when it is in draft status. Returns the full application object including id, package_id, status, fields, collections, created_at, and updated_at. Required: id. - **nmi_applications_submit** — Submit an NMI merchant application for underwriting review. Returns the full application object including id, package_id, status, fields, collections, created_at, and updated_at. Required: application. - **nmi_applications_upload_document** — Upload a supporting document to an NMI merchant application. Returns the uploaded document object including its id, type, and created_at. Required: application, type, file. Documents can only be uploaded while the application is in draft or underwriter_requested_information status; accepted file formats are PNG, JPG, JPEG, and PDF with a max size of 20 MB. - **nmi_applications_get_legal_consent** — Get the legal consent URL for an NMI merchant application. The returned url is used with the Embed Helper to embed the legal consent widget so the applicant can review and accept the legal terms. Required: application (the application ID, e.g. app_341c7b5b432a3158). - **nmi_applications_download_agreement** — Download the signed agreement PDF for an NMI application. Returns the agreement as a binary PDF file (application/octet-stream, max 100 MB). The agreement can only be downloaded after the application has been submitted. Required: application. - **nmi_applications_update_info** — Add additional information to an NMI application that is in the underwriter_requested_information status. Returns: code, message. Required: application, note. - **list_all_nmi_webhook_subscriptions** — List all NMI webhook subscriptions. Returns: id, callback_url, status, events, created_at, updated_at. - **create_a_nmi_webhook_subscription** — Create a new NMI webhook subscription with a callback URL, signing secret, and list of events. Returns the created subscription including id, callback_url, events, status, created_at, and updated_at. Required: callback_url, secret, events. - **get_single_nmi_webhook_subscription_by_id** — Get a single NMI webhook subscription by id. Returns: id, callback_url, status, events, created_at, updated_at. Required: id. - **update_a_nmi_webhook_subscription_by_id** — Update an NMI webhook subscription's subscribed events list or callback URL. Returns the updated subscription object including id, callback_url, events, status, and created_at. Required: id. - **delete_a_nmi_webhook_subscription_by_id** — Delete an NMI webhook subscription by id. Returns: code, message. Required: id. ## How it works 1. **Link your customer's NMI account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach NMI.** The Proxy API is a 1-to-1 mapping of the NMI API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed native payment acceptance in your SaaS** — Let your users charge their customers directly inside your product using saved cards, one-time sales, or authorization holds — without your platform ever touching raw card data or entering PCI scope. - **Automate merchant onboarding for PayFac and ISV models** — If you're acting as a payment facilitator or ISO, programmatically board sub-merchants by submitting applications, uploading KYC documents, and capturing legal consent so new users can start accepting payments the same day they sign up. - **Power recurring billing for subscription businesses** — Vertical SaaS platforms (gyms, memberships, SaaS-for-SaaS) can map their internal pricing tiers to NMI plans and subscriptions so end-user merchants can bill their own customers on a recurring schedule with zero manual work. - **Sync invoicing and A/R workflows** — Field service, professional services, and B2B platforms can generate invoices from work orders, email them to end customers via NMI, and reconcile paid status back into their own ledger through webhooks. - **Support delayed-capture and cancellation flows for B2B commerce** — ERPs and order management systems can authorize funds when an order is placed and only capture on shipment — or void the hold if the order is canceled — so your users' cash flow and accounting stay accurate automatically. ## What you can build - **Card-on-file charging with the NMI Customer Vault** — Create and manage customer records, billing addresses, and shipping addresses in NMI so your users can charge saved payment methods with a single click from your UI. - **Auth, capture, void, and refund controls in-app** — Expose a full transaction lifecycle — sale, auth, capture, void, refund, credit, and validate — inside your dashboard so merchants never leave your product to manage payments. - **Programmatic merchant application and underwriting flow** — Build a native onboarding wizard that constructs an NMI application, uploads supporting documents, presents legal consent, and submits to underwriting — all inside your signup experience. - **Subscription and plan management UI** — Let merchants create plans, start and cancel subscriptions, and update billing details for their own customers directly from your interface, backed by NMI's recurring billing engine. - **Invoice generation and delivery** — Create invoices, send them to end customers via NMI's email delivery, and close them out when paid — perfect for field service, healthcare, and B2B workflows. - **Event-driven payment sync via webhooks** — Register webhook subscriptions programmatically so your platform reacts in real time to successful sales, failed recurring charges, invoice payments, and application status changes. ## FAQs ### How does authentication work with NMI through Truto? NMI uses API key–based authentication (security keys issued per merchant account or partner). Truto handles credential storage and injection so your end users connect their NMI account once and your platform can call the API on their behalf without you managing secrets. ### Do we need to be PCI compliant to charge cards through NMI? No. NMI's tokenization (Collect.js) and Customer Vault let you exchange raw card data for tokens on the client side, and Truto's API calls only pass tokens or vault IDs. Your servers never see PAN data, keeping you out of PCI scope. ### Can we onboard merchants (PayFac / ISO model) programmatically? Yes. The integration supports the full boarding flow: creating an application, uploading documents, retrieving legal consent, submitting to underwriting, and downloading signed agreements — so you can board sub-merchants without leaving your product. ### What payment operations are supported? Sale, auth, capture, void, refund, credit, and validate are all available, plus fetching a single transaction by ID. This covers both single-step (immediate charge) and dual-step (auth-then-capture) flows. ### How do we get real-time updates on payments and subscriptions? You can create, list, update, and delete NMI webhook subscriptions through the integration. Register endpoints to receive events for transaction outcomes, subscription lifecycle changes, invoice payments, and application status updates. ### Can a single integration support multiple merchants under our platform? Yes. NMI is built for partner hierarchies — you can list affiliates, create and manage merchants, view fee schedules, and manage packages, which lets your SaaS scale to many end-user merchants under one integration. ## Related reading - [Connect NMI to ChatGPT: Handle Payments and Recurring Billing](https://truto.one/blog/connect-nmi-to-chatgpt-handle-payments-and-recurring-billing/) — Learn how to connect NMI to ChatGPT using a managed MCP server. Automate payments, recurring billing, and customer vault operations with AI agents. - [Connect NMI to Claude: Streamline Merchant Apps & Payments](https://truto.one/blog/connect-nmi-to-claude-streamline-merchant-apps-and-onboarding/) — Learn how to connect NMI to Claude using a managed MCP server. Automate merchant onboarding, payment processing, and subscription recovery workflows. - [Connect NMI to AI Agents: Automate Invoicing and Customer Vaults](https://truto.one/blog/connect-nmi-to-ai-agents-automate-invoicing-and-customer-vaults/) — Learn how to connect NMI to AI agents using Truto's /tools endpoint. Fetch tools, bind them via LangChain, and automate complex payment and invoicing workflows.