Callback Events

The Bridge WooCommerce Plugin uses callbacks to receive real-time payment notifications and update order statuses automatically.

Overview

Callbacks are HTTP POST requests sent to your WooCommerce site when payment events occur. The plugin automatically handles these callbacks to update order statuses and send notifications.

Callback URL

Default Callback URL

https://your-site.com/wc-api/bridge_callback

Custom Callback URL

You can set a custom callback URL in the plugin settings, but the default URL is recommended.

Callback Events

Payment Success

Triggered when a payment is successfully completed.

Event Data:

{
  "event_type": "payment_success",
  "transaction_id": "79",
  "order_id": "1234",
  "status": "000",
  "status_desc": "Transaction Successful",
  "network_transaction_id": "57537797464",
  "amount": 0.1,
  "currency_code": "GHS",
  "customer_number": "0541234567",
  "reference": "Transfer to momo",
  "timestamp": "2025-08-31T23:45:00Z"
}

Plugin Actions:

Update order status to "Processing"
Add order note with transaction details
Send confirmation email to customer
Send SMS notification (if enabled)

Payment Failure

Triggered when a payment fails.

Event Data:

{
  "event_type": "payment_failure",
  "transaction_id": "80",
  "order_id": "1235",
  "status": "001",
  "status_desc": "Transaction Failed",
  "network_transaction_id": "61962982397",
  "amount": 0.1,
  "currency_code": "GHS",
  "customer_number": "0541234567",
  "reference": "Transfer to momo",
  "timestamp": "2025-08-31T23:46:00Z"
}

Plugin Actions:

Update order status to "Failed"
Add order note with failure reason
Send failure notification to customer
Send SMS notification (if enabled)

Payment Pending

Triggered when a payment is still being processed.

Event Data:

{
  "event_type": "payment_pending",
  "transaction_id": "81",
  "order_id": "1236",
  "status": "002",
  "status_desc": "Transaction Pending",
  "network_transaction_id": "pending_12345",
  "amount": 0.1,
  "currency_code": "GHS",
  "customer_number": "0541234567",
  "reference": "Transfer to momo",
  "timestamp": "2025-08-31T23:47:00Z"
}

Plugin Actions:

Keep order status as "Pending Payment"
Add order note with pending status
Send pending notification to customer

Payment Cancelled

Triggered when a payment is cancelled.

Event Data:

{
  "event_type": "payment_cancelled",
  "transaction_id": "82",
  "order_id": "1237",
  "status": "003",
  "status_desc": "Transaction Cancelled",
  "network_transaction_id": "cancelled_12345",
  "amount": 0.1,
  "currency_code": "GHS",
  "customer_number": "0541234567",
  "reference": "Transfer to momo",
  "timestamp": "2025-08-31T23:48:00Z"
}

Plugin Actions:

Update order status to "Cancelled"
Add order note with cancellation reason
Send cancellation notification to customer

Callback Processing

Automatic Processing

The plugin automatically processes callbacks and:

Validates the callback data
Updates the order status
Adds order notes
Sends notifications
Logs the event

Manual Processing

You can also process callbacks manually by:

Going to WooCommerce > Bridge > Callbacks
Viewing recent callbacks
Manually processing failed callbacks

Callback Security

Signature Verification

The plugin verifies callback signatures to ensure authenticity:

// Verify callback signature
$signature = $_SERVER['HTTP_X_BRIDGE_SIGNATURE'];
$payload = file_get_contents('php://input');
$expected_signature = hash_hmac('sha256', $payload, $secret_key);

if (!hash_equals($expected_signature, $signature)) {
    wp_die('Invalid signature', 'Unauthorized', 401);
}

IP Whitelisting

You can whitelist Bridge IP addresses for additional security:

// Allowed IP addresses
$allowed_ips = [
    '203.0.113.1',
    '203.0.113.2',
    '203.0.113.3'
];

$client_ip = $_SERVER['REMOTE_ADDR'];
if (!in_array($client_ip, $allowed_ips)) {
    wp_die('Unauthorized IP', 'Forbidden', 403);
}

Callback Logging

Log Files

Callbacks are logged in:

/wp-content/uploads/bridge-logs/callbacks-YYYY-MM-DD.log

Log Format

[2025-08-31 23:45:00] SUCCESS: Payment callback received for order 1234
[2025-08-31 23:46:00] ERROR: Invalid signature for callback
[2025-08-31 23:47:00] INFO: Payment status updated for order 1235

Log Levels

SUCCESS: Successful callback processing
ERROR: Callback processing failed
INFO: General callback information
DEBUG: Detailed debugging information

Testing Callbacks

Test Callback URL

Use our test endpoint to verify your callback URL:

curl -X POST "https://your-site.com/wc-api/bridge_callback" \
  -H "Content-Type: application/json" \
  -H "X-Bridge-Signature: test_signature" \
  -d '{
    "event_type": "payment_success",
    "transaction_id": "test_123",
    "order_id": "1234",
    "status": "000",
    "status_desc": "Test Transaction",
    "amount": 1.00,
    "currency_code": "GHS"
  }'