Webhooks

OnCharge uses two webhook flows: inbound (PSP to OnCharge) and outbound (OnCharge to your WooCommerce store).

Outbound Callbacks (OnCharge to Merchant)

When a payment event occurs, OnCharge sends a POST request to your registered callback URL:

POST https://yoursite.com/?wc-api=oncharge_callback

The payload is JSON-encoded and includes an X-Oncharge-Signature header for HMAC verification.

Callback Payload Example

{
  "event": "payment.authorized",
  "session_id": "cs_abc123...",
  "psp_reference": "PSP_REF_...",
  "merchant_reference": "42",
  "status": "authorized",
  "amount": { "value": 9999, "currency": "USD" },
  "metadata": { "woo_order_id": "42" }
}

Verifying the Signature

Compute HMAC-SHA256(signing_secret_hash, JSON.stringify(payload)) and compare to the X-Oncharge-Signature header using a timing-safe comparison.

$expected = hash_hmac('sha256', $raw_body, $secret_hash);
if (!hash_equals($expected, $provided_signature)) {
    // Reject: signature mismatch
}

Event Types

Event	Description
`payment.authorized`	Payment was authorized by the PSP
`payment.captured`	Payment was captured
`payment.refused`	Payment was refused
`payment.cancelled`	Payment was cancelled
`refund.succeeded`	Refund was processed successfully
`refund.failed`	Refund failed
`chargeback.opened`	A chargeback was opened

Retry Policy

OnCharge retries failed callback deliveries with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours. After 10 failed attempts, the delivery is marked as dead.

Inbound PSP Webhooks

OnCharge receives webhooks from the payment processor at dedicated endpoints. These are HMAC-verified using the PSP-provided signing key and acknowledged within milliseconds. Processing is deferred to a durable job queue for reliability.

Merchants do not need to configure PSP webhooks — OnCharge handles this at the company level.