Create a Checkout Session

Create a new checkout session for a one-time payment. This is the core of the Coal payment flow.

POST /api/checkouts

Headers

Name	Type	Required	Description
`x-api-key`	`string`	Yes	Your Coal API key (starts with `coal_live_...`)

Body Parameters

Name	Type	Required	Description
`amount`	`number`	Yes	The amount to charge in MNEE.
`productName`	`string`	No	Display name for the product.
`description`	`string`	No	A description of the purchase.
`currency`	`string`	No	Currency code (default: `MNEE`).
`redirectUrl`	`string`	No	Where to redirect the user after success.
`callbackUrl`	`string`	No	Webhook URL for server-to-server notifications.
`productId`	`string`	No	The ID of the product being purchased.

Example Request

bash

1curl -X POST http://localhost:3001/api/checkouts \
2  -H "Content-Type: application/json" \
3  -H "x-api-key: coal_live_12345..." \
4  -d '{
5    "amount": 25.00,
6    "productName": "Limited Edition Hoodie",
7    "redirectUrl": "https://yoursite.com/success",
8    "callbackUrl": "https://yoursite.com/api/webhook"
9  }'

Example Response

json

1{
2  "id": "clv9abc123...",
3  "url": "http://localhost:3000/pay/clv9abc123...",
4  "status": "pending",
5  "amount": 25.00,
6  "currency": "MNEE",
7  "expiresAt": "2026-01-07T01:30:00.000Z"
8}

Node.js / Next.js Example

typescript

1// app/actions.ts
2'use server';
3import { redirect } from 'next/navigation';
4
5export async function createCheckout(formData: FormData) {
6    const COAL_API_URL = process.env.COAL_API_URL || 'http://localhost:3001/api/checkouts';
7    const API_KEY = process.env.COAL_API_KEY;
8
9    if (!API_KEY) {
10        throw new Error("Missing COAL_API_KEY");
11    }
12
13    const response = await fetch(COAL_API_URL, {
14        method: 'POST',
15        headers: {
16            'Content-Type': 'application/json',
17            'x-api-key': API_KEY,
18        },
19        body: JSON.stringify({
20            amount: parseFloat(formData.get('amount') as string),
21            productName: formData.get('productName') as string,
22            currency: 'MNEE',
23            redirectUrl: 'https://yoursite.com/success',
24            callbackUrl: 'https://yoursite.com/api/webhook'
25        }),
26    });
27
28    if (!response.ok) {
29        throw new Error("Failed to create checkout");
30    }
31
32    const data = await response.json();
33    
34    // Redirect user to Coal payment page
35    redirect(data.url);
36}

Handling the Redirect

Once you receive the url, redirect your user to that page. Coal will:

Display a branded payment form
Connect the user's wallet (MetaMask, WalletConnect, etc.)
Process the MNEE transfer
Verify the transaction on-chain
Redirect to your redirectUrl with ?session_id=clv9abc123...

Webhook Notifications

If you provide a callbackUrl, Coal will POST a webhook notification when the payment is confirmed:

json

1{
2  "event": "checkout.session.completed",
3  "data": {
4    "id": "clv9abc123...",
5    "amount": 25.00,
6    "currency": "MNEE",
7    "status": "confirmed",
8    "txHash": "0xabc123..."
9  }
10}