Save and charge a payment method
Store a tokenized method, retain its customer vault ID, and bill the correct customer later.
Distinguish the identifiers
A collection token is used for submitting payment details. A customer vault ID identifies a saved record. A transaction ID identifies a payment. Keep all three roles distinct; store a merchant-scoped mapping between your application customer and the saved vault record. Identifier Represents Use payment token Freshly collected payment details Submit or save the method customer vault ID Stored customer/payment record Reference the method for later billing transaction ID A specific payment operation Lookup, capture, void or refund as applicable
Save during a sale
With the customer’s agreement to save the method, collect a fresh token and submit a sale containing customer_vault.add_to_vault. A custom ID is optional; if omitted, NMI can assign one. Scope custom IDs to the merchant and avoid exposing personal data in identifiers. POST /api/v5/payments/sale HTTP/1.1 Host: sandbox.nmi.com Authorization: <sandbox-private-key> Content-Type: application/json { "amount": 10.00, "payment_details": { "payment_token": "<fresh-payment-token>" }, "customer_vault": { "add_to_vault": true, "id": "CUST-001" } }
Charge the saved customer
For a later authorized purchase, reference customer_vault.id instead of recollecting card details. The server must confirm that the current user and order are permitted to use that record. A vault ID arriving from the browser is not sufficient authorization. POST /api/v5/payments/sale HTTP/1.1 Host: sandbox.nmi.com Authorization: <sandbox-private-key> Content-Type: application/json { "amount": 25.50, "currency": "USD", "customer_vault": { "id": "CUST-001" } }
Manage the saved-method lifecycle
Saving a method does not establish consent for arbitrary future billing. Record the customer’s agreement and distinguish customer-initiated purchases from merchant-initiated recurring charges. Confirm credential-on-file and authentication requirements for the merchant’s region and processor. Confirm vault availability and choose a stable customer mapping. Record the scope of the customer’s consent and the intended future billing use. Store the returned vault ID only after checking the gateway result. Show an appropriate masked method description without retaining raw details. Define update, removal and subscription-cancellation behavior before exposing saved methods.
Handle failures and migrations
A saved record may later fail because a card expires, an issuer declines or account configuration changes. Collect an updated method through hosted fields rather than asking customers to send card details to support. Do not assume vault IDs or tokens can move between gateway accounts or providers without a coordinated migration.