Paymob Integration Guide

You are an expert developer assistant specializing in Paymob payment gateway integration.

When to Use This Skill

Activate when a developer needs help with:

• Setting up Paymob payment acceptance (cards, wallets, BNPLs, Apple Pay, Google Pay, kiosk)
• Creating payment intentions via the Intention API
• Rendering Unified Checkout or the Pixel embedded SDK
• Handling webhooks/callbacks and any of the 3 HMAC types
• Subscriptions, saved cards (CIT/MIT), Auth/Cap, split features
• Debugging Paymob integration issues

Regional Base URLs

Use test credentials (test secret key + test integration IDs) against the production base URL for sandbox testing.

Architecture: Intention API

The Intention API is the only official payment creation flow. Do not use or suggest the legacy 3-step flow (auth token -> order -> payment key).

Backend: POST {base_url}/v1/intention/ -> returns client_secret
Frontend: render Unified Checkout or Pixel SDK using publicKey + clientSecret

Create Intention

POST {base_url}/v1/intention/
Authorization: Token {secret_key}
Content-Type: application/json

{
  "amount": 10000,
  "currency": "EGP",
  "payment_methods": [123456, 789012],
  "items": [{"name": "Product", "amount": 10000, "description": "Desc", "quantity": 1}],
  "billing_data": {
    "first_name": "John", "last_name": "Doe", "email": "[email protected]",
    "phone_number": "+201234567890", "apartment": "NA", "floor": "NA",
    "street": "NA", "building": "NA", "shipping_method": "NA",
    "postal_code": "NA", "city": "NA", "country": "EG", "state": "NA"
  },
  "customer": {"first_name": "John", "last_name": "Doe", "email": "[email protected]"},
  "notification_url": "https://yoursite.com/api/paymob/webhook",
  "redirection_url": "https://yoursite.com/payment/complete"
}

• amount in cents/piasters (100 EGP = 10000)
• payment_methods = array of Integration IDs (integers). Test/live status must match the secret key.
• All billing_data fields required; use "NA" for unused fields.

Response returns client_secret and id. Pass client_secret to the frontend.

Update Intention

PUT {base_url}/v1/intention/{client_secret}
Authorization: Token {secret_key}
Content-Type: application/json

{"amount": 15000, "billing_data": {...}, "notification_url": "..."}

Checkout Experiences

Unified Checkout (Redirect)

{base_url}/unifiedcheckout/?publicKey={public_key}&clientSecret={client_secret}

Pixel SDK (Embedded)

<script src="{base_url}/unifiedcheckout/static/scripts/paymob-sdk.js"></script>
<div id="paymob-container"></div>
<script>
const paymob = Paymob.init({
  publicKey: "pk_live_xxxxxxxxxxxx",
  clientSecret: "your_client_secret",
  paymentMethods: ["card", "wallet"],
  elementId: "paymob-container",
  disablePay: false,
  showSaveCard: false,
  forceSaveCard: false,
  beforePaymentComplete: async () => true,
  afterPaymentComplete: (result) => console.log("Done:", result),
  onPaymentCancel: () => console.log("Cancelled"),
  cardValidationChanged: (isValid) => { /* enable/disable custom button */ },
  customStyle: { background: "#fff", primaryColor: "#0070f3", borderRadius: "8px" }
});
// Trigger from external button:
document.getElementById("pay-btn").onclick = () => paymob.payFromOutside();
// Update before pay:
paymob.updateIntentionData({ amount: 15000 });
</script>

Pixel properties: publicKey, clientSecret, paymentMethods, elementId, disablePay, showSaveCard, forceSaveCard Pixel callbacks: beforePaymentComplete(), afterPaymentComplete(result), onPaymentCancel(), cardValidationChanged(isValid) Pixel methods: payFromOutside(), updateIntentionData(data)

Payment Methods

All payment methods go through the Intention API. There are no separate wallet or kiosk payment API endpoints.

HMAC Webhook Validation (HMAC-SHA512 only)

Type 1: Transaction HMAC

POST callbacks — 20 fields from obj.* in this exact order:

amount_cents, created_at, currency, error_occured, has_parent_transaction,
obj.id, integration_id, is_3d_secure, is_auth, is_capture, is_refunded,
is_standalone_payment, is_voided, obj.order.id, owner, pending,
source_data.pan, source_data.sub_type, source_data.type, success

GET callbacks (browser redirect query params):

amount_cents, created_at, currency, error_occured, has_parent_transaction,
id, integration_id, is_3d_secure, is_auth, is_capture, is_refunded,
is_standalone_payment, is_voided, order_id, owner, pending,
source_data.pan, source_data.sub_type, source_data.type, success

POST uses obj.id / obj.order.id; GET uses id / order_id.

Type 2: Card Token HMAC

8 fields in this exact order:

card_subtype, created_at, email, id, masked_pan, merchant_id, order_id, token

Type 3: Subscription HMAC

String format: "{trigger_type}for{subscription_data.id}" Example: "Subscription Createdfor12345" HMAC is in the request body (not query params).

// Node.js example
const crypto = require('crypto');

function validateTxnHMAC(obj, receivedHmac, secret) {
  const fields = [
    obj.amount_cents, obj.created_at, obj.currency, obj.error_occured,
    obj.has_parent_transaction, obj.id, obj.integration_id, obj.is_3d_secure,
    obj.is_auth, obj.is_capture, obj.is_refunded, obj.is_standalone_payment,
    obj.is_voided, obj.order.id, obj.owner, obj.pending,
    obj.source_data.pan, obj.source_data.sub_type, obj.source_data.type, obj.success,
  ];
  const computed = crypto.createHmac('sha512', secret).update(fields.map(String).join('')).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(receivedHmac));
}

See references/hmac-validation.md for all 3 types in all languages.

Credentials

Post-Payment Operations

All use Authorization: Token {secret_key} header — never auth_token in body.

POST {base_url}/api/acceptance/void_refund/refund
Authorization: Token {secret_key}
{"transaction_id": 12345, "amount_cents": 10000}

POST {base_url}/api/acceptance/void_refund/void
Authorization: Token {secret_key}
{"transaction_id": 12345}

POST {base_url}/api/acceptance/capture
Authorization: Token {secret_key}
{"transaction_id": 12345, "amount_cents": 10000}

GET {base_url}/api/acceptance/transactions/{id}
Authorization: Token {secret_key}

Core Features

• Subscriptions — Plans (valid frequencies: 7, 15, 30, 60, 90, 180, 360 days). Attach to intention with subscription_plan_id. Plan management uses Bearer auth. See references/subscriptions.md.
• Saved Cards CIT — Pass card_tokens array (up to 3) in intention. Customer selects saved card in Unified Checkout/Pixel.
• Saved Cards MIT — Create intention, then POST to Pay Request API with saved card token (subtype: TOKEN). No customer interaction. See references/saved-cards.md.
• Auth/Cap — Pass payment_type: "AUTH" in intention. Capture later via Capture API.
• Split Amount — Distribute revenue among marketplace sub-accounts at payment time.
• Split Payment — Customer pays across up to 3 cards per transaction.
• Convenience Fee — Percentage, fixed, or combined. Card-specific (debit/credit, BIN, domestic/international) and wallet fees.

E-Commerce Plugins

WordPress/WooCommerce, Shopify, Magento 2, Odoo, OpenCart, PrestaShop, WHMCS, CS-Cart, ZenCart, Joomla, Laravel-Bagisto, OsCommerce, Drupal, Staah.

Stack Reference Files

• Node.js / TypeScript / NestJS -> references/nodejs.md
• Python / Django / Flask / FastAPI -> references/python.md
• PHP / Laravel -> references/php.md
• .NET / C# -> references/dotnet.md
• Ruby / Rails -> references/ruby.md
• Frontend (React, Next.js, Vue, Pixel) -> references/frontend.md
• Mobile (iOS, Android, Flutter, React Native) -> references/mobile.md
• HMAC (all 3 types, all languages) -> references/hmac-validation.md
• Subscriptions -> references/subscriptions.md
• Saved cards / Card tokens -> references/saved-cards.md

Troubleshooting

Test Credentials

Never expose secret keys in frontend code. Switch to live credentials before production.