API reference

The v1 API is JSON over HTTPS at https://digitaltoken.ai/api/v1. Every endpoint needs a secret key, and every example below comes from the same definitions that produce the OpenAPI spec.

Last updated:

The basics

Authentication
Send your secret key as a Bearer token: Authorization: Bearer sk_test_... . The key decides the mode, so a test key only sees test data. Never put a secret key in a browser or a mobile app.
Idempotency
Send an Idempotency-Key header on session creation. Repeating a request with the same key and the same body returns the original response. Reusing a key with a different body returns 422, and a repeat while the first request is still running returns 409.
Rate limits
Each key can make 120 requests per minute. A 429 response means you should wait a moment and retry. The server SDK retries 429 and 5xx responses on safe requests with a short backoff.
Errors
Errors use standard HTTP status codes and a JSON body with a single error field that is safe to log. Treat any 5xx as temporary and retry with the same idempotency key.
HTTP/1.1 400 Bad Request
Content-Type: application/json

{ "error": "Invalid amount: Amount must be at least $0.50" }

Prefer to generate a client? Import the OpenAPI 3.1 spec or read how in SDKs and tools.

Account

Check your API key

GET/api/v1/me

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.

curl https://digitaltoken.ai/api/v1/me \
  -H "Authorization: Bearer sk_test_..."

Errors

  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.

Checkout

Create a checkout session

POST/api/v1/checkout/sessions

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.

Request body (JSON)

  • amountnumberrequired

    Order total in the chosen currency. Between about $0.50 and $100,000 USD.

  • currencyUSD | INRdefault USD

    Currency of amount. INR is converted to USD at the live rate.

  • order_idstringrequired

    Your own order reference, up to 128 characters.

  • customer_emailstring (email)

    Used for receipts and shown on the session.

  • success_urlstring (uri)required

    Where the customer returns after paying. Must be https, and on an allowed domain if you set any.

  • cancel_urlstring (uri)required

    Where the customer returns if they cancel.

  • metadataobject

    Up to 20 string key/value pairs. Keys max 40 characters, values max 500. Returned in every webhook.

curl -X POST https://digitaltoken.ai/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "order_id": "1001",
    "customer_email": "jane@example.com",
    "success_url": "https://shop.example/thanks",
    "cancel_url": "https://shop.example/cart",
    "metadata": {
      "cart_id": "abc"
    }
  }'

Errors

  • 400 A field is invalid, the amount is out of range, or a redirect URL is not on an allowed domain.
  • 409 A request with the same Idempotency-Key is still in progress.
  • 422 The Idempotency-Key was reused with different parameters.
  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.

List checkout sessions

GET/api/v1/checkout/sessions

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.

Query parameters

  • limitintegerdefault 20

    Page size from 1 to 100.

  • starting_afterstring

    A session_id. Returns sessions created before it.

  • statuspending | paid | expired | refunded

    Only return sessions with this status.

curl https://digitaltoken.ai/api/v1/checkout/sessions?limit=20&status=paid \
  -H "Authorization: Bearer sk_test_..."

Errors

  • 400 A query parameter is invalid, or starting_after does not match a session.
  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.

Retrieve a checkout session

GET/api/v1/checkout/sessions/{id}

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.

curl https://digitaltoken.ai/api/v1/checkout/sessions/cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z \
  -H "Authorization: Bearer sk_test_..."

Errors

  • 404 The session does not exist, belongs to another merchant, or is in the other mode.
  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.

Expire a checkout session

POST/api/v1/checkout/sessions/{id}/expire

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.

curl -X POST https://digitaltoken.ai/api/v1/checkout/sessions/cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z/expire \
  -H "Authorization: Bearer sk_test_..."

Errors

  • 404 The session does not exist or is not yours.
  • 409 The session is not pending.
  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.

Webhooks

Send a test webhook

POST/api/v1/webhooks/test

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.

curl -X POST https://digitaltoken.ai/api/v1/webhooks/test \
  -H "Authorization: Bearer sk_test_..."

Errors

  • 400 No webhook URL is set, or it is not a public https URL.
  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.

List webhook deliveries

GET/api/v1/webhooks/deliveries

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.

Query parameters

  • limitintegerdefault 20

    Page size from 1 to 100.

  • statuspending | delivered | failed | skipped

    Only return deliveries with this status.

curl https://digitaltoken.ai/api/v1/webhooks/deliveries?status=failed \
  -H "Authorization: Bearer sk_test_..."

Errors

  • 400 A query parameter is invalid.
  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.

Redeliver a webhook

POST/api/v1/webhooks/deliveries/{id}/redeliver

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.

curl -X POST https://digitaltoken.ai/api/v1/webhooks/deliveries/9b2f6a3e-5c1d-4e7a-8f10-2d6c4b7a1e33/redeliver \
  -H "Authorization: Bearer sk_test_..."

Errors

  • 400 No webhook URL is set.
  • 404 The delivery does not exist or is in the other mode.
  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.

Perks

Verify a perk reference

POST/api/v1/perks/verify

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.

Request body (JSON)

  • refstringrequired

    The dtai_ref value from the landing URL.

  • convertbooleandefault false

    Mark the redemption as converted.

curl -X POST https://digitaltoken.ai/api/v1/perks/verify \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "dtai_ref_value_from_url",
    "convert": true
  }'

Errors

  • 400 ref is missing or malformed.
  • 401 The secret key is missing, malformed or revoked.
  • 403 The merchant account is not approved for this mode.
  • 429 You exceeded the per-key rate limit. Retry after a short wait.