Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.solvapay.com/llms.txt

Use this file to discover all available pages before exploring further.

For the complete webhook guide — setup, signature verification, event catalog, payload schemas, and best practices — see the central Webhooks documentation.

​
Quick Reference

import { verifyWebhook } from '@solvapay/server'

const event = verifyWebhook({
  body: rawBodyString,
  signature: request.headers.get('sv-signature')!,
  secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
})

switch (event.type) {
  case 'payment.succeeded':
    // fulfil the order
    break
  case 'purchase.created':
    // grant access
    break
  case 'purchase.cancelled':
    // revoke access
    break
}

​
Edge Runtimes

import { verifyWebhook } from '@solvapay/server/edge'

const event = await verifyWebhook({
  body: rawBodyString,
  signature: svSignatureHeader,
  secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
})

​
Fetch runtimes (Deno, Cloudflare Workers, Supabase Edge)

For web-standards fetch runtimes, @solvapay/server/fetch provides a solvapayWebhook factory that handles the full lifecycle (read body, verify signature, parse, respond): 
// supabase/functions/solvapay-webhook/index.ts
import { solvapayWebhook } from '@solvapay/server/fetch'

Deno.serve(solvapayWebhook({
  onEvent: async event => {
    // Handle events here
  },
}))
The factory reads SOLVAPAY_WEBHOOK_SECRET from the environment automatically. Use verifyWebhook from @solvapay/server/edge if you need manual control over the request lifecycle. See the Supabase Edge Functions guide for the complete setup.

​
Event Types

EventDescription
payment.succeededPayment successfully processed
payment.failedPayment attempt failed
payment.refundedRefund successfully processed
payment.refund_failedRefund attempt failed
purchase.createdNew purchase created
purchase.updatedPurchase modified
purchase.cancelledPurchase cancelled
purchase.expiredPurchase expired
purchase.suspendedPurchase suspended
customer.createdCustomer created
customer.updatedCustomer updated
customer.deletedCustomer deleted

​
Side effects on Customer and Transaction records

Two SolvaPay-internal webhook handlers update derived data you may rely on:
  • Card mirror on payment_intent.succeeded. When a payment succeeds, SolvaPay mirrors the card brand, last4, expMonth, and expYear onto the Customer record. GET /v1/sdk/payment-method?customerRef=… reads from this mirror, so the SDK’s usePaymentMethod hook and CurrentPlanCard never round-trip to Stripe. The mirror is updated whenever a new successful payment lands, so the “payment method on file” always reflects the last working card.
  • Refund FX normalization. For refunds against transactions with a non-unity exchange rate (e.g. EUR → USD), the refund record now stores both the original-currency amount and the USD equivalent computed from the source transaction’s stored exchangeRate. This keeps wallet balances and revenue reports consistent after cross-currency refunds.
Both behaviors are idempotent and safe to replay. See Webhooks documentation for full payload schemas and integration examples.