Build your first sandbox checkout
Create the browser-to-server token flow and verify a first payment without moving money.
Follow the first-payment path
Build the basic online flow in this order. The checkout and server guides contain the implementation details; the recipe brings the request and expected outcome together. Complete the test matrix before moving to launch preparation. 1. Choose an SDK or library 2. Configure sandbox keys 3. Build the checkout 4. Connect your server 5. Run the first-payment recipe 6. Test and prepare to launch
Prepare the sandbox account
Obtain sandbox merchant access and the associated public tokenization key and private API key. A sandbox account is already in test mode. Do not use real cards, bank details or production secrets. The online sale endpoint in this guide is https://sandbox.nmi.com/api/v5/payments/sale. Confirm your intended merchant and enabled payment methods. Read the public tokenization key from Merchant Keys in the sandbox key-management screen. Inject the private key into server-only configuration. Create an order in your application with a fixed sandbox amount such as 10.00. Create an NMI sandbox account Key and environment setup A development frontend with a package manager and an application server that can make HTTPS requests. Access to the sandbox merchant’s public tokenization and private API credentials. A server-owned test order and a way to persist its payment attempt and gateway transaction ID. No production card data or production keys in this flow.
Install and connect
Use the React package for a React checkout, or the vanilla JavaScript package for a framework-independent implementation. These are NMI packages; there is no separate Betterpay SDK in this integration. npm install @nmipayments/nmi-pay-react # Alternative for a non-React integration: # npm install @nmipayments/nmi-pay
Complete the first round trip
Mount NmiPayments with tokenizationKey and an onPay handler. Send event.token and your order identifier to your own authenticated server route. The server loads the order amount and sends payment_details.payment_token in the NMI JSON request. Return a normalized outcome to the browser; onPay expects true for success or a displayable string for an error. online Use the test Visa 4111111111111111 and expiry 10/29 in the hosted fields. Submit a 10.00 sandbox order and inspect both HTTP status and the gateway response field. Persist the returned transaction id against the order before showing confirmation. Verify that refreshing the result page reads your stored state instead of creating another sale.
Know when the milestone is complete
An HTTP 200 by itself is not sufficient payment approval. NMI’s component examples check response equal to "1". A successful checkout is also not a settlement or funding guarantee. Keep your order state separate from gateway settlement and processor deposits. Observation Expected evidence Approved sale Gateway response "1", transaction id saved, order linked Declined sale Customer sees a clear message; order remains unpaid Lost network response Order remains uncertain until investigated; no automatic duplicate sale Secret inspection No private API key in the frontend bundle or browser requests
Recognize an approved response
The response below is an abbreviated illustrative shape, not an executed test result. Read the real response from your account: approval requires both a successful HTTP response and the gateway approval result. Keep the transaction ID with your order; pending settlement does not mean funds have been deposited. { "id": "<gateway-transaction-id>", "response": "1", "response_code": "100", "status": "pendingsettlement" } Sale response and fields First-payment recipe
Extend only after the base flow works
Next, run the sandbox test matrix, then choose saved methods, recurring billing or wallet support. Switching to production requires the correct live merchant configuration and both production keys, not just replacing the hostname. Betterpay coordinates merchant approval and provisioning.
Troubleshoot the first attempt
Locate the failing stage before changing the implementation. Avoid repeated charges while diagnosing an ambiguous response. Symptom Check next Fields do not initialize Correct public tokenization key, package import and browser console/network errors No token reaches the server onPay or onChange is wired; complete state is true for a custom submit flow Authentication fails Matching sandbox merchant/private key; Authorization contains the key without Bearer Validation error JSON shape, amount and payment_details.payment_token mapping HTTP success but payment declined Gateway response and response_text; do not equate HTTP 200 with approval Request timed out Keep the attempt uncertain and reconcile before submitting again Authentication details Diagnose errors and uncertainty