Payments API
Manage transactions, payment plans, and checkout sessions.
Payment Plans
Create Payment Plan
Shell
POST /api/v1/projects/{projectId}/payment-plansJSON
{
"title": "Pro Plan — Monthly",
"pricingModel": "fixed_usd",
"amountUsd": "10.00",
"acceptedAssetPolicies": [
{
"policyType": "any"
}
],
"redirectUrl": "https://your-site.com/success"
}Fields:
| Field | Type | Description |
|---|---|---|
title | string | Plan title (required) |
pricingModel | string | fixed_usd or variable pricing (optional) |
amountUsd | string | Fixed USD amount (numeric string) |
minAmountUsd / maxAmountUsd | string | Bounds for variable pricing |
acceptedAssetPolicies | array | Which assets the plan accepts. If omitted, the plan inherits all required-for-checkout assets automatically. Each policy has a policyType (any or asset_definition) and optional assetDefinitionId, environmentScope, chainScope, priority. |
redirectUrl | string | Redirect URL after successful payment |
merchantInfo | object | Merchant metadata |
expiresAt | string | Expiration time (ISO 8601) |
List Payment Plans
Shell
GET /api/v1/projects/{projectId}/payment-plansGet Payment Plan
Shell
GET /api/v1/projects/{projectId}/payment-plans/{planId}Transactions
List Transactions
Shell
GET /api/v1/projects/{projectId}/transactions?page=1&limit=20Query parameters:
| Parameter | Type | Description |
|---|---|---|
page | number | Page number (default: 1) |
limit | number | Items per page (default: 20) |
status | string | Filter by status: pending, confirmed, finalized, failed |
from | string | Filter transactions created on or after this date (ISO 8601) |
to | string | Filter transactions created on or before this date (ISO 8601) |
isLive | boolean | Filter by environment: true = live, false = sandbox |
Get Transaction
Shell
GET /api/v1/projects/{projectId}/transactions/{transactionId}Transaction Statuses
| Status | Description |
|---|---|
pending | Transaction submitted, awaiting confirmation |
confirmed | Transaction confirmed on-chain (first confirmation) |
finalized | Transaction reached full confirmations |
failed | Transaction reverted or timed out |
Checkout Sessions
Create Checkout Session
This endpoint is public — no API key or session token required.
Shell
POST /api/v1/checkout/sessionsJSON
{
"paymentPlanId": "your-payment-plan-id",
"email": "customer@example.com",
"metadata": {
"orderId": "order_123"
}
}Get Checkout Session
Sessions are fetched by their session token (the 64-character token returned when the session is created), not by an internal ID.
Shell
GET /api/v1/checkout/sessions/{sessionToken}