SANDBOX MODE SANDBOX — test mode, no real charges
Payeny
Header: Payeny-Signature: t=<unix>,v1=<hmac>
Outbound & Inbound Webhooks

Webhooks & Cryptographic Signatures

Payeny dispatches real-time signed HTTP POST webhooks to each merchant's configured webhook URL whenever a checkout session completes, a subscription changes state, an invoice is paid or fails, or a refund is issued.

Fulfillment Rule: Never trust the browser redirect to success_url alone to provision paid entitlements. Always verify the Payeny-Signature header on incoming webhooks before fulfilling orders or activating subscriptions.

Standard Outbound Webhook Envelope

Every outbound webhook delivered to your merchant endpoint shares a deterministic top-level JSON envelope containing id, type, created (Unix timestamp), livemode: false, merchant (your tenant slug, e.g. acme), and data.object:

{
  "id": "evt_70f4e47c3a6801cb6c11",
  "object": "event",
  "type": "checkout.completed",
  "created": 1792720840,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "session_id": "cs_27b5028e3d12ebed8b0e04ce",
      "order_reference": "ORD-261022-C05D2",
      "amount_cents": 5000,
      "amount_total": 5000,
      "currency": "usd",
      "payment_intent": "pi_3UTXmcAlRoAmlooY1rpSrm2Y",
      "payment_id": "pay_80a9228f78ee2a277a56",
      "client_reference_id": "client_ref_12345",
      "status": "succeeded"
    }
  }
}
Event Deduplication: Always deduplicate incoming webhooks by recording the event.id (format ^evt_[0-9a-f]{20}$) in your local database. If an event ID has already been processed, return HTTP 200 OK immediately without re-executing order fulfillment.

Outbound Event Catalog

Payeny emits the following canonical event types across all merchant workspaces:

Event Type Resource When Emitted
checkout.completed cs_... Customer completes payment or subscription signup on hosted checkout (or Stripe checkout.session.completed).
checkout.session.completed cs_... Embedded or custom checkout session is completed and order fulfilled.
payment.created pay_... A new direct payment or charge attempt is initiated via API.
payment.succeeded pay_... Direct payment or checkout payment is successfully settled and confirmed.
payment.captured pay_... An authorized payment is captured.
payment.canceled pay_... An uncaptured payment or authorization is canceled.
payment.failed pay_... A payment intent or card authorization attempt fails.
refund.created ref_... Full or partial refund is issued via API, admin dashboard, or Stripe sync.
subscription.created sub_... A new recurring subscription is created via API, hosted checkout, or sync.
subscription.updated sub_... Subscription plan changes, cancellation is scheduled, subscription is resumed, or status updates.
subscription.canceled sub_... Subscription is canceled immediately or reaches the end of its billing cycle.
subscription.renewed sub_... Subscription successfully renews for a subsequent billing period.
subscription.payment_failed sub_... Recurring subscription billing cycle charge attempt fails.
invoice.created in_... A new customer billing invoice is generated.
invoice.paid in_... Initial or recurring subscription invoice payment succeeds.
invoice.payment_failed in_... Invoice charge attempt fails (e.g. card declined or insufficient funds).
dispute.created dp_... Customer files a payment dispute or chargeback with issuing bank.
dispute.closed dp_... Dispute inquiry is resolved, won, or lost.
payout.status po_... Payout transfer to seller external bank account updates status (paid, failed, pending).
transaction.agreed txn_... Both buyer and seller complete mutual agreement on a marketplace transaction.
merchant.created mer_... A new connected merchant workspace is created.
merchant.updated mer_... Connected merchant profile, status, or payout capability updates.
portal.session.created pts_... Customer billing management portal session is created.
portal.session.accessed pts_... Customer accesses their self-service billing portal session.
usage.recorded usg_... Metered usage event is recorded for a subscription customer.
usage.invoiced usg_... Aggregated metered usage is finalized and invoiced.

Event Payload Examples

1. payment.succeeded
{
  "id": "evt_10a1b2c3d4e5f6a7b8c9",
  "object": "event",
  "type": "payment.succeeded",
  "created": 1792667800,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "pay_9876543210abcdef1234",
      "amount": 2900,
      "amount_cents": 2900,
      "currency": "usd",
      "status": "succeeded",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "payment_method": "pm_card_visa",
      "client_reference_id": "order_ref_12345",
      "fee_cents": 25,
      "net_cents": 2875,
      "description": "Standard Plan Subscription"
    }
  },
  "api_version": "2026-09-01"
}
2. payment.failed
{
  "id": "evt_20b2c3d4e5f6a7b8c9d0",
  "object": "event",
  "type": "payment.failed",
  "created": 1792667820,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "pay_failed_456789abcdef0123",
      "amount_cents": 2900,
      "currency": "usd",
      "status": "failed",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "error_code": "card_declined",
      "decline_code": "insufficient_funds",
      "error_message": "Your card has insufficient funds."
    }
  },
  "api_version": "2026-09-01"
}
3. refund.created
{
  "id": "evt_99887766554433221100",
  "object": "event",
  "type": "refund.created",
  "created": 1792668100,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "ref_5566778899aabbccddee",
      "payment_id": "pay_1234567890abcdef",
      "amount_cents": 1500,
      "currency": "usd",
      "reason": "requested_by_customer",
      "status": "succeeded"
    }
  },
  "api_version": "2026-09-01"
}
4. subscription.created
{
  "id": "evt_30c3d4e5f6a7b8c9d0e1",
  "object": "event",
  "type": "subscription.created",
  "created": 1792668200,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "sub_11223344556677889900",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "price_id": "price_1a2b3c4d5e6f7a8b9c0d1e2f",
      "plan_name": "Studio Pro Plan",
      "status": "active",
      "cancel_at_period_end": false,
      "amount_cents": 2900,
      "currency": "usd",
      "interval": "month",
      "current_period_start": "2026-10-22 10:00:00",
      "current_period_end": "2026-11-22 10:00:00"
    }
  },
  "api_version": "2026-09-01"
}
5. subscription.updated
{
  "id": "evt_11223344556677889900",
  "object": "event",
  "type": "subscription.updated",
  "created": 1792667850,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "sub_9876543210abcdef1234",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "price_id": "price_1a2b3c4d5e6f7a8b9c0d1e2f",
      "plan_name": "Studio Pro Plan",
      "status": "active",
      "cancel_at_period_end": false,
      "amount_cents": 2900,
      "amount_total": 2900,
      "currency": "usd",
      "interval": "month",
      "proration_behavior": "create_prorations",
      "current_period_start": "2026-10-22 10:00:00",
      "current_period_end": "2026-11-22 10:00:00"
    }
  },
  "api_version": "2026-09-01"
}
6. subscription.canceled
{
  "id": "evt_40d4e5f6a7b8c9d0e1f2",
  "object": "event",
  "type": "subscription.canceled",
  "created": 1792668300,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "sub_9876543210abcdef1234",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "status": "canceled",
      "cancel_at_period_end": false,
      "canceled_at": "2026-10-22 10:30:00",
      "amount_cents": 2900,
      "currency": "usd"
    }
  },
  "api_version": "2026-09-01"
}
7. invoice.paid
{
  "id": "evt_ccddeeff001122334455",
  "object": "event",
  "type": "invoice.paid",
  "created": 1792667910,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "in_1042",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "subscription_id": "sub_9876543210abcdef1234",
      "amount_paid": 2900,
      "amount_due": 0,
      "currency": "usd",
      "status": "paid",
      "hosted_invoice_url": "https://payeny.com/invoices/inv_tok_1042",
      "invoice_pdf": "https://payeny.com/api/v1/invoices/1042/pdf"
    }
  },
  "api_version": "2026-09-01"
}
8. invoice.payment_failed
{
  "id": "evt_ffeeddccbbaa00998877",
  "object": "event",
  "type": "invoice.payment_failed",
  "created": 1792667920,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "in_1043",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "subscription_id": "sub_9876543210abcdef1234",
      "amount_due": 2900,
      "amount_paid": 0,
      "currency": "usd",
      "status": "open",
      "attempt_count": 1,
      "hosted_invoice_url": "https://payeny.com/invoices/inv_tok_1043"
    }
  },
  "api_version": "2026-09-01"
}
9. checkout.completed
{
  "id": "evt_aabb1122334455667788",
  "object": "event",
  "type": "checkout.completed",
  "created": 1792667930,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "cs_27b5028e3d12ebed8b0e04ce",
      "session_id": "cs_27b5028e3d12ebed8b0e04ce",
      "order_reference": "ORD-261022-C05D2",
      "amount_total": 5000,
      "currency": "usd",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "status": "complete"
    }
  },
  "api_version": "2026-09-01"
}
10. payment.created
{
  "id": "evt_9900aabbccddeeff1122",
  "object": "event",
  "type": "payment.created",
  "created": 1792667940,
  "livemode": false,
  "merchant": "acme",
  "data": {
    "object": {
      "id": "pay_9876543210abcdef1234",
      "amount_cents": 2900,
      "currency": "usd",
      "status": "pending",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c"
    }
  },
  "api_version": "2026-09-01"
}
Setup session completed (checkout.session.completed with "mode": "setup")

Sent when a customer saves a card through a setup session (hosted page, Elements, or reconciled from the processor's setup_intent.succeeded). Nothing is charged. The saved card is in payment_method and, flattened, in payment_method_id and card (brand, last4, exp_month, exp_year). subscriptions_updated lists subscriptions now using the card; subscriptions_skipped lists any that were not updated, each with a reason. Full card numbers and CVCs are never sent.

{
  "id": "evt_20b1c2d3e4f5a6b7c8d9",
  "object": "event",
  "type": "checkout.session.completed",
  "livemode": false,
  "data": {
    "object": {
      "id": "cs_fc8e0e7f4531d237cb0b847d",
      "object": "checkout.session",
      "mode": "setup",
      "status": "completed",
      "customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
      "subscription_id": "sub_1a2b3c4d5e6f7a8b9c0d",
      "setup_intent_id": "seti_1Example",
      "setup_intent_status": "succeeded",
      "payment_method": { "id": "pm_1Example", "brand": "Visa", "last4": "4242", "exp_month": 12, "exp_year": 2030 },
      "payment_method_id": "pm_1Example",
      "card": { "brand": "Visa", "last4": "4242", "exp_month": 12, "exp_year": 2030 },
      "subscriptions_updated": ["sub_1a2b3c4d5e6f7a8b9c0d"],
      "subscriptions_skipped": [],
      "amount_charged_cents": 0,
      "livemode": false
    }
  }
}

Signature Verification (Payeny-Signature)

Payeny signs every outbound webhook payload using your merchant's webhook secret (whsec_...) and includes the signature in the Payeny-Signature HTTP header:

Payeny-Signature: t=1792667700,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  1. Split the Payeny-Signature header on , to extract the Unix timestamp t and the hex HMAC digest v1.
  2. Construct the signed payload string by concatenating t, a literal period ., and the exact raw UTF-8 HTTP request body: "<t>.<raw body>".
  3. Compute the lower-case hex HMAC-SHA256 of "<t>.<raw body>" using your merchant's whsec_... secret as the key.
  4. Replay Protection: Reject any webhook where abs(current_time - t) > 300 (5 minutes). This prevents replay attacks where a third party captures and retransmits valid payloads.
  5. Constant-Time Comparison: Compare your computed digest to v1 using a timing-safe comparison function (hash_equals in PHP, crypto.timingSafeEqual in Node.js, or hmac.compare_digest in Python) to prevent byte-by-byte timing attacks.

PHP Signature Verification Example

<?php

$rawBody = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_PAYENY_SIGNATURE'] ?? '';
$webhookSecret = getenv('PAYENY_WEBHOOK_SECRET'); // e.g. whsec_acme_...

function verifyPayenyWebhook(string $rawBody, string $sigHeader, string $secret, int $tolerance = 300): array
{
    $parts = [];
    foreach (explode(',', $sigHeader) as $segment) {
        [$k, $v] = array_pad(explode('=', trim($segment), 2), 2, '');
        $parts[$k] = $v;
    }

    $timestamp = (int)($parts['t'] ?? 0);
    $v1 = $parts['v1'] ?? '';

    if ($timestamp <= 0 || $v1 === '') {
        http_response_code(400);
        throw new RuntimeException('Missing timestamp or v1 signature in Payeny-Signature header.');
    }

    if (abs(time() - $timestamp) > $tolerance) {
        http_response_code(400);
        throw new RuntimeException('Webhook timestamp outside tolerance window.');
    }

    $signedPayload = $timestamp . '.' . $rawBody;
    $expectedSignature = hash_hmac('sha256', $signedPayload, $secret);

    if (!hash_equals($expectedSignature, $v1)) {
        http_response_code(400);
        throw new RuntimeException('Invalid Payeny-Signature HMAC digest.');
    }

    return json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
}

$event = verifyPayenyWebhook($rawBody, $sigHeader, $webhookSecret);
// Handle $event['type'] ('checkout.completed', 'subscription.created', etc.)
http_response_code(200);
echo json_encode(['received' => true]);

JavaScript / Node.js Signature Verification Example

import crypto from 'node:crypto';
import express from 'express';

const app = express();

export function verifyPayenySignature(rawBody, sigHeader, webhookSecret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    String(sigHeader || '')
      .split(',')
      .map((item) => item.trim().split('='))
  );

  const timestamp = Number(parts.t);
  const signature = parts.v1 || '';

  if (!timestamp || !signature) {
    throw new Error('Malformed Payeny-Signature header');
  }

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) {
    throw new Error('Webhook timestamp outside tolerance window');
  }

  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(signedPayload, 'utf8')
    .digest('hex');

  const expectedBuf = Buffer.from(expected, 'hex');
  const receivedBuf = Buffer.from(signature, 'hex');

  if (
    expectedBuf.length !== receivedBuf.length ||
    !crypto.timingSafeEqual(expectedBuf, receivedBuf)
  ) {
    throw new Error('Payeny-Signature verification failed');
  }

  return JSON.parse(rawBody);
}

app.post('/webhooks/payeny', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const rawBody = req.body.toString('utf8');
    const sigHeader = req.headers['payeny-signature'];
    const event = verifyPayenySignature(rawBody, sigHeader, process.env.PAYENY_WEBHOOK_SECRET);

    // Handle event.type ('checkout.completed', 'subscription.updated', etc.)
    res.status(200).json({ received: true, id: event.id });
  } catch (err) {
    res.status(400).json({ error: err.message });
  }
});

Python Signature Verification Example

import hmac
import hashlib
import time
import json
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_payeny_signature(raw_body: str, sig_header: str, webhook_secret: str, tolerance_seconds: int = 300) -> dict:
    parts = {}
    for segment in (sig_header or "").split(","):
        if "=" in segment:
            k, v = segment.strip().split("=", 1)
            parts[k] = v

    timestamp = int(parts.get("t", 0))
    signature = parts.get("v1", "")

    if not timestamp or not signature:
        raise ValueError("Malformed Payeny-Signature header: missing timestamp or v1 signature.")

    now = int(time.time())
    if abs(now - timestamp) > tolerance_seconds:
        raise ValueError(f"Webhook timestamp outside tolerance window ({abs(now - timestamp)}s > {tolerance_seconds}s).")

    signed_payload = f"{timestamp}.{raw_body}".encode("utf-8")
    expected_sig = hmac.new(webhook_secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()

    # Timing-safe comparison to prevent byte-by-byte timing attacks
    if not hmac.compare_digest(expected_sig, signature):
        raise ValueError("Invalid Payeny-Signature HMAC digest.")

    return json.loads(raw_body)

@app.route("/webhooks/payeny", methods=["POST"])
def payeny_webhook():
    raw_body = request.get_data(as_text=True)
    sig_header = request.headers.get("Payeny-Signature", "")
    secret = "whsec_..."  # Loaded securely from environment

    try:
        event = verify_payeny_signature(raw_body, sig_header, secret)
        # Handle event["type"] ('checkout.completed', 'subscription.updated', etc.)
        return jsonify({"received": True, "id": event.get("id")}), 200
    except ValueError as e:
        return jsonify({"error": str(e)}), 400

Retry Policy, Exponential Backoff & Delivery Logs

Payeny expects your webhook endpoint to return an HTTP 2xx status code within 10 seconds. Any non-2xx response (such as 4xx or 5xx) or any network timeout exceeding 10 seconds is logged and scheduled for automatic retry with exponential backoff:

Attempt Backoff Delay Status After Failure
Initial Delivery (Attempt 1)Immediate (0s)retrying (schedules Retry 1)
Retry 1 (Attempt 2)+1 minute (60s)retrying (schedules Retry 2)
Retry 2 (Attempt 3)+5 minutes (300s)retrying (schedules Retry 3)
Retry 3 (Attempt 4)+30 minutes (1,800s)retrying (schedules Retry 4)
Retry 4 (Attempt 5)+2 hours (7,200s)retrying (schedules Retry 5)
Retry 5 (Attempt 6)+12 hours (43,200s)retrying (schedules Retry 6)
Retry 6 (Attempt 7)+24 hours (86,400s)Marked failed permanently

Delivery Log & Manual Resend: Every delivery attempt records the event ID, target URL, attempt number, HTTP status code, response snippet, and duration in milliseconds. Operators can inspect all deliveries and trigger a manual Resend from the Payeny Admin dashboard (/admin/merchants and /admin/webhooks).

Webhook Endpoints & Allowed Redirect Domains API

Merchant Scoped

Merchants can dynamically register HTTPS webhook receiver endpoints and allowlisted redirect hostnames for checkout redirection:

  • GET /api/v1/webhook_endpoints — List configured webhook endpoints for the calling merchant.
  • POST /api/v1/webhook_endpoints — Register an HTTPS webhook URL. Returns the whsec_... signature secret once only on creation.
  • DELETE /api/v1/webhook_endpoints/{id} — Remove an endpoint.
  • GET /api/v1/allowed_redirect_domains — List allowlisted redirect hostnames.
  • POST /api/v1/allowed_redirect_domains — Allowlist a bare domain (e.g. example.com) or explicit wildcard (*.example.com).
  • DELETE /api/v1/allowed_redirect_domains/{id} — Delete an allowed domain.
  • POST /api/v1/events/{id}/resend — Admin / merchant resend action that re-delivers an event with the same event ID, fresh timestamp signature, logs the attempt in delivery logs, and never duplicates ledger rows.
  • POST /api/v1/events/{id}/replay — Test-mode-only replay helper supporting mode: "single" | "duplicate" | "out_of_order" and optional unsigned: true (refused in live mode with HTTP 403 test_mode_only).
Example: Register Webhook Endpoint
curl -X POST https://payeny.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sec_test_acme_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/payeny", "description": "Production Webhook"}'

Test-Mode Webhook Replay & Unsigned Webhook Verification

POST /api/v1/events/{id}/replay (TEST MODE ONLY)

In test mode (`sec_test_...`), merchants and QA suites can replay stored webhook events to their configured receiver endpoint to verify signature validation, idempotency deduplication, and out-of-order state handling. Calling this endpoint in live mode is refused with HTTP 403 test_mode_only.

  • mode: "single": Re-delivers the stored event payload once with its original evt_... ID and a fresh Payeny-Signature header.
  • mode: "duplicate": Delivers the identical evt_... event twice back-to-back so you can verify your receiver's idempotency table returns HTTP 200 without double-processing.
  • mode: "out_of_order": Delivers a sequence of events (or event_ids: [...] in reverse/out-of-order sequence, e.g. subscription.updated before subscription.created) to verify your handler reconciles state deterministically.
  • Sending an Unsigned Webhook Test (unsigned: true): Pass "unsigned": true in the replay body—or send a direct curl -X POST to your webhook URL without the Payeny-Signature header—to confirm your receiver rejects unsigned requests with HTTP 400 or 401.
# 1. Replay duplicate delivery (verify idempotency dedupe)
curl -s -X POST https://payeny.com/api/v1/events/evt_70f4e47c3a6801cb6c11/replay \
  -H "Authorization: Bearer sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{"mode": "duplicate"}'

# 2. Replay out-of-order delivery
curl -s -X POST https://payeny.com/api/v1/events/evt_70f4e47c3a6801cb6c11/replay \
  -H "Authorization: Bearer sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{"mode": "out_of_order", "event_ids": ["evt_later_update", "evt_earlier_create"]}'

# 3. Send an unsigned webhook test (omits Payeny-Signature header)
curl -s -X POST https://payeny.com/api/v1/events/evt_70f4e47c3a6801cb6c11/replay \
  -H "Authorization: Bearer sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{"mode": "single", "unsigned": true}'

Inbound Stripe Webhook Endpoint

POST /api/v1/stripe/webhook/{merchant_slug}

Each merchant configures its Stripe test workbench to send events to its dedicated inbound endpoint on Payeny (for example, https://payeny.com/api/v1/stripe/webhook/acme).

  • Per-Merchant Secret Verification: Payeny loads STRIPE_WEBHOOK_SECRET from secrets/stripe_{merchant_slug}.env and verifies the incoming Stripe-Signature header. Any missing or invalid signature is rejected immediately with HTTP 400 Bad Request.
  • Event Deduplication: Processed Stripe event IDs (evt_...) are stored in stripe_webhook_events so duplicate deliveries return 200 {"received":true,"duplicate":true} without double-processing.
  • State Sync & Outbound Fan-Out: Payeny updates local database records (checkout_sessions, subscriptions_v2, invoices, refunds_v2) and dispatches the corresponding signed Payeny outbound webhook to the merchant's endpoint.
curl -X POST https://payeny.com/api/v1/stripe/webhook/acme \
  -H "Stripe-Signature: t=1792667700,v1=..." \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_test_123","type":"checkout.session.completed","data":{"object":{"id":"cs_test_123"}}}'