Developer Documentation

# First page
GET /api/v1/payments?limit=100

# Next page
GET /api/v1/payments?limit=100&after=<next_cursor from meta>

# With filters
GET /api/v1/payments?status=confirmed&currency=USDC&limit=50

{
  "event": "payment.confirmed",
  "data": {
    "payment_id":   "3f2a1c8e-...",       // UUID — use as idempotency key
    "product_id":   "7b8d3e2f-...",       // UUID of the purchased product
    "product_name": "My eBook",
    "product_slug": "my-ebook",
    "product_type": "digital",           // digital | physical | service | tip

    "currency":       "USDC",            // USDC | SOL
    "amount_crypto":  9.99,              // total amount sent by buyer
    "price_usd":      9.99,              // USD value at time of payment
    "platform_fee":   0.098901,          // 0.99% deducted by HashPrism
    "creator_amount": 9.891099,          // amount_crypto - platform_fee

    "tx_signature": "5yYZ1km...",        // Solana transaction signature
    "buyer_wallet": "BuyerPubkey...",    // buyer's Solana wallet address

    "buyer_email": "buyer@example.com",  // null if not collected at checkout
    "buyer_name":  "Jane Doe"            // null if not collected at checkout
  },
  "timestamp": "2026-04-01T14:30:00.000Z"
}

{
  "event": "refund.confirmed",
  "data": {
    "refund_id":    "9c4b2d1a-...",       // UUID of the refund record
    "payment_id":   "3f2a1c8e-...",       // UUID of the original payment
    "product_id":   "7b8d3e2f-...",
    "product_name": "My eBook",
    "product_slug": "my-ebook",
    "product_type": "digital",

    "currency":       "USDC",
    "amount_crypto":  9.891099,           // amount the creator received originally
    "refund_fee":     0.097922,           // 0.99% of creator_amount
    "buyer_receives": 9.793177,           // amount_crypto - refund_fee

    "tx_signature": "8aBC2zk...",
    "buyer_wallet": "BuyerPubkey...",
    "buyer_email":  "buyer@example.com"   // null if not available
  },
  "timestamp": "2026-04-01T15:00:00.000Z"
}

{
  "event": "test",
  "data": { "message": "HashPrism webhook test — your endpoint is working." },
  "timestamp": "2026-04-01T15:00:00.000Z"
}

import crypto from 'crypto'

// Next.js App Router example — works with any framework
export async function POST(req: Request) {
  // 1. Read raw body before any parsing
  const rawBody = await req.text()
  const sigHeader = req.headers.get('x-hashprism-signature') ?? ''

  // 2. Parse the signature header
  const timestamp = sigHeader.match(/t=(\d+)/)?.[1]
  const receivedHex = sigHeader.match(/v1=([a-f0-9]+)/)?.[1]

  if (!timestamp || !receivedHex) {
    return new Response('Bad signature format', { status: 400 })
  }

  // 3. Reject replays older than 5 minutes
  const age = Math.abs(Date.now() / 1000 - parseInt(timestamp, 10))
  if (age > 300) {
    return new Response('Timestamp expired', { status: 400 })
  }

  // 4. Compute expected HMAC
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
    .update(`${timestamp}.${rawBody}`)  // signed payload = timestamp + "." + body
    .digest('hex')

  // 5. Constant-time comparison — prevents timing attacks
  const valid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedHex)
  )
  if (!valid) return new Response('Unauthorized', { status: 401 })

  // 6. Parse and dispatch — respond immediately, process async
  const payload = JSON.parse(rawBody)

  if (payload.event === 'payment.confirmed') {
    const { payment_id, product_id, product_type, buyer_email, buyer_name,
            amount_crypto, currency, buyer_wallet } = payload.data

    // Check idempotency before acting
    const alreadyProcessed = await db.payments.exists({ hashprismId: payment_id })
    if (!alreadyProcessed) {
      await queue.push('fulfill', { payment_id, product_id, product_type,
                                    buyer_email, buyer_name, currency,
                                    amount_crypto, buyer_wallet })
    }
  }

  if (payload.event === 'refund.confirmed') {
    const { payment_id, buyer_email, buyer_receives, currency } = payload.data
    await queue.push('revoke-access', { payment_id, buyer_email, buyer_receives, currency })
  }

  return new Response('OK', { status: 200 })
}

import hmac, hashlib, re, time, os
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET']

def verify_hashprism_signature(raw_body: bytes, sig_header: str) -> bool:
    ts_match = re.search(r't=(\d+)', sig_header)
    hex_match = re.search(r'v1=([a-f0-9]+)', sig_header)
    if not ts_match or not hex_match:
        return False

    timestamp = int(ts_match.group(1))
    received_hex = hex_match.group(1)

    # Reject replays older than 5 minutes
    if abs(time.time() - timestamp) > 300:
        return False

    signed_payload = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(WEBHOOK_SECRET.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_hex)

@app.route('/webhook/hashprism', methods=['POST'])
def handle_webhook():
    raw_body = request.get_data()
    sig_header = request.headers.get('X-HashPrism-Signature', '')

    if not verify_hashprism_signature(raw_body, sig_header):
        abort(401)

    payload = request.get_json()
    event = payload['event']
    data = payload['data']

    if event == 'payment.confirmed':
        # Queue fulfillment asynchronously
        queue.enqueue('fulfill', payment_id=data['payment_id'],
                      buyer_email=data['buyer_email'])

    return 'OK', 200