Wallet Checkout

The checkout system lets merchants create payment links, manage checkouts, and receive webhook notifications when payments complete. It follows a Stripe-inspired model with three levels: Payment, Checkout, and Subscription.

Key concepts

Concept Description
WalletPayment A reusable payment template — amount, interval, name, description. Think of it as a “product listing.”
WalletCheckout A single instance of a payment with a specific payer. Lifecycle: pending → pending_payment → paid | expired.
WalletSubscription Recurring billing schedule — daily, weekly, monthly, or annually. Creates checkouts automatically.

Creating a payment link

From the wallet Payments page, create a new payment with an amount (in ASTR), name, optional description, and optional billing interval. The system creates a permanent shareable URL at /pay/p/<payment_id>.

How a checkout works

When a payer visits the payment link URL:

  1. A new WalletCheckout is created in pending status.
  2. The payer selects an Astreum account to pay from.
  3. The system constructs a TRANSFER transaction from the payer's account to the merchant's Checkout account.
  4. The transaction is signed and submitted.
  5. Status moves to pending_payment while awaiting block confirmation.
  6. A background task polls the chain every 5 minutes. When the transaction lands in a block, status moves to paid.

Checkout API

Merchants can create checkouts programmatically via the wallet API:

POST /api/v1/wallet/checkout
Content-Type: application/json
Authorization: Bearer <checkout_key>
Idempotency-Key: <unique_key>

{
  "payment_id": "<uuid>",
  "account": "<public_key>",
  "amount": 1000
}

The Idempotency-Key header ensures the same checkout is not created twice. Check the status with:

GET /api/v1/wallet/checkout/<checkout_id>

Webhooks

Configure webhook endpoints to receive checkout.paid events. Each delivery includes an HMAC-SHA256 signature in the X-Wallet-Signature header. Failed deliveries are retried automatically with exponential backoff.

Expiry

Checkouts that remain in pending status for too long are automatically expired by a background task running every 5 minutes.