v1

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

  1. Go to the Merchant Dashboard.
  2. Navigate to the API Credentials section.
  3. 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.

Automatic Retries

If your server does not acknowledge the webhook successfully, MyPay retries delivery automatically:

  • Up to 5 attempts
  • Intervals: 10s → 30s → 1min → 5min → 10min

Respond with 2xx as soon as you receive the notification. Temporary failures (for example network errors or 502 / 503 / 504) are retried; client errors (4xx) and 500 are not.

Previous
← Payments