DTAI Pay quickstart

Create a checkout session from your server with one API call, send the customer to the hosted checkout, then confirm the order from a signed webhook. Test keys run on Solana devnet, so you can build the full flow without real funds.

Last updated:

1. Get your test keys

Apply as a merchant, then copy your keys from the merchant dashboard. Test keys (pk_test_ and sk_test_) run on Solana devnet and never move real funds. Test and live data are stored separately.

# The SDK is a single file with no dependencies.
curl -O https://digitaltoken.ai/sdk/v1/dtai-server.mjs
curl -O https://digitaltoken.ai/sdk/v1/dtai-server.d.ts

# Keep the secret key on the server only.
export DTAI_SECRET_KEY=sk_test_...
export DTAI_WEBHOOK_SECRET=whsec_...

2. Check that the key works

The /api/v1/me endpoint shows which account and mode a key belongs to, and whether a webhook URL is set. Run it at start-up or in CI.

import { DTAI } from "./dtai-server.mjs"

const dtai = new DTAI(process.env.DTAI_SECRET_KEY)
const me = await dtai.me()
console.log(me.business_name, "livemode:", me.livemode)

3. Create a checkout session

Create the session on your server, then send the customer to checkout_url. Always pass an idempotency key so a retried request cannot create a second session for the same order. Sessions expire after 30 minutes.

// app/api/checkout/route.ts
import { DTAI } from "@/lib/dtai-server.mjs"

const dtai = new DTAI(process.env.DTAI_SECRET_KEY!)

export async function POST(req: Request) {
  const { orderId, total } = await req.json()

  const session = await dtai.sessions.create(
    {
      amount: total,
      currency: "USD",
      order_id: orderId,
      success_url: `https://shop.example/orders/${orderId}/thanks`,
      cancel_url: "https://shop.example/cart",
    },
    { idempotencyKey: `order-${orderId}` },
  )

  return Response.json({ url: session.checkout_url })
}

4. Confirm the payment with a webhook

Set your webhook URL in the merchant dashboard, then verify every event before you trust it. The browser redirect to success_url proves nothing, so fulfil orders from payment.succeeded.

// app/api/dtai/webhook/route.ts
import { DTAI } from "@/lib/dtai-server.mjs"

export async function POST(req: Request) {
  const raw = await req.text() // the raw body, not parsed JSON

  let event
  try {
    event = await DTAI.constructEvent(raw, req.headers.get("x-dtai-signature"), process.env.DTAI_WEBHOOK_SECRET!)
  } catch {
    return new Response("Invalid signature", { status: 400 })
  }

  if (event.type === "payment.succeeded") {
    // Webhooks can arrive more than once. Key your fulfilment on the order, not the delivery.
    await markOrderPaid(event.data.order_id, event.data.tx_signature)
  }
  if (event.type === "payment.expired") {
    await releaseStock(event.data.order_id)
  }

  return new Response("ok") // any 2xx acknowledges the event
}

Optional: add the Pay with DTAI button

Instead of redirecting, show a button that opens the hosted checkout in a popup. It shows Pay with DTAI.

<script src="https://digitaltoken.ai/sdk/v1/dtai.js"></script>
<div id="pay"></div>
<script>
  DTAI.button({
    publishableKey: "pk_test_...",
    sessionId: "cs_...",   // from your server
    theme: "dark",         // "dark" | "light" | "brand"
    mode: "popup",         // "popup" | "redirect"
    container: "#pay",
    onSuccess: function (e) { window.location = e.successUrl }
  })
</script>

5. Go live

Once your application is approved you get pk_live_ and sk_live_ keys. Swap them in, point your live webhook URL at your production server, and run the launch checklist.

Where to next

Developer questions

How do I authenticate API requests?
Send your secret key as a Bearer token in the Authorization header. Keep secret keys on your server. Publishable keys are safe to use in the browser.
How do I verify a webhook?
Compute an HMAC-SHA256 of the timestamp, a dot and the raw request body using your webhook secret, then compare it to the v1 value in the X-DTAI-Signature header with a constant-time comparison. The server SDK does this for you with DTAI.constructEvent.
How does retry work?
Failed deliveries are retried up to eight times with growing waits of 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours. Respond with a 2xx status to acknowledge an event. You can also redeliver any event yourself with the API.
How do I test without real funds?
Use pk_test_ and sk_test_ keys. Test mode runs on Solana devnet and is kept separate from live data. You can also send a signed test event with POST /api/v1/webhooks/test.