Webhooks

SaySwitch sends merchant webhooks to the webhook URL configured on the merchant dashboard.

Webhook requests are sent as HTTP POST requests with a JSON body.

Configure Webhooks

Log into the SaySwitch Dashboard.
Navigate to Settings > API Key > Webhook URL.
Add your webhook endpoint URL.

Request Headers

Header	Description
`payloadSignature`	HMAC SHA512 signature of the raw JSON payload using the merchant secret key.
`merchantSignature`	HMAC SHA512 signature of the merchant public key using the merchant secret key.
`timestamp`	Timestamp when the webhook was sent.
`Content-Type`	Always `application/json`.

Signature Rules

payloadSignature = hash_hmac("SHA512", raw_json_payload, merchant_secret_key)

merchantSignature = hash_hmac("SHA512", merchant_public_key, merchant_secret_key)

Use the correct keys for the transaction domain:

Domain	Keys to use
`live`	Live secret key and live public key.
`test`	Test secret key and test public key.

Body Structures

Transaction and payout webhooks use notify and notifyType:

{
  "notify": "transaction | payout",
  "notifyType": "successful | failed",
  "data": {}
}

Refund webhooks use an event name that includes the refund status:

{
  "event": "refund.awaiting_settlement | refund.pending | refund.processing | refund.success | refund.failed | refund.rejected",
  "data": {}
}

Supported Values

Field	Supported values
`notify`	`transaction`, `payout`
`event`	`refund.awaiting_settlement`, `refund.pending`, `refund.processing`, `refund.success`, `refund.failed`, `refund.rejected`

Current Active Notify Types

`notifyType`	Description
`successful`	Sent when a transaction or payout completes successfully.
`failed`	Sent when a transaction or payout fails. A failed payout webhook can also indicate that the payout amount was returned to the merchant wallet.

Final Status Notifications

Pending status is generally not sent for transaction or payout webhooks. Refunds use a separate lifecycle and send refund.awaiting_settlement, refund.pending, refund.processing, refund.success, refund.failed, and refund.rejected events as their status changes.

Webhook Samples

{
  "notify": "transaction",
  "notifyType": "successful",
  "data": {
    "id": 10231,
    "business_id": 169,
    "currency": "NGN",
    "amount": "5000.00",
    "reference": "S2S_OPAY_WALLET_001",
    "ip_address": "102.89.44.10",
    "channel": "opay",
    "type": "banktransfer",
    "domain": "live",
    "fees": "75.00",
    "customer_id": 4512,
    "plan": null,
    "requested_amount": "5000.00",
    "status": "success",
    "card_attempt": null,
    "message": "Payment successful",
    "created_at": "2026-06-13T10:20:30.000000Z",
    "paid_at": "2026-06-13T10:22:15.000000Z",
    "customer": {
      "id": 4512,
      "email": "customer@example.com",
      "first_name": "Test",
      "last_name": "Customer",
      "customer_code": "CUS_ABC123456"
    }
  }
}

Field	Value
`notify`	`transaction`
`notifyType`	`successful`
`data.status`	`success`

For dedicated account and bank transfer collections, transferDetails may be included when available.

For multiple-wallet collections, use the transaction reference to reconcile the wallet-specific payment.

{
  "notify": "transaction",
  "notifyType": "failed",
  "data": {
    "id": 10232,
    "currency": "NGN",
    "amount": "5000.00",
    "reference": "S2S_CARD_FAILED_001",
    "ip_address": "102.89.44.10",
    "channel": "card",
    "type": null,
    "domain": "live",
    "fees": "75.00",
    "plan": null,
    "requested_amount": "5000.00",
    "status": "failed",
    "message": "Payment failed",
    "wallet_id": 123,
    "wallet_code": "NGN169XXXX",
    "created_at": "2026-06-13T10:20:30.000000Z",
    "updated_at": "2026-06-13T10:25:30.000000Z",
    "customer": {
      "id": 4512,
      "email": "customer@example.com",
      "first_name": "Test",
      "last_name": "Customer",
      "customer_code": "CUS_ABC123456"
    }
  }
}

Field	Value
`notify`	`transaction`
`notifyType`	`failed`
`data.status`	`failed`

Failed transaction webhooks are sent when a transaction is marked failed, including expired pending transactions.

{
  "notify": "payout",
  "notifyType": "successful",
  "data": {
    "id": 8841,
    "reference": "PO_1234567890123456",
    "currency": "NGN",
    "amount": "5000.00",
    "fee": "50.00",
    "bank_code": "044",
    "bank_name": "Access Bank",
    "account_number": "0123456789",
    "account_name": "John Doe",
    "narration": "Vendor payment",
    "domain": "live",
    "status": "success",
    "wallet_id": 123,
    "wallet_code": "NGN169XXXX",
    "requestIp": "102.89.44.10",
    "initiator": "API",
    "sender": "SAYSWITCH",
    "created_at": "2026-06-13T11:00:00.000000Z",
    "updated_at": "2026-06-13T11:01:00.000000Z"
  }
}

Field	Value
`notify`	`payout`
`notifyType`	`successful`
`data.status`	`success`

For multiple-wallet payouts, wallet_id and wallet_code identify the source wallet debited.

{
  "notify": "payout",
  "notifyType": "failed",
  "data": {
    "id": 8842,
    "reference": "PO_FAILED_1234567890",
    "currency": "NGN",
    "amount": "5000.00",
    "fee": "50.00",
    "bank_code": "044",
    "bank_name": "Access Bank",
    "account_number": "0123456789",
    "account_name": "John Doe",
    "narration": "Vendor payment",
    "domain": "live",
    "status": "failed",
    "wallet_id": 123,
    "wallet_code": "NGN169XXXX",
    "message": "Transfer failed",
    "requestIp": "102.89.44.10",
    "initiator": "API",
    "sender": "SAYSWITCH",
    "created_at": "2026-06-13T11:00:00.000000Z",
    "updated_at": "2026-06-13T11:05:00.000000Z"
  }
}

Field	Value
`notify`	`payout`
`notifyType`	`failed`
`data.status`	`failed`

A payout webhook with notifyType value failed is sent when the payout status is not success.

If the merchant receives only failed payout webhooks, a failed payout webhook may also indicate that the payout was reversed or refunded.

{
  "notify": "payout",
  "notifyType": "successful",
  "data": {
    "id": 8901,
    "reference": "WTW_1234567890123456",
    "currency": "NGN",
    "amount": "5000.00",
    "fee": "0.00",
    "bank_code": "sayswitch",
    "bank_name": "SaySwitch Wallet",
    "account_number": "NGN200DEST",
    "account_name": "Destination Merchant - Operations Wallet",
    "narration": "Move funds",
    "domain": "live",
    "status": "success",
    "wallet_id": 123,
    "wallet_code": "NGN169SOURCE",
    "requestIp": "102.89.44.10",
    "initiator": "S2S API",
    "sender": "SAYSWITCH",
    "created_at": "2026-06-13T12:00:00.000000Z",
    "updated_at": "2026-06-13T12:00:01.000000Z"
  }
}

Wallet-to-wallet transfer uses the payout webhook structure.

Field	Value
`notify`	`payout`
`notifyType`	`successful`
`fee`	`0`
`wallet_code`	Source wallet debited.
`account_number`	Destination `wallet_code`.

Source and destination wallets must be on the same domain and currency.

{
  "event": "refund.awaiting_settlement",
  "data": {
    "refund_reference": "REF_2026_001",
    "transaction_reference": "USD_TXN_2026_001",
    "amount": "100.00",
    "fee": "1.00",
    "total_reserved": "101.00",
    "currency": "USD",
    "status": "awaiting_settlement",
    "funding": {
      "status": "awaiting_settlement",
      "available_reserved": "40.00",
      "pending_reserved": "61.00",
      "pending_funded_amount": "0.00",
      "pending_remaining": "61.00",
      "funded_at": null
    },
    "external_reference": null,
    "requested_at": "2026-09-28T10:00:00+01:00",
    "updated_at": "2026-09-28T10:00:00+01:00"
  }
}

The refund is accepted but is waiting for reserved pending funds to settle. It moves to pending automatically after it is fully funded.

{
  "event": "refund.pending",
  "data": {
    "refund_reference": "REFUND_REFERENCE",
    "transaction_reference": "SSW_TRANSACTION_REFERENCE",
    "amount": "25.00",
    "fee": "1.00",
    "currency": "USD",
    "status": "pending",
    "external_reference": null,
    "requested_at": "2026-09-27T12:00:00+01:00",
    "updated_at": "2026-09-27T12:00:00+01:00"
  }
}

The refund is fully funded and waiting for processing. This event is also sent when settlement finishes funding an awaiting_settlement refund.

{
  "event": "refund.processing",
  "data": {
    "refund_reference": "REFUND_REFERENCE",
    "transaction_reference": "SSW_TRANSACTION_REFERENCE",
    "amount": "25.00",
    "fee": "1.00",
    "currency": "USD",
    "status": "processing",
    "external_reference": null,
    "requested_at": "2026-09-27T12:00:00+01:00",
    "updated_at": "2026-09-27T12:15:00+01:00"
  }
}

SaySwitch has started processing the refund.

{
  "event": "refund.success",
  "data": {
    "refund_reference": "REFUND_REFERENCE",
    "transaction_reference": "SSW_TRANSACTION_REFERENCE",
    "amount": "25.00",
    "fee": "1.00",
    "currency": "USD",
    "status": "success",
    "external_reference": "EXTERNAL_REF_123",
    "requested_at": "2026-09-27T12:00:00+01:00",
    "updated_at": "2026-09-27T13:00:00+01:00"
  }
}

The refund completed and the reserved balance was consumed.

{
  "event": "refund.failed",
  "data": {
    "refund_reference": "REFUND_REFERENCE",
    "transaction_reference": "SSW_TRANSACTION_REFERENCE",
    "amount": "25.00",
    "fee": "1.00",
    "currency": "USD",
    "status": "failed",
    "external_reference": null,
    "requested_at": "2026-09-27T12:00:00+01:00",
    "updated_at": "2026-09-27T13:00:00+01:00"
  }
}

The processing attempt failed. Funds remain reserved while the refund can be retried or rejected.

{
  "event": "refund.rejected",
  "data": {
    "refund_reference": "REFUND_REFERENCE",
    "transaction_reference": "SSW_TRANSACTION_REFERENCE",
    "amount": "25.00",
    "fee": "1.00",
    "currency": "USD",
    "status": "rejected",
    "external_reference": null,
    "requested_at": "2026-09-27T12:00:00+01:00",
    "updated_at": "2026-09-27T13:00:00+01:00"
  }
}

The refund was rejected and its reserved funds were released.

See Refund Webhooks for the full refund lifecycle and handler examples in JavaScript, PHP, Python, and Java.

Verifying Webhook Signatures

Always verify both payloadSignature and merchantSignature before processing a webhook.

Use the raw request body when generating the expected payloadSignature. Do not parse and re-stringify the JSON before verification.

import crypto from "crypto";
 
function verifySaySwitchWebhook({ rawBody, headers, secretKey, publicKey }) {
  const expectedPayloadSignature = crypto
    .createHmac("sha512", secretKey)
    .update(rawBody)
    .digest("hex");
 
  const expectedMerchantSignature = crypto
    .createHmac("sha512", secretKey)
    .update(publicKey)
    .digest("hex");
 
  const payloadSignature = headers["payloadsignature"];
  const merchantSignature = headers["merchantsignature"];
 
  return (
    payloadSignature === expectedPayloadSignature &&
    merchantSignature === expectedMerchantSignature
  );
}

function verifySaySwitchWebhook($rawBody, $headers, $secretKey, $publicKey): bool
{
    $expectedPayloadSignature = hash_hmac('SHA512', $rawBody, $secretKey);
    $expectedMerchantSignature = hash_hmac('SHA512', $publicKey, $secretKey);
 
    $payloadSignature = $headers['payloadSignature'] ?? $headers['payloadsignature'] ?? null;
    $merchantSignature = $headers['merchantSignature'] ?? $headers['merchantsignature'] ?? null;
 
    return hash_equals($expectedPayloadSignature, $payloadSignature)
        && hash_equals($expectedMerchantSignature, $merchantSignature);
}

import hashlib
import hmac
 
 
def verify_sayswitch_webhook(
    raw_body: bytes,
    headers,
    secret_key: str,
    public_key: str,
) -> bool:
    expected_payload_signature = hmac.new(
        secret_key.encode("utf-8"),
        raw_body,
        hashlib.sha512,
    ).hexdigest()
    expected_merchant_signature = hmac.new(
        secret_key.encode("utf-8"),
        public_key.encode("utf-8"),
        hashlib.sha512,
    ).hexdigest()
 
    payload_signature = headers.get("payloadSignature", "")
    merchant_signature = headers.get("merchantSignature", "")
 
    return hmac.compare_digest(
        expected_payload_signature,
        payload_signature,
    ) and hmac.compare_digest(
        expected_merchant_signature,
        merchant_signature,
    )

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.Map;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
 
public final class SaySwitchWebhookVerifier {
    public static boolean verify(
        byte[] rawBody,
        Map<String, String> headers,
        String secretKey,
        String publicKey
    ) throws Exception {
        String expectedPayloadSignature = hmac(rawBody, secretKey);
        String expectedMerchantSignature = hmac(
            publicKey.getBytes(StandardCharsets.UTF_8),
            secretKey
        );
 
        String payloadSignature = headers.getOrDefault("payloadSignature", "");
        String merchantSignature = headers.getOrDefault("merchantSignature", "");
 
        return matches(expectedPayloadSignature, payloadSignature)
            && matches(expectedMerchantSignature, merchantSignature);
    }
 
    private static String hmac(byte[] value, String secretKey) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA512");
        mac.init(new SecretKeySpec(
            secretKey.getBytes(StandardCharsets.UTF_8),
            "HmacSHA512"
        ));
        return HexFormat.of().formatHex(mac.doFinal(value));
    }
 
    private static boolean matches(String expected, String received) {
        return MessageDigest.isEqual(
            expected.getBytes(StandardCharsets.UTF_8),
            received.getBytes(StandardCharsets.UTF_8)
        );
    }
}

Handling Webhooks

Return HTTP 200 after receiving and validating a webhook. Process long-running work asynchronously so your endpoint responds quickly.

Best Practices

#	Recommendation
1	Verify both webhook signatures before processing the payload.
2	Use the raw JSON payload for signature verification.
3	Use the key pair that matches the originating test or live environment.
4	Process transaction, payout, and refund webhooks idempotently using their references and event status.
5	Respond with HTTP `200` promptly and process heavy tasks asynchronously.
6	Validate `notify` and `notifyType`, or the refund `event`, together with `data.status` before updating records.

Need help? Contact support at developers@sayswitch.com.

TV Validate Sandbox Test Cards