أنشئ دفعة، ووجه المشتري إلى الرابط المستلم، ثم استقبل التأكيد عبر webhook. صفحة الدفع يستضيفها lahsab، فلا تحتاج إلى بناء أي شيء. ابدأ في بيئة Sandbox: نفس API الإنتاج، دون مال حقيقي.

1. إنشاء intent

استدع POST /payments/intents بمبلغ بأعداد صحيحة من الدينار (DZD، دون سنتيمات). تحمل الاستجابة حقل checkoutUrl (رابط الدفع الذي يستضيفه lahsab)، صالح لمدة 48 ساعة.

curl -X POST https://api.lahsab.com/payments/intents \
  -H "x-api-key: lsk_sandbox_CLE" \
  -H "content-type: application/json" \
  -d '{ "amount": 2500, "description": "Abonnement Premium", "customerRef": "user_abc123" }'

const res = await fetch("https://api.lahsab.com/payments/intents", {
  method: "POST",
  headers: {
    "x-api-key": process.env.LAHSAB_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    amount: 2500,
    description: "Abonnement Premium",
    customerRef: "user_abc123",
  }),
});
const intent = await res.json();

window.location.href = intent.checkoutUrl;

<?php
$ch = curl_init("https://api.lahsab.com/payments/intents");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "x-api-key: " . getenv("LAHSAB_API_KEY"),
    "content-type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 2500,
    "description" => "Abonnement Premium",
    "customerRef" => "user_abc123",
  ]),
]);
$intent = json_decode(curl_exec($ch), true);

header("Location: " . $intent["checkoutUrl"]);

import os, requests

res = requests.post(
    "https://api.lahsab.com/payments/intents",
    headers={"x-api-key": os.environ["LAHSAB_API_KEY"]},
    json={
        "amount": 2500,
        "description": "Abonnement Premium",
        "customerRef": "user_abc123",
    },
)
intent = res.json()

redirect(intent["checkoutUrl"])

استجابة 201:

{
  "id": "a7f3c2e1-9b4d-4e6a-8c1f-2d3e4f5a6b7c",
  "environment": "sandbox",
  "amount": 2500,
  "status": "pending",
  "checkoutUrl": "https://dashboard.lahsab.com/pay/a7f3c2e1-9b4d-4e6a-8c1f-2d3e4f5a6b7c",
  "expiresAt": "2026-07-13T10:00:00.000Z",
  "proofs": [],
  "createdAt": "2026-07-11T10:00:00.000Z"
}

2. توجيه المشتري إلى صفحة الدفع

أرسل المشتري إلى checkoutUrl. الصفحة التي يستضيفها lahsab تتيح له اختيار وسيلة الدفع (دفع عبر CCP أو بريدي موب)، وتعرض التعليمات وبيانات الوسيلة المختارة، وتستقبل وصل الدفع (إيصال أو لقطة شاشة). يدفع المشتري ويرفع وصله، فتنتقل حالة intent إلى proof_submitted، دون سطر برمجي واحد من جهتك.

3. التأكيد ثم استقبال حدث webhook

تأكيد «وصول المال» يتم يدويا، وهذا جوهر النموذج: تحقق في حسابك من أن التحويل وصل فعلا، ثم اضغط تأكيد في لوحة التحكم. تنتقل حالة intent إلى confirmed ويرسل lahsab الحدث payment.confirmed إلى نقطة النهاية الخاصة بك. هذه إشارتك لمنح الوصول أو شحن الطلب.

التحصيل أكثر من مرة

كل intent يحصل مبلغا واحدا مرة واحدة. لبيع اشتراك، لا تكرر هذه العملية في حلقة: lahsab يصدر الفواتير، ويتابع المتأخرات، ويخبرك إلى أي تاريخ تم الدفع، وكل ذلك باستدعاء واحد لنقطة POST /subscriptions. في هذه الحالة، حدث منح الوصول لم يعد payment.confirmed بل invoice.paid.

وماذا بعد؟

• استقبال الأحداث والتحقق من توقيعها: Webhooks.
• بيع اشتراك: الاشتراكات.
• تنفيذ كل الخطوات دون مال حقيقي: الاختبار في Sandbox.
• جميع نقاط النهاية والحقول والأخطاء: مرجع API.