Migrate Classic payments to REST
Reshape requests and response handling while preserving orders, tokens and transaction IDs.
Set the scope
The Classic DirectPost API uses /api/transact.php with a type form field. REST uses explicit /api/v5/payments paths and JSON. NMI states that existing Payment Component or Collect.js token creation can remain and that key permissions are inherited. Classic remains supported; this is a controlled server migration, not a requirement to replace every integration at once.
Map request fields and operations
Treat this as a schema migration. Do not merely change the URL and send the old form body. Classic REST Implementation change /api/transact.php + type=sale POST /api/v5/payments/sale Explicit operation path security_key in body Authorization header containing the key only No Bearer prefix payment_token payment_details.payment_token Nested JSON value firstname / lastname billing_address.first_name / last_name Nested address object transactionid response id in JSON response Persist canonical gateway ID type=capture + transactionid POST /api/v5/payments/{id}/capture ID in URL path Query-string response JSON plus HTTP status Replace parsing and error classification
Use the token sale as the first migration case
Keep the browser collection flow unchanged. Submit the same type of newly issued token through the REST adapter for a selected sandbox order. The JSON representation below is the replacement for a Classic token sale; send it to /api/v5/payments/sale with the private merchant Authorization header. { "amount": 10.00, "payment_details": { "payment_token": "<fresh-token>" }, "billing_address": { "first_name": "Test", "last_name": "Customer", "address1": "888", "zip": "77777", "country": "US" } }
Rewrite response handling before rollout
Keep gateway approval separate from HTTP success. REST error payloads can include type, error_code, message and details. Do not leave a Classic query-string parser in place. Preserve gateway transaction IDs so follow-on actions work for orders created before and after the switch. Normalize Classic and REST responses into one application payment record. Exercise approval, decline, validation error and uncertain response cases. Verify captures/refunds/lookups against the correct stored transaction IDs. Compare reconciliation totals for each merchant cohort. Keep routing per attempt immutable so a retry cannot accidentally switch APIs.
Roll out by merchant cohort
Recommended application approach: test in sandbox, deploy a disabled REST adapter, enable a small approved merchant cohort, reconcile, then expand. Rollback should change the route for new attempts only; it must not resubmit an uncertain payment. Provider-to-provider vault transfers, new merchant accounts and commercial conversion are separate workstreams and require explicit coordination. Do not dual-submit a real payment to compare Classic and REST. Compare controlled test fixtures and reconciled records instead.