Payments API

PayDirect deployment (ops)

STRIPE_API_KEY=sk_live_...          # or STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET=whsec_...     # from Stripe Dashboard destination

Stripe Dashboard webhook destination

• URL: https://www.paydirect.com/api/webhooks/stripe
• Events from: Your account (not Connected accounts, unless you use Connect)
• API version: 2026-05-27.dahlia
• Payload style: Snapshot
• Events: checkout.session.completed, checkout.session.expired, payment_intent.payment_failed

Use one destination per environment. Multiple destinations with different signing secrets will break verification.

Live vs sandbox

1. Register outbound webhooks (your server)

POST /api/v1/webhooks
{
  "url": "https://your-app.com/webhooks/paydirect",
  "events": ["payment.forwarded", "payment.failed", "payment.expired"]
}

Fulfill orders on payment.forwarded. Check payment.paymentProvider (onchain or stripe) if you display different receipts.

2. Create payment when user checks out

// User chose "Pay with card"
const res = await fetch("https://www.paydirect.com/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${PAYDIRECT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${orderId}-stripe`,
  },
  body: JSON.stringify({
    paymentMethod: "stripe",
    tokenSymbol: "USD",
    amount: "49.00",
    description: "Pro listing — 30 days",
    metadata: { orderId, userId, listingId },
  }),
});
const { checkoutUrl, paymentUrl, payment } = await res.json();

// Option A: redirect to Stripe Checkout directly (live)
if (checkoutUrl) window.location.href = checkoutUrl;

// Option B: hosted PayDirect page (works for both rails)
// window.location.href = paymentUrl;  // https://www.paydirect.com/pay/{id}

3. Crypto checkout (unchanged)

const res = await fetch("https://www.paydirect.com/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${PAYDIRECT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${orderId}-crypto`,
  },
  body: JSON.stringify({
    paymentMethod: "crypto",
    tokenSymbol: "USDC",
    amount: "49.00",
    merchantWallet: MERCHANT_BASE_ADDRESS,
    metadata: { orderId, userId, listingId },
  }),
});
const { receivingAddress, paymentUrl, payment } = await res.json();
// Show QR / address, or send user to paymentUrl

4. Confirm before fulfilling (poll or webhook)

// After user returns from Checkout, or on webhook receipt:
const { verified, payment } = await fetch("https://www.paydirect.com/api/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${PAYDIRECT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ paymentId: payment.id }),
}).then((r) => r.json());

if (verified) {
  await activateListing(payment.metadata.listingId);
}