Events Reference | RizPay Developer API

Complete reference of all webhook events and their payloads.

Event Types

Transaction Events

Event	Description
`transaction.pending`	Purchase initiated, processing with provider
`transaction.successful`	Purchase completed successfully
`transaction.failed`	Purchase failed
`transaction.reversed`	Payment was reversed/refunded

Product Events

Event	Description
`product.price_changed`	Product price was updated
`product.unavailable`	Product became unavailable
`product.available`	Product became available again

Account Events

Event	Description
`account.low_balance`	Account balance fell below threshold

Subscribe to All

Use * to subscribe to all current and future event types.

Transaction Event Payloads

transaction.pending

Sent when a purchase is initiated:

json

{
  "id": "evt_abc123",
  "type": "transaction.pending",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "object": {
      "id": "txn_xyz789",
      "external_reference": "1736234400A1B2C3",
      "rizpay_reference": "RIZ-ABCD-1234",
      "amount": "1000.00",
      "fee": "0.00",
      "total": "1000.00",
      "status": "pending",
      "product_type": "airtime",
      "product_id": "prd_mtn_airtime",
      "phone_number": "08012345678",
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
}

transaction.successful

Sent when a purchase completes successfully:

json

{
  "id": "evt_def456",
  "type": "transaction.successful",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T10:30:05Z",
  "data": {
    "object": {
      "id": "txn_xyz789",
      "external_reference": "1736234400A1B2C3",
      "rizpay_reference": "RIZ-ABCD-1234",
      "amount": "1000.00",
      "fee": "0.00",
      "total": "1000.00",
      "status": "successful",
      "product_type": "airtime",
      "product_id": "prd_mtn_airtime",
      "phone_number": "08012345678",
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:30:05Z"
    }
  }
}

For electricity purchases, includes the token:

json

{
  "data": {
    "object": {
      "id": "txn_xyz789",
      "status": "successful",
      "product_type": "electricity",
      "meter_number": "12345678901",
      "token": "1234-5678-9012-3456-7890",
      "units": "45.5 kWh"
    }
  }
}

transaction.failed

Sent when a purchase fails:

json

{
  "id": "evt_ghi789",
  "type": "transaction.failed",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T10:30:10Z",
  "data": {
    "object": {
      "id": "txn_xyz789",
      "external_reference": "1736234400A1B2C3",
      "status": "failed",
      "failure_reason": "Provider service unavailable",
      "refunded": true,
      "refund_amount": "1000.00"
    }
  }
}

transaction.reversed

Sent when a transaction is reversed:

json

{
  "id": "evt_jkl012",
  "type": "transaction.reversed",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T12:00:00Z",
  "data": {
    "object": {
      "id": "txn_xyz789",
      "external_reference": "1736234400A1B2C3",
      "status": "reversed",
      "reversal_reason": "Duplicate transaction detected",
      "refund_amount": "1000.00"
    }
  }
}

Product Event Payloads

product.price_changed

json

{
  "id": "evt_mno345",
  "type": "product.price_changed",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T08:00:00Z",
  "data": {
    "object": {
      "id": "prd_mtn_1gb_monthly",
      "name": "MTN 1GB Monthly",
      "old_amount": "500.00",
      "new_amount": "550.00",
      "effective_at": "2024-01-15T08:00:00Z"
    }
  }
}

product.unavailable

json

{
  "id": "evt_pqr678",
  "type": "product.unavailable",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T14:00:00Z",
  "data": {
    "object": {
      "id": "prd_glo_airtime",
      "name": "Glo Airtime",
      "reason": "Provider maintenance"
    }
  }
}

product.available

json

{
  "id": "evt_stu901",
  "type": "product.available",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T16:00:00Z",
  "data": {
    "object": {
      "id": "prd_glo_airtime",
      "name": "Glo Airtime"
    }
  }
}

Account Event Payloads

account.low_balance

json

{
  "id": "evt_vwx234",
  "type": "account.low_balance",
  "api_version": "1.0.0",
  "created_at": "2024-01-15T10:35:00Z",
  "data": {
    "object": {
      "current_balance": "850.00",
      "threshold": "1000.00",
      "currency": "NGN"
    }
  }
}

Handling Events

javascript

app.post("/webhooks/rizpay", express.json(), async (req, res) => {
  const event = req.body;

  // Use event.id for idempotency
  if (await isEventProcessed(event.id)) {
    return res.status(200).send("Already processed");
  }

  try {
    switch (event.type) {
      case "transaction.successful":
        await fulfillOrder(event.data.object);
        break;

      case "transaction.failed":
        await notifyCustomerOfFailure(event.data.object);
        break;

      case "account.low_balance":
        await alertAccountOwner(event.data.object);
        break;

      case "product.price_changed":
        await updateProductCache(event.data.object);
        break;
    }

    await markEventProcessed(event.id);
    res.status(200).send("OK");
  } catch (error) {
    console.error("Webhook processing error:", error);
    // Return 500 to trigger retry
    res.status(500).send("Processing failed");
  }
});

Event Filtering

When creating a webhook, you can subscribe to specific events:

Single event: transaction.successful
Multiple events: transaction.successful, transaction.failed
All events: *

Use specific subscriptions to reduce noise and processing overhead.

Next Steps

Webhook Security - Verify webhook signatures
Webhooks Overview - Setup and configuration