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.