DEVELOPER DOCUMENTATION

Build your first payment.

Create a hosted USDC checkout and complete it safely in sandbox mode.

1. Start the app

pnpm install
pnpm dev

2. Create a payment

curl -X POST http://localhost:3000/api/payments \
  -H "Authorization: Bearer sp_test_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123" \
  -d '{"amount":"25.00","description":"API access"}'

3. Open checkoutUrl

The response contains a hosted checkout path. Open it and click Complete sandbox payment.

Payment lifecycle

Payments move through explicit states: created → awaiting payment → processing → paid. A paid transition requires verified provider evidence and posts balanced immutable journal entries atomically.

Idempotency

Send an Idempotency-Key on every mutation. Reusing a key with different request content is rejected.

Webhooks

Production webhooks use HMAC signatures, timestamp protection, durable event IDs, and retry-safe delivery. Local sandbox completion records the same event contract without sending external traffic.