OpenAPI spec
The DTAI Pay API is described by an OpenAPI 3.1 document. Browse the operations below, or download the JSON to import into Postman or a client generator.
Last updated:
Overview
- Title
- DTAI Pay API
- Version
- 1.0.0
- Server
- https://digitaltoken.ai
- Authentication
- Bearer secret key (sk_test_ or sk_live_)
- Spec URL
- https://digitaltoken.ai/api/v1/openapi.json
Operations
Account
- GET/api/v1/me
Check your API key
Checkout
- POST/api/v1/checkout/sessions
Create a checkout session
- GET/api/v1/checkout/sessions
List checkout sessions
- GET/api/v1/checkout/sessions/{id}
Retrieve a checkout session
- POST/api/v1/checkout/sessions/{id}/expire
Expire a checkout session
Webhooks
- POST/api/v1/webhooks/test
Send a test webhook
- GET/api/v1/webhooks/deliveries
List webhook deliveries
- POST/api/v1/webhooks/deliveries/{id}/redeliver
Redeliver a webhook
Perks
- POST/api/v1/perks/verify
Verify a perk reference
Raw JSON
This is exactly what GET /api/v1/openapi.json returns. Tools should use that URL directly.
Show the full document
{
"openapi": "3.1.0",
"info": {
"title": "DTAI Pay API",
"version": "1.0.0",
"description": "Accept DTAI payments with hosted checkout sessions and signed webhooks. Test keys (sk_test_) run on Solana devnet and never move real funds.",
"contact": {
"name": "Digital Token AI",
"url": "https://digitaltoken.ai/developers"
}
},
"servers": [
{
"url": "https://digitaltoken.ai"
}
],
"tags": [
{
"name": "Account"
},
{
"name": "Checkout"
},
{
"name": "Webhooks"
},
{
"name": "Perks"
}
],
"paths": {
"/api/v1/me": {
"get": {
"operationId": "get-me",
"tags": [
"Account"
],
"summary": "Check your API key",
"description": "Returns the merchant account and mode that a secret key belongs to. Use it as a health check in CI or at server start-up to confirm a key works and a webhook URL is set.",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"merchant_id": "7c1f0b6e-2a54-4d0e-9a3b-5f8e1c2d4a90",
"business_name": "Example Store",
"status": "approved",
"livemode": false,
"settlement_token": "DTAI",
"discount_percent": 0,
"webhook_configured": true,
"allowed_domains": [
"shop.example"
],
"rate_limit_per_minute": 120,
"session_ttl_minutes": 30
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
}
},
"/api/v1/checkout/sessions": {
"post": {
"operationId": "create-session",
"tags": [
"Checkout"
],
"summary": "Create a checkout session",
"description": "Creates a hosted checkout for one order. Send the customer to checkout_url or open it with the embed button. Sessions expire after 30 minutes. The discount you offer is locked in when the session is created.",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"schema": {
"type": "string",
"maxLength": 255
},
"description": "Repeating a request with the same key returns the original response."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"amount",
"order_id",
"success_url",
"cancel_url"
],
"properties": {
"amount": {
"type": "number",
"description": "Order total in the chosen currency. Between about $0.50 and $100,000 USD."
},
"currency": {
"type": "string",
"enum": [
"USD",
"INR"
],
"default": "USD",
"description": "Currency of amount. INR is converted to USD at the live rate."
},
"order_id": {
"type": "string",
"description": "Your own order reference, up to 128 characters."
},
"customer_email": {
"type": "string",
"format": "email",
"description": "Used for receipts and shown on the session."
},
"success_url": {
"type": "string",
"format": "uri",
"description": "Where the customer returns after paying. Must be https, and on an allowed domain if you set any."
},
"cancel_url": {
"type": "string",
"format": "uri",
"description": "Where the customer returns if they cancel."
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Up to 20 string key/value pairs. Keys max 40 characters, values max 500. Returned in every webhook."
}
}
}
}
}
},
"responses": {
"201": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"session_id": "cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z",
"checkout_url": "https://digitaltoken.ai/pay/cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z",
"expires_at": "2026-10-18T12:30:00.000Z",
"livemode": false
}
}
}
},
"400": {
"description": "A field is invalid, the amount is out of range, or a redirect URL is not on an allowed domain.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A request with the same Idempotency-Key is still in progress.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "The Idempotency-Key was reused with different parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
},
"get": {
"operationId": "list-sessions",
"tags": [
"Checkout"
],
"summary": "List checkout sessions",
"description": "Returns your sessions for the key's mode, newest first. Page through results by passing the last session_id of a page as starting_after until has_more is false. Useful for reconciliation jobs.",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 20,
"description": "Page size from 1 to 100."
},
"description": "Page size from 1 to 100."
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "A session_id. Returns sessions created before it."
},
"description": "A session_id. Returns sessions created before it."
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"paid",
"expired",
"refunded"
],
"description": "Only return sessions with this status."
},
"description": "Only return sessions with this status."
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"data": [
{
"session_id": "cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z",
"order_id": "1001",
"status": "paid",
"amount": 49.99,
"currency": "USD",
"amount_usd": 49.99,
"discount_percent": 0,
"settlement_token": "DTAI",
"customer_email": "jane@example.com",
"metadata": {
"cart_id": "abc"
},
"livemode": false,
"created_at": "2026-10-18T12:00:00.000Z",
"expires_at": "2026-10-18T12:30:00.000Z",
"paid_at": "2026-10-18T12:04:11.000Z"
}
],
"has_more": false
}
}
}
},
"400": {
"description": "A query parameter is invalid, or starting_after does not match a session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
}
},
"/api/v1/checkout/sessions/{id}": {
"get": {
"operationId": "get-session",
"tags": [
"Checkout"
],
"summary": "Retrieve a checkout session",
"description": "Returns one session. A pending session is checked against the chain first, so this is a safe way to confirm a payment if a webhook is delayed. The payment object is null until the session is paid.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The identifier from the path."
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"session_id": "cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z",
"status": "paid",
"order_id": "1001",
"amount": 49.99,
"currency": "USD",
"amount_usd": 49.99,
"discount_percent": 0,
"settlement_token": "DTAI",
"customer_email": "jane@example.com",
"metadata": {
"cart_id": "abc"
},
"livemode": false,
"created_at": "2026-10-18T12:00:00.000Z",
"expires_at": "2026-10-18T12:30:00.000Z",
"paid_at": "2026-10-18T12:04:11.000Z",
"payment": {
"tx_signature": "5Qm3...Hx9",
"payer": "2vYA...iMzs",
"pay_token": "DTAI",
"settled_token": "DTAI",
"final_usd": 49.99,
"discount_usd": 0
}
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "The session does not exist, belongs to another merchant, or is in the other mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
}
},
"/api/v1/checkout/sessions/{id}/expire": {
"post": {
"operationId": "expire-session",
"tags": [
"Checkout"
],
"summary": "Expire a checkout session",
"description": "Cancels a pending session so the customer can no longer pay it, for example when the cart changed or stock ran out. A payment.expired webhook is sent. Paid, expired and refunded sessions cannot be expired.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The identifier from the path."
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"session_id": "cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z",
"status": "expired",
"order_id": "1001",
"amount": 49.99,
"currency": "USD",
"amount_usd": 49.99,
"discount_percent": 0,
"settlement_token": "DTAI",
"customer_email": "jane@example.com",
"metadata": {
"cart_id": "abc"
},
"livemode": false,
"created_at": "2026-10-18T12:00:00.000Z",
"expires_at": "2026-10-18T12:30:00.000Z",
"paid_at": null,
"payment": null
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "The session does not exist or is not yours.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "The session is not pending.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
}
},
"/api/v1/webhooks/test": {
"post": {
"operationId": "test-webhook",
"tags": [
"Webhooks"
],
"summary": "Send a test webhook",
"description": "Sends a signed webhook.test event to your configured webhook URL right now and reports how your endpoint answered. Nothing is stored or retried. Use it to check your URL and signature code before a real payment.",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"event_id": "evt_Xk29aPq0LmB7vZc3Nd81WqRt",
"delivered": true,
"response_status": 200,
"error": null,
"duration_ms": 184
}
}
}
},
"400": {
"description": "No webhook URL is set, or it is not a public https URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
}
},
"/api/v1/webhooks/deliveries": {
"get": {
"operationId": "list-deliveries",
"tags": [
"Webhooks"
],
"summary": "List webhook deliveries",
"description": "Returns recent webhook deliveries for the key's mode, newest first, with the attempt count and the last response from your endpoint. Use it to find events your server missed.",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 20,
"description": "Page size from 1 to 100."
},
"description": "Page size from 1 to 100."
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"delivered",
"failed",
"skipped"
],
"description": "Only return deliveries with this status."
},
"description": "Only return deliveries with this status."
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"data": [
{
"id": "9b2f6a3e-5c1d-4e7a-8f10-2d6c4b7a1e33",
"event": "payment.succeeded",
"event_id": "evt_Xk29aPq0LmB7vZc3Nd81WqRt",
"session_id": "cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z",
"status": "failed",
"attempts": 8,
"last_status": 500,
"last_error": "Endpoint responded with 500",
"next_attempt_at": null,
"created_at": "2026-10-18T12:04:12.000Z",
"delivered_at": null,
"livemode": false
}
]
}
}
}
},
"400": {
"description": "A query parameter is invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
}
},
"/api/v1/webhooks/deliveries/{id}/redeliver": {
"post": {
"operationId": "redeliver-webhook",
"tags": [
"Webhooks"
],
"summary": "Redeliver a webhook",
"description": "Resets a delivery and sends it again immediately, with a fresh signature. Use it after fixing a bug in your endpoint. The response shows the new delivery state.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The identifier from the path."
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"id": "9b2f6a3e-5c1d-4e7a-8f10-2d6c4b7a1e33",
"event": "payment.succeeded",
"event_id": "evt_Xk29aPq0LmB7vZc3Nd81WqRt",
"session_id": "cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z",
"status": "delivered",
"attempts": 1,
"last_status": 200,
"last_error": null,
"next_attempt_at": null,
"created_at": "2026-10-18T12:04:12.000Z",
"delivered_at": "2026-10-18T13:00:02.000Z",
"livemode": false
}
}
}
},
"400": {
"description": "No webhook URL is set.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "The delivery does not exist or is in the other mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
}
},
"/api/v1/perks/verify": {
"post": {
"operationId": "verify-perk",
"tags": [
"Perks"
],
"summary": "Verify a perk reference",
"description": "Partners use this to confirm the dtai_ref value a customer arrives with after redeeming a partner perk. Set convert to true to mark the redemption as converted once the customer buys.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"description": "The dtai_ref value from the landing URL."
},
"convert": {
"type": "boolean",
"default": "false",
"description": "Mark the redemption as converted."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"valid": true,
"convert": false
}
}
}
},
"400": {
"description": "ref is missing or malformed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "The secret key is missing, malformed or revoked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "The merchant account is not approved for this mode.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "You exceeded the per-key rate limit. Retry after a short wait.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [
{
"secretKey": []
}
]
}
}
},
"components": {
"securitySchemes": {
"secretKey": {
"type": "http",
"scheme": "bearer",
"description": "Your secret key, such as sk_test_... Keep it on your server."
}
},
"schemas": {
"Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "A readable message."
}
}
}
}
}
}