Developers

DirectPagos API

A tiny, predictable REST API for non-custodial USDT (TRC20) payments. Every response is JSON.

https://app.directpagos.com/api/public/v1OpenAPI spec

Authentication

Send your API key in the Authorization header: Bearer <prefix>.<secret>. Test keys start with ctest_, live keys with clive_. Create keys in Dashboard → Developers. Never expose live keys in the browser.

Give this to your AI builder

Paste this prompt into Lovable, Cursor, v0 or any AI IDE — plus your API key, wallet and webhook secret — and it will wire up checkout and webhooks for you.

Integrate the DirectPagos non-custodial USDT (TRC20) payment API into this app.

## Credentials (store as secrets)
- DIRECTPAGOS_API_KEY = "ctest_xxx.yyy"          # or clive_ for production, from Dashboard → Developers
- DIRECTPAGOS_WALLET_ID = "uuid-of-wallet"        # the wallet is registered on DirectPagos (Dashboard → Wallets); use its ID here

The receiving TRC20 wallet is managed on the DirectPagos platform — you do NOT paste
the wallet address in the app. Register it once at
https://app.directpagos.com/dashboard/wallets, then reference it by
wallet_id. You can also list wallets via GET /wallets.

## Base URL
https://app.directpagos.com/api/public/v1

## What to build
1. A server endpoint POST /api/checkout that:
   - reads amount + reference from the request
   - calls POST /charges with { wallet_id: DIRECTPAGOS_WALLET_ID, amount, reference,
     webhook_url: "<APP_URL>/api/directpagos-webhook", return_url: "<APP_URL>/thanks" }
   - returns { hosted_url } to the client
   Authorization header: "Bearer <DIRECTPAGOS_API_KEY>"

2. A checkout button on the frontend that calls /api/checkout and does
   window.location.href = "https://app.directpagos.com" + hosted_url

3. A public webhook endpoint POST /api/directpagos-webhook that:
   - handles event types: payment.confirmed, payment.underpaid, payment.overpaid,
     payment.expired, payment.cancelled
   - is idempotent (dedupe by event id)
   - always responds 200 quickly; do heavy work async

4. A thank-you page at /thanks that shows the payment reference.

## Docs & schema
- Human docs: https://app.directpagos.com/docs
- OpenAPI:    https://app.directpagos.com/api/public/v1/openapi.json

Create a charge

POST /charges

curl -X POST https://app.directpagos.com/api/public/v1/charges \
  -H "Authorization: Bearer ctest_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "YOUR_WALLET_ID",
    "amount": 100.00,
    "description": "Order #1234",
    "reference": "order_1234",
    "webhook_url": "https://api.your-site.com/webhooks/directpagos",
    "return_url": "https://your-site.com/thanks",
    "ttl_minutes": 60,
    "checkout_language": "en"
  }'

Returns a charge including hosted_url, expected_amount (with unique fractional cents for on-chain matching) and expires_at.

Fetch or cancel a charge

GET /charges/{id} · DELETE /charges/{id} (only while created / waiting_payment)

curl https://app.directpagos.com/api/public/v1/charges/pay_XXXX \
  -H "Authorization: Bearer ctest_xxx.yyy"

List wallets & charges

curl https://app.directpagos.com/api/public/v1/wallets \
  -H "Authorization: Bearer ctest_xxx.yyy"

curl "https://app.directpagos.com/api/public/v1/charges?status=confirmed&limit=20" \
  -H "Authorization: Bearer ctest_xxx.yyy"

Webhooks

Configure endpoints in Dashboard → Webhooks. Each delivery includes:

x-directpagos-timestamp — seconds since epoch
x-directpagos-signature — HMAC-SHA256 of <timestamp>.<rawBody> with your endpoint secret

import crypto from "node:crypto";

export function verify(headers: Record<string, string>, rawBody: string, secret: string) {
  const ts = headers["x-directpagos-timestamp"];
  const sig = headers["x-directpagos-signature"];
  if (!ts || !sig) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Events

payment.created
payment.confirmed
payment.underpaid / payment.overpaid
payment.expired / payment.cancelled
credits.purchased

Errors

All errors return JSON { error: { code, message } }. Common codes: missing_api_key, invalid_api_key, insufficient_scope, invalid_body, wallet_not_found, not_found, invalid_state.