Webhooks

Instant Notifications (Webhooks)

The Webhooks system (or IPN) allows us to notify your server immediately when a payment status changes, ensuring that orders are updated even if the customer closes the browser.

Setup

Go to the Merchant Dashboard.
Navigate to the API Credentials section.
Enter your Webhook URL and obtain the Webhook Secret.

Security Verification

To ensure that the notification is coming from MyPay, we send a digital signature in the X-MyPay-Signature header. You must verify this signature.

Verification Example (PHP)

$payload = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_MYPAY_SIGNATURE'];
$webhookSecret = 'your_webhook_secret_here';

// Calculate expected signature using HMAC SHA256
$calculatedSignature = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($calculatedSignature, $receivedSignature)) {
    // ✅ Signature is valid
    // Process the request and update order status in your database
} else {
    // ❌ Signature is invalid
    // Ignore the request
}

Data Structure (Payload)

You will receive a POST request containing JSON in the following format:

{
    "event": "payment.success",
    "type": "QR_PAY",
    "transaction_id": "ABC123XYZ789",
    "token": "ABC123XYZ789",
    "trx_ref": "REF_456789",
    "status": "success",
    "gateway": "moamalat",
    "custom": "ORDER_12345",
    "amount": 100.00,
    "currency": "LYD",
    "timestamp": "2024-01-12 14:30:00"
}

Field Reference

event: Event type (e.g. payment.success)
type: Integration type (QR_PAY)
transaction_id: MyPay transaction identifier
token: Public payment token
trx_ref: Transaction reference (usually the same as token)
status: Payment status (success)
gateway: Lowercase payment gateway alias (e.g. moamalat, yasr-pay, sadad, mobicash) — not an uppercase label
custom: Your order identifier from payment/create — use this to match the webhook to your order (required for integrations such as WooCommerce)
amount: Paid amount
currency: Currency code (e.g. LYD)
timestamp: Notification timestamp

[!NOTE] The gateway value is the lowercase alias sent in payment_gateway during payment/create, not a display name.

Events

payment.success: Payment successfully received

[!IMPORTANT] Your server must respond with status code 200 OK immediately upon receiving the notification to confirm receipt.

← Payments