Skip to main content

Overview

This guide shows how to build a Next.js App Router API route that creates a Checkout Session and returns a redirectUrl to send your customer to Monime’s hosted checkout.
Base URL: https://api.monime.io · Auth: Bearer token · Required headers: Monime-Space-Id, Idempotency-Key

Prerequisites

Environment variables

Create .env.local:
Never expose tokens in the browser.

Implement the API route

Create app/api/checkout/route.ts:
Notes:
  • Amount is derived from lineItems (price.value × quantity, where value is in SLE minor units).
  • callbackState is 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 the successUrl to a Next.js API route that will:
  1. Verify the session and update your server-side state
  2. Redirect the user to your success UI page
Create app/api/checkout/success/route.ts:
Notes:
  • You can embed extra context in the successUrl query (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.
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 lineItems is non-empty and URLs are absolute
  • 401/403 Auth: use a valid server-side token and correct Monime-Space-Id
  • 409 Conflict: reuse Idempotency-Key only 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