Merchant onboarding
Separate merchant approval from payment integration, and connect application progress to your platform.
Choose the account route
The Merchant Sign-Up API serves enabled NMI Payments partners. It handles applications and underwriting; it is separate from taking a payment. An existing merchant account can instead require gateway boarding through Account Management. Confirm the Betterpay program and credentials before building the application flow. A successful application submission does not mean the merchant is approved or ready to process.
Build the application journey
Use the package returned for your program to determine application fields and validation. Collections represent repeated information such as owners or bank accounts. Configure a webhook subscription for application updates. Retrieve packages and the selected package’s fields and rules. Create the application and retain its application ID on your server. Collect required information, update the application, and complete legal consent. Submit the application, then process approval, decline, or additional-information events.
Submit for review
The sandbox submission operation requires applications:write. The application identifier uses app_ followed by 16 hexadecimal characters. Supply a unique Idempotency-Key of 10–100 characters for a logical write and reuse it for a retry of that same write. POST https://sandbox.signup.nmi.com/api/v1/applications/{application}/submit Authorization: Bearer <access-token> Idempotency-Key: <unique-request-id> Result Interpretation 200 Application submitted; initial state is submitted. 404 Application resource was not found. 422 Correct validation issues before submitting again.
Exercise sandbox decisions
Sandbox decisions are simulated using fld_monthly_volume. These thresholds are test behavior, not underwriting policy for real merchants. Monthly volume Simulated event Below $5,000 application.declined $5,000–$99,999 application.approved $100,000 or more application.updated.data.requested
Keep your platform state separate
Recommended application design: store your own tenant ID, the external application ID, last verified status, and event-processing timestamp together. Restrict access to application data by tenant and staff role. Show a review-pending screen after submission; offer a clear way to supply missing information rather than opening payment features immediately. Keep personal application data out of ordinary request logs. Make webhook processing safe when an event is delivered again. Record which application step failed so users can resume without repeating completed steps. Enable processing only after the account has the required approval and configuration.