Integrate Resolve checkout by creating a checkout session on your server and passing its short-lived reference to Resolve.js. Your backend controls the merchant, cart, items, total and return URLs; the browser opens that saved checkout in a modal or a full page.
Use checkout sessions for new custom integrations. Existing checkout-object integrations are documented in Legacy checkout.
- Set up your merchant credentials.
- Add Resolve.js.
- Create a session on your server.
- Open checkout in the browser.
- Handle buyer verification.
- Handle completion and capture.
- Test in sandbox.
- Enable Direct API and OAuth access for the merchant, and create an API access key with
merchant:write. Basic auth and read-only keys cannot create checkout sessions. - Keep the client ID and client secret on your server. Follow Direct API authentication and Mint an Access Token.
- Use the same environment for OAuth, issuance and Resolve.js:
https://app-sandbox.resolvepay.comfor sandbox,https://app.resolvepay.comfor production. Setsandbox: trueonly for the sandbox SDK call. - Build the checkout from your server's current cart/order record, after checking the signed-in buyer owns it. Do not forward an unchecked browser payload.
Add Resolve.js to your page template:
<script src="https://app.resolvepay.com/js/resolve.js"></script>Use sandbox: true in the SDK call when connecting to the sandbox environment.
The Node helper performs both server-side requests:
POST /api/access-keys/tokenwith{ client_id, client_secret }obtains a merchant Auth0 M2M access token. This authenticates your backend, not your buyer.POST /api/checkout-sessionssends that bearer token, anIdempotency-Key, and the checkout. The merchant is derived from the credential; do not sendmerchant_id.
Use this complete request example:
{
"checkout": {
"cart_id": "cart_123",
"currency": "USD",
"total_amount": 25,
"customer": { "email": "buyer@example.com" },
"items": [{ "sku": "sku_123", "unit_price": 25, "quantity": 1 }],
"success_url": "https://merchant.example/success",
"cancel_url": "https://merchant.example/checkout"
}
}Amounts are numeric USD dollars with at most two decimal places, not cents or numeric strings. The server accepts 1–1,000 items and treats total_amount as authoritative rather than recalculating it from item prices. Optional tax_amount, shipping_amount, addresses, order_id, order_number and po_number are defined in the API reference. Omit an unused PO number instead of sending an empty string. Return URLs must be HTTP(S), without URL credentials or fragments; query parameter names containing credential-related words are rejected.
Your backend can call the helper as follows. The input variables come from your trusted server-side order/authentication records, not browser-supplied identities:
import { createCheckoutSession } from './server.mjs';
const result = await createCheckoutSession(
{
checkout: orderSnapshot.checkout,
idempotencyKey: checkoutAttempt.id,
},
{
origin: 'https://app-sandbox.resolvepay.com',
clientId: process.env.RESOLVE_CLIENT_ID,
clientSecret: process.env.RESOLVE_CLIENT_SECRET,
},
);
// Your authenticated, ownership-checked HTTP handler returns only result:
res.set('Cache-Control', 'no-store').json(result);Create an attempt ID on the server and retain it with the exact request snapshot for retries. Never generate a new key automatically after a timeout: the first request may have succeeded. A changed cart is a new checkout attempt and needs a new key.
The issuance response is HTTP 201, with Cache-Control: no-store:
{
"id": "opaque_session_id",
"client_token": "opaque_sensitive_reference",
"status": "pending",
"expires_at": "2026-01-01T12:05:00.000Z"
}status can be consumed on an identical retry. Return client_token and expires_at only to the browser authorized to use this cart over HTTPS; they remain in memory for the immediate SDK call. Never return merchant credentials or the merchant access token.
When the buyer chooses Resolve, obtain a reference from your own ownership-checked endpoint:
const response = await fetch('/checkout/resolve-session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
// Apply your application's normal authentication and CSRF protection.
});
if (!response.ok) throw new Error('Unable to start Resolve checkout');
const { client_token } = await response.json();
resolve.checkout({
session_token: client_token,
modal: true,
sandbox: true,
});Use modal: false for full-page checkout. Do not add merchant, customer, items, total_amount or legacy checkout data to this SDK invocation. The SDK loads the server-created state and handles its own browser nonce and handoff proof. Do not build a checkout link containing a token or manually implement the handoff.
Resolve.js handles session redemption and buyer handoff. Your integration supplies only the reference and display/environment options. Creating or opening a session does not authorize or capture a payment.
If your storefront has authenticated the buyer and verified their email, include buyer_assertion in the server request. This identifies the buyer for checkout; Resolve verifies their email before granting payment access.
const result = await createCheckoutSession(
{
checkout: orderSnapshot.checkout,
idempotencyKey: checkoutAttempt.id,
buyerAssertion: {
subject: authenticatedBuyer.stableCustomerId,
email: authenticatedBuyer.verifiedEmail,
email_verified: true,
authenticated_at: authenticatedBuyer.lastAuthenticatedAt,
authentication_methods: ['password'],
},
},
{
origin: 'https://app-sandbox.resolvepay.com',
clientId: process.env.RESOLVE_CLIENT_ID,
clientSecret: process.env.RESOLVE_CLIENT_SECRET,
},
);The helper sends buyerAssertion as buyer_assertion. Use a stable subject scoped to this merchant, a genuinely verified email and the actual ISO authentication timestamp. The normalized email must match checkout.customer.email. New sessions require authentication within 15 minutes, allowing up to 60 seconds of future clock skew. authentication_methods is optional; supply the actual methods when included. An email entered into a checkout form is not a verified identity assertion.
Resolve creates or reuses the merchant-specific buyer from this identity. Conflicting subject/email mappings are rejected rather than switching the buyer to another account.
For an asserted buyer, Resolve presents email verification before payment choices or confirmation. The buyer requests a code, enters it, and continues after successful verification. A valid, fully authenticated Resolve session for the same buyer is reused without another OTP prompt.
This behavior is the default for every buyer assertion. You do not need to set buyer_session_mode. The compatibility values normal and checkout_only follow the same OTP requirement; neither bypasses verification.
Before verification, access is restricted to the bound checkout and buyer. Successful OTP verification establishes the normal Resolve buyer session and links the verified identity to the buyer's Resolve account. The old restricted session cannot be reused.
After verification:
- An approved buyer continues to the merchant's available payment options. Net terms selection leads to confirmation; card or ACH details are requested for payment options that need them.
- A new or unapproved buyer can continue to the merchant's credit application. The application reuses verification for the same buyer and email instead of requesting a second email OTP.
- The merchant's checkout settings determine which payment options are available, including whether Pay Now is offered upfront. They do not bypass the OTP requirement.
Without buyer_assertion, Resolve uses its ordinary buyer sign-in flow. Merchant API credentials authenticate your backend and never sign in a buyer.
Successful checkout logs the buyer out before returning to the merchant. If a verified buyer abandons checkout and starts another checkout while their Resolve session remains valid, that session can be reused for the same buyer. A new session does not extend the existing login's expiry.
For code expiry, resend limits and retry handling, see Session lifecycle and recovery.
Resolve Checkout SDK supports two post-checkout authorization models:
chargemodel: checkout returns acharge_id, and the merchant captures the authorization with the Charges API.ordermodel: checkout returns anorder_id, and the merchant manages the authorization with the Orders API, including partial or multiple captures.
To use the Checkout SDK order model, your merchant must opt in to Checkout - Order Authorization.
When this setting is enabled, successful Checkout SDK completions return an order_id, and the merchant manages that authorization through the order object.
When this setting is not enabled, successful Checkout SDK completions return a charge_id, and the merchant manages that authorization through the charge object.
Resolve supports both authorization models, but each Checkout SDK completion follows the model configured for that merchant.
After a successful checkout, Resolve creates an authorization. Depending on your merchant configuration and selected model, that authorization may be represented as either a charge or an order.
The customer is redirected to your success_url with one of the following query parameters appended:
https://www.merchantsite.com/confirm?charge_id=czTrT9opfkBaYZNhor
https://www.merchantsite.com/confirm?order_id=ORDlaE5wbg0On your success page:
- Redirect the customer to the order confirmation page or display an order confirmation message.
- Store the returned identifier in your order management system:
charge_idif you are using the charge modelorder_idif you are using the order model
- Mark the order payment as pending.
For immediate fulfillment, capture the authorization right away. Otherwise, consult your account manager about capture timing best practices.
For invoices in the "Pay Now" flow, see the Checkout SDK Invoice Flows guide. For a detailed operational guide to the charge model after checkout, see Charge Management. For a detailed operational guide to the order model after checkout, see Checkout SDK Order Management.
If the customer cancels the checkout, they will be redirected back to cancel_url. Typically, this page is the payment method selection page in the checkout flow.
If the customer never reaches the success page, assume the payment failed and do not fulfill the order.
To receive funds and start the Net 30-60-90 clock for the customer, you will need to capture the authorization after fulfillment.
You can do this in one of two ways:
Use the charge_id returned by checkout.
| Environment | Endpoint |
|---|---|
| Production | POST https://app.resolvepay.com/api/charges/<charge_id>/capture |
| Sandbox | POST https://app-sandbox.resolvepay.com/api/charges/<charge_id>/capture |
Use the order_id returned by checkout.
| Environment | Endpoint |
|---|---|
| Production | POST https://app.resolvepay.com/api/orders/<order_id>/capture |
| Sandbox | POST https://app-sandbox.resolvepay.com/api/orders/<order_id>/capture |
The order model supports partial capture and multiple captures against a single authorization. Each capture creates its own invoice and charge under the order.
Use either HTTP Basic Auth (merchant_id + secret_key) or Bearer token auth.
For request/response schemas and live examples, see the Merchant API reference:
To let buyers apply from a financing page, product page or banner, use the Credit Application Modal. Buyers must be approved before they can pay on Resolve credit terms.
Use sandbox credentials and sandbox: true in Resolve.js. Request a sandbox merchant account and an approved test buyer from your Resolve account manager.
Check the complete flow:
- Create a session from your server's cart and open it in both modal and full-page checkout.
- Retry an unchanged session request with the same key; confirm it returns the same session. Confirm a changed payload with that key is rejected.
- For an asserted buyer, confirm verification precedes payment, an incorrect code does not continue, and a correct code does.
- Confirm an approved buyer can select terms and reach confirmation. Confirm a new or unapproved buyer reaches the merchant's application using the verified email.
- Complete checkout, store the returned authorization identifier, verify logout, then capture using the configured charge or order model.
- Check cancellation, session expiry and recovery using the session lifecycle guide.
Follow Direct API Access and Authentication for production credentials. Use https://app.resolvepay.com for server requests and remove sandbox: true from SDK calls. Keep OAuth, session creation and the browser checkout in the same environment.