Super Payments triggers a webhook whenever a significant event occurs within a transaction lifecycle.

Real-time Updates: Receive immediate notice when a transaction status changes.
Monitoring: You can verify your configuration and monitor webhook performance through the Webhook Insights section of your business portal, click on your webhook URL to view the events.

Endpoint Configuration

To begin receiving events, you must register your webhook endpoint URL within the Super Payments Portal. This URL is where our server will send POST requests containing event data.

Registering your Endpoint URL

Access the Portal: Log in to your business portal and navigate to the integrations section.
Enter your URL: Locate the webhook configuration field and enter the full destination URL of your server (e.g., https://your-api.com/webhooks/super).
Retrieve your Secret: Once configured, you will see your Confirmation ID (starting with PWH_). Save this securely, as it is required for signature verification.

Securing your Webhook

To ensure that requests are authentic and originated from Super Payments, every webhook includes a super-signature header.

Signature Format

The super-signature header contains a timestamp and a cryptographic signature, separated by a comma.

Timestamp: Prefixed by t: (e.g., t:1669219987926).
Signature: Prefixed by v1: (e.g., v1:bc2719322a2...).

Verifying the Signature

To verify the signature, you will need your Confirmation ID, which acts as your webhook secret. This ID starts with PWH_ and is located in the Integrations section of your portal, click on the arrow "View this integration".

Extract Data: Split the header by the , character to separate the timestamp and signature.
Parse Pairs: Split the resulting components by the :character to retrieve the actual values.
Prepare Message: Create a single message string by concatenating the timestamp value and the raw request body.
Compute Hash: Generate an HMAC signature using the SHA256 hash function. Use your Confirmation ID as the key and the string from step 3 as the message.
Compare: Ensure the generated hash matches the signature provided in the header.

super-signature: t:1669219987926,v1:bc2719322a26335c486df9dffeb0c555c758b2a7470de6f62421cfb8437e8b5b

Reliability & Retries

If your server is unavailable or returns an error, Super Payments will automatically retry sending the webhook notification using an exponential backoff strategy.

Attempt	Resend Interval
1	8 seconds
2	1 minute
3	8 minutes
4	1 hour
5	8 hours
6	12 hours

🚧
Following the sixth attempt, we continue to retry every 12 hours for a maximum of 7 additional attempts .

Event Reference

Super sends two primary webhooks to track transaction lifecycles. Both payloads contain a transactionStatus field which identifies the specific state of the event.

Payment Status Update Webhook Payload

200 Response

{
"eventType": "PaymentStatus",
"transactionId": "c2909dcb-ade7-4625-aa22-123456789",
"fundingSummary": {
  "cashPayableToMerchant": {
    "amount": 5000,
    "amountMultiplier": 100,
    "currency": "GBP"
  },
  "customerFundedAmount": {
    "amount": 5000,
    "amountMultiplier": 100,
    "currency": "GBP"
  },
  "superFundedAmount": {
    "amount": 0,
    "amountMultiplier": 100,
    "currency": "GBP"
  },
  "merchantFundedAmount": {
    "amount": 0,
    "amountMultiplier": 100,
    "currency": "GBP"
  }
},
"externalReference": "Order-123",
"transactionAmount": "5000",
"transactionSource": "checkoutSession",
"transactionStatus": "PaymentSuccess",
"transactionReference": "CAYNXYZFWT99US62FK"
}

Refund Status Update Webhook Payload

200 Response

{
"eventType": "RefundStatus",
"transactionId": "3a9064a4-dd7b-4f00-a6a6-123456789",
"externalReference": "Tes",
"transactionStatus": "RefundSuccess",
"originatingPaymentId": "a792e89d-658c-4acb-8410-6e08f82636cc",
"transactionReference": "REV8V3XM2DBR5KJ2X",
"superAmountInMinorUnits": 0,
"originatingPaymentSource": "onLine",
"customerAmountInMinorUnits": 1000,
"merchantAmountInMinorUnits": 0,
"requestedAmountInMinorUnits": 1000,
"originatingPaymentExternalReference": "Order-123"
}

Transaction Identification

Every webhook payload includes a transactionId that uniquely identifies the payment transaction. This is the same value as the paymentIntentId returned in the /proceed endpoint and the id returned in the /payments endpoint response.

Source	Field	Description
`/proceed` \| `/payments` response	`paymentIntentId` \| `id`	Unique identifier assigned to the payment transaction
Webhook payload	`transactionId`	The same identifier, referencing the transaction in status updates

Use this shared identifier to correlate webhook events with the payment transactions initiated from your server.

Matching Webhooks to Orders

The externalReference field in the webhook payload is a pass-through value set by the merchant at payment creation. Super Payments does not use this field to deduplicate or relate transactions.

Because multiple transactions can share the same externalReference, you should use the transactionId as the primary identifier when processing webhook events.

Recommended approach:

When calling /proceed| /payments, store the returned paymentIntentId|id against your order.
If the customer retries the payment, call the relavent endpoint again and update the stored ID with the new value.
When a webhook is received, validate that the incoming transactionId matches the paymentIntentId | idcurrently associated with your order.
Discard any webhook where the transactionId does not match.

ON /proceed response:
    order.paymentIntentId = response.paymentIntentId
    SAVE order

ON webhook received:
    order = FIND order BY webhook.externalReference

    IF webhook.transactionId != order.paymentIntentId:
        LOG "Ignoring webhook for outdated transaction"
        RETURN 200 OK
    ELSE:
        UPDATE order status
        RETURN 200 OK

🚧
Always return a 200 OK to acknowledge receipt, even if you discard the event. This prevents unnecessary delivery retries (see Reliability & Retries).

Supported Payment Methods

Webhooks are triggered for payments created through the embedded checkout components and the Payment Intents API, as well as refunds processed through the Refunds API. Webhooks are not triggered for payments created through the **Payment Links API **- this includes any refunds made against those payments, which will also not generate a refund webhook.

Best Practices

Return a 2xx response

Your endpoint must quickly return a successful status code (2xx) prior to executing any complex logic that could cause a timeout. For example, you should return a 200 response immediately upon receiving the event, before performing tasks like updating your database or triggering order fulfillments. This prevents Super from marking the attempt as a failure and initiating retries.