WEBHOOKS

Webhook Documentation

Understand how PayCoinPro notifies your store about payment events.

How Webhooks Work

Real-time Notifications

When a customer makes a payment, PayCoinPro sends an HTTP POST request to your webhook URL with details about the transaction. Your WooCommerce store receives this notification and automatically updates the order status.

1Customer pays with cryptocurrency

2PayCoinPro detects the payment on the blockchain

3Webhook is sent to your store with payment details

4WooCommerce plugin verifies signature and updates order

Event Types

Event	Status	Description
invoice	PAID	Payment received and confirmed (97-105% of expected)
invoice	UNDERPAID	Payment below expected amount
invoice	OVERPAID	Payment exceeds expected amount
invoice	PARTIAL	Partial payment received
invoice	EXPIRED	Invoice expired without payment

Payload Example

Here's an example of the JSON payload sent when a payment is completed:

Invoice Webhook Payloadjson

{
  "event": "invoice",
  "invoiceId": "inv_abc123xyz",
  "orderId": "1234",
  "status": "PAID",
  "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
  "senderAddress": "0x9876543210fedcba9876543210fedcba98765432",
  "txHash": "0x1234567890abcdef1234567890abcdef...",
  "amountReceived": "100.50",
  "amountExpected": "100.00",
  "cryptoSymbol": "USDT",
  "network": "BSC",
  "networkName": "BNB Smart Chain",
  "amountFiat": "100.00",
  "fiatCurrency": "USD",
  "timestamp": "2024-01-15T12:30:00.000Z"
}

Payload Fields

Field	Type	Description
event	string	Event type (always "invoice")
invoiceId	string	PayCoinPro invoice ID
orderId	string	Your WooCommerce order ID
status	string	Payment status
amountReceived	string	Actual amount received in crypto
cryptoSymbol	string	Cryptocurrency used (e.g., USDT, BTC)
txHash	string	Blockchain transaction hash

Signature Verification

HMAC-SHA256 Signatures

Every webhook includes an X-PayCoinPro-Signature header containing an HMAC-SHA256 signature. This allows you to verify the webhook came from PayCoinPro and wasn't tampered with.

The WooCommerce plugin automatically verifies signatures

Invalid signatures are rejected with a 401 error

Make sure your webhook secret is correctly configured

Manual Verification (PHP)

If you're building a custom integration, here's how to verify signatures:

PHP Signature Verificationphp

<?php
// Verify webhook signature in your custom handler
function verify_paycoinpro_signature($payload, $signature, $secret) {
    $expected = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

// Get the raw POST body and signature
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PAYCOINPRO_SIGNATURE'] ?? '';

// Your webhook secret from PayCoinPro dashboard
$secret = 'whsec_your_webhook_secret';

if (!verify_paycoinpro_signature($payload, $signature, $secret)) {
    http_response_code(401);
    die('Invalid signature');
}

// Signature valid - process the webhook
$data = json_decode($payload, true);
// ... handle the event
?>

Best Practices

✓ Always verify signatures

Never trust webhook payloads without verifying the HMAC signature first.

✓ Return 200 OK quickly

Respond with HTTP 200 as soon as you receive the webhook. Process async if needed.

✓ Handle retries gracefully

PayCoinPro retries failed webhooks. Make your handler idempotent to avoid duplicate processing.

✓ Log webhook events

Enable debug logging during development to troubleshoot issues.

Common Issues

Webhooks Not Arriving?

• Check that your webhook URL is accessible from the internet
• Verify SSL certificate is valid (HTTPS required)
• Check firewall rules aren't blocking PayCoinPro IPs
• Ensure the webhook URL is correct in PayCoinPro dashboard
• Look for errors in WooCommerce → Status → Logs

View full troubleshooting guide

Next Steps

Troubleshooting Guide

Common issues, debug logging, and FAQ