Overview
This guide shows how to build a Next.js App Router API route that creates a Checkout Session and returns aredirectUrl to send your customer to Monime’s hosted checkout.
Base URL:
https://api.monime.io · Auth: Bearer token · Required headers: Monime-Space-Id, Idempotency-KeyPrerequisites
- Access Token (server-side) and Space ID
- Create tokens: Personal Access Tokens
- Find your Space ID: Create a Monime Space (see Developer section → Space list)
- Next.js 13+ with the App Router
Environment variables
Create.env.local:
Implement the API route
Createapp/api/checkout/route.ts:
- Amount is derived from
lineItems(price.value × quantity, wherevalueis in SLE minor units). callbackStateis optional and is echoed back via callbacks for correlation.- Always send a new
Idempotency-Key(e.g., UUID) per logical attempt.
Call the endpoint from your UI
Example client-side handler using fetch:Handle successUrl with a server redirect
Point thesuccessUrl to a Next.js API route that will:
- Verify the session and update your server-side state
- Redirect the user to your success UI page
app/api/checkout/success/route.ts:
- You can embed extra context in the
successUrlquery (e.g.,orderId). - Persist the session ID when creating it, so you can look it up here and confirm status.
- Prefer webhooks for authoritative status; the success redirect is for UX continuity.
Webhooks (recommended)
Use webhooks to reliably update your system about payment outcomes, even if the customer closes the browser before redirection.Webhook Introduction
How webhooks work on Monime
HMAC Verification
Verify webhook signatures securely
Troubleshooting
- 400 Validation: ensure
lineItemsis non-empty and URLs are absolute - 401/403 Auth: use a valid server-side token and correct
Monime-Space-Id - 409 Conflict: reuse
Idempotency-Keyonly to retry the same logical request
Next steps
API Reference
Request schema and responses
Full Checkout Session Guide
Deep dive, options, and multi-stack examples