Checkout API
Create hosted checkout sessions from your server and retrieve checkout information using a Business-scoped API key. All amounts are expressed in cents.
Create Checkout Session
POST /api/platform/v1/checkout-sessions
Creates a checkout session that expires 30 minutes after creation. The Business must be payment-ready and redirect domains configured.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| amountCents | integer | Yes | Positive amount in USD cents. |
| currency | string | Yes | Must be "usd". |
| description | string | Yes | Non-empty payment description. |
| successUrl | string | Yes | Authorized customer success redirect URL. |
| cancelUrl | string | Yes | Authorized customer cancellation redirect URL. |
| merchantReference | string | No | Non-empty merchant reference, maximum 200 characters. |
Example Request
curl -X POST https://www.tabedge.com/api/platform/v1/checkout-sessions \
-H "Authorization: Bearer tb_sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amountCents": 2500,
"currency": "usd",
"description": "Order #1001",
"successUrl": "https://merchant.example/success",
"cancelUrl": "https://merchant.example/cancel",
"merchantReference": "ORDER-1001"
}'Success Response — HTTP 200
{
"checkoutId": "CHECKOUT_ID",
"checkoutUrl": "https://www.tabedge.com/checkout/CHECKOUT_ID"
}Redirect the customer to the returned checkoutUrl. The URL shown above is illustrative; the actual URL is returned by the API.
Retrieve Checkout Status
GET /api/platform/v1/checkouts/{checkoutId}
Retrieves public checkout status fields for the authenticated Business. The API verifies owner, Business, and environment before returning data. Internal wallet, ledger, and accounting metadata are not exposed.
curl https://www.tabedge.com/api/platform/v1/checkouts/CHECKOUT_ID \
-H "Authorization: Bearer tb_sk_live_YOUR_API_KEY"Example Response — HTTP 200
{
"id": "CHECKOUT_ID",
"status": "paid",
"amountCents": 2500,
"currency": "usd",
"description": "Order #1001",
"merchantReference": "ORDER-1001",
"paymentIntentId": "pi_example",
"createdAt": "2026-10-12T00:00:00.000Z",
"updatedAt": "2026-10-12T00:01:00.000Z",
"expiresAt": "2026-10-12T00:30:00.000Z",
"paidAt": "2026-10-12T00:01:00.000Z"
}Status created means the checkout was created but payment is not confirmed. Status paid means server-side payment finalization updated the checkout. Before payment, paymentIntentId and paidAt may be null. Timestamps are ISO 8601 strings when available. The example values above are illustrative.
Inspect the returned status and verify the expected order reference and amount on your backend. Never mark an order paid based only on the customer visiting the success URL.
HTTP Error Reference
| Status | Meaning |
|---|---|
| 400 | Invalid request fields or unauthorized redirect URL |
| 401 | Missing, invalid, or revoked API key |
| 403 | Checkout belongs to another Business or environment |
| 404 | Checkout session not found (status endpoint) |
| 409 | Business not payment-ready, environment mismatch, or missing allowed domains |
| 500 | Internal server error |
| 503 | Checkout API disabled by platform administrator |
Payment Confirmation
For automated fulfillment, use verified server-side checkout status and authenticated merchant webhook notifications. Implement idempotent order processing to prevent duplicate fulfillment.