API
API reference
Use project/API-key auth for external merchant checkout creation. Dashboard cookies are not part of this boundary.
Authentication boundaries
Project management endpoints are dashboard authenticated with the `zamapay_session` cookie. Checkout creation is different: it is authenticated by a project API key and an idempotency key.
This split is the core safety boundary. A leaked dashboard cookie should not be needed by merchant infrastructure, and a project API key should not control the dashboard.
| Endpoint | Auth | Purpose |
|---|---|---|
| POST /api/projects | zamapay_session cookie | Create a merchant payment project. |
| POST /api/projects/{projectId}/api-keys | zamapay_session cookie | Create a one-time project API key. |
| POST /api/projects/{projectId}/webhook-endpoints | zamapay_session cookie | Register or rotate a webhook endpoint. |
| POST /api/projects/{projectId}/checkout-sessions | Bearer project API key | Create a buyer-payable hosted checkout session. |
| GET /api/projects/{projectId}/checkout-sessions/{checkoutSessionId} | Bearer project API key | Read one checkout session from merchant backend code. |
Create a checkout session
Send checkout creation from your merchant backend. The request must include `Authorization: Bearer <project API key>` and `idempotency-key`.
curl -X POST \
http://127.0.0.1:8080/api/projects/proj_123/checkout-sessions \
-H "authorization: Bearer zmp_test_..." \
-H "idempotency-key: order_1001" \
-H "content-type: application/json" \
-d '{
"merchantOrderId": "order_1001",
"title": "Prepaid card bundle",
"amountLabel": "120 cUSDT",
"amountMinorUnits": 120000000,
"note": "Release after finality-safe payment",
"successUrl": "http://127.0.0.1:8093/success",
"cancelUrl": "http://127.0.0.1:8093/cancel",
"metadata": { "source": "cardforge" }
}'Ready to wire a merchant project?
Create the project in the console, then keep external checkout creation on the project API-key path.