Webhooks

{
  "amount": 5000,
  "currency": "usd",
  "successUrl": "https://yoursite.com/success",
  "cancelUrl": "https://yoursite.com/cancel",
  "webhookUrl": "https://yoursite.com/api/webhooks/ultrapay"
}

POST https://yoursite.com/api/webhooks/ultrapay
Content-Type: application/json
User-Agent: UltraPay-Webhook/1.0
X-UltraPay-Event: payment.completed
X-UltraPay-Transaction: 550e8400-e29b-41d4-a716-446655440000
X-UltraPay-Timestamp: 2025-12-23T14:30:05.000Z

{
  "event": "payment.completed",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "amount": 5000,
  "currency": "usd",
  "customerEmail": "customer@example.com",
  "stripePaymentId": "pi_3ABC123...",
  "metadata": {
    "orderId": "12345"
  },
  "completedAt": "2025-12-23T14:30:00.000Z",
  "timestamp": "2025-12-23T14:30:05.000Z"
}

curl -X GET https://pay.ultrapay.cc/api/v1/payments/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Public-Key: upp_your_public_key" \
  -H "X-Secret-Key: ups_your_secret_key"

{ "received": true }

// Express.js webhook handler
const ULTRAPAY_API = 'https://pay.ultrapay.cc';

// Statuses that each event can carry (see Event Types)
const EVENT_STATUSES = {
  'payment.completed': ['succeeded'],
  'payment.failed': ['failed', 'cancelled'],
  'payment.expired': ['expired'],
  'payment.refunded': ['refunded', 'partially_refunded'],
  'payment.disputed': ['disputed', 'dispute_lost'],
};

// Fetch the payment with your API keys instead of trusting the webhook body
async function getPayment(transactionId) {
  const response = await fetch(`${ULTRAPAY_API}/api/v1/payments/${encodeURIComponent(transactionId)}`, {
    headers: {
      'X-Public-Key': process.env.ULTRAPAY_PUBLIC_KEY,
      'X-Secret-Key': process.env.ULTRAPAY_SECRET_KEY,
    },
  });
  if (!response.ok) {
    throw new Error(`Payment lookup failed with HTTP ${response.status}`);
  }
  const { data } = await response.json();
  return data;
}

app.post('/api/webhooks/ultrapay', express.json(), async (req, res) => {
  const { event, transactionId } = req.body;
  let eventKey = null;

  try {
    // Confirm the payment with the API
    const payment = await getPayment(transactionId);

    // Only act if the confirmed status matches the event
    if (!EVENT_STATUSES[event]?.includes(payment.status)) {
      return res.json({ received: true });
    }

    // The same event can arrive more than once. claimEvent() records the key
    // under a unique constraint and returns false if it was already recorded.
    const key = `${transactionId}:${event}:${payment.status}`;
    if (!(await claimEvent(key))) {
      return res.json({ received: true }); // Already handled
    }
    eventKey = key;

    const orderId = payment.metadata?.orderId;

    switch (event) {
      case 'payment.completed':
        // Fulfill the order
        console.log(`Payment ${transactionId} completed for $${payment.amount / 100}`);
        await fulfillOrder(orderId);
        break;

      case 'payment.failed':
        // Handle failure
        console.log(`Payment ${transactionId} ${payment.status}`);
        await notifyCustomerOfFailure(orderId);
        break;

      case 'payment.refunded':
        // Handle refund (status is refunded or partially_refunded)
        console.log(`Payment ${transactionId} ${payment.status}`);
        await processRefund(orderId, payment.status);
        break;

      case 'payment.disputed':
        // Handle chargeback (status is disputed or dispute_lost)
        console.log(`Payment ${transactionId} ${payment.status}`);
        await handleDispute(orderId, payment.status);
        break;
    }

    // Respond within 10 seconds
    res.json({ received: true });
  } catch (err) {
    console.error(err);
    if (eventKey) await releaseEvent(eventKey); // Let a retry process it again
    res.status(500).json({ received: false }); // 5xx responses are retried
  }
});

<?php
// Statuses that each event can carry (see Event Types)
const EVENT_STATUSES = [
    'payment.completed' => ['succeeded'],
    'payment.failed' => ['failed', 'cancelled'],
    'payment.expired' => ['expired'],
    'payment.refunded' => ['refunded', 'partially_refunded'],
    'payment.disputed' => ['disputed', 'dispute_lost'],
];

// Fetch the payment with your API keys instead of trusting the webhook body
function getPayment(string $transactionId): ?array
{
    $ch = curl_init('https://pay.ultrapay.cc/api/v1/payments/' . rawurlencode($transactionId));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 5,
        CURLOPT_HTTPHEADER => [
            'X-Public-Key: ' . getenv('ULTRAPAY_PUBLIC_KEY'),
            'X-Secret-Key: ' . getenv('ULTRAPAY_SECRET_KEY'),
        ],
    ]);
    $body = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($body === false || $httpCode !== 200) {
        return null;
    }
    return json_decode($body, true)['data'] ?? null;
}

// Get the webhook payload
$payload = json_decode(file_get_contents('php://input'), true);

$event = $payload['event'] ?? '';
$transactionId = $payload['transactionId'] ?? '';

// Confirm the payment with the API
$payment = getPayment($transactionId);
if ($payment === null) {
    http_response_code(500); // 5xx responses are retried
    exit;
}

// Only act if the confirmed status matches the event
if (!in_array($payment['status'], EVENT_STATUSES[$event] ?? [], true)) {
    http_response_code(200);
    echo json_encode(['received' => true]);
    exit;
}

// The same event can arrive more than once. claimEvent() records the key
// under a unique constraint and returns false if it was already recorded.
$eventKey = $transactionId . ':' . $event . ':' . $payment['status'];
if (!claimEvent($eventKey)) {
    http_response_code(200); // Already handled
    echo json_encode(['received' => true]);
    exit;
}

$orderId = $payment['metadata']['orderId'] ?? null;

try {
    switch ($event) {
        case 'payment.completed':
            // Fulfill the order
            fulfillOrder($orderId);
            break;

        case 'payment.refunded':
            // Handle refund (status is refunded or partially_refunded)
            processRefund($orderId, $payment['status']);
            break;

        case 'payment.disputed':
            // Handle chargeback (status is disputed or dispute_lost)
            handleDispute($orderId, $payment['status']);
            break;
    }
} catch (Throwable $e) {
    releaseEvent($eventKey); // Let a retry process it again
    http_response_code(500); // 5xx responses are retried
    exit;
}

// Acknowledge receipt
http_response_code(200);
echo json_encode(['received' => true]);