تخطَّ إلى المحتوى
افتح بيئة اختبار API

02ابدأ هنا

أول دفعة تجريبية

مسار كامل من إنشاء الفاتورة إلى استقبال حدث الدفع، من دون شبكة حقيقية أو رصيد قابل للتحويل.

في هذه الصفحة

قبل أن تبدأ

  • اختر وضع الاختبار وأنشئ مفتاحاً يبدأ بـ nbta_test_.
  • استخدم عنوان API نفسه؛ نوع المفتاح يحدد بيئة الاختبار.
  • احفظ المفتاح في خادمك أو متغير سري في Postman. بيئة الاختبار لا تحفظ المفتاح المدخل.

1. أنشئ فاتورة

POST /v1/invoices
curl -X POST "$NBTA_BASE_URL/v1/invoices" \
  -H "Authorization: Bearer $NBTA_API_KEY" \
  -H "Idempotency-Key: order-2026-0042-create" \
  -H "Content-Type: application/json" \
  --data '{
    "external_id": "order_2026_0042",
    "amount": "50.00",
    "payment_route_id": "00000000-0000-4000-8000-000000000001",
    "success_url": "https://store.example/orders/0042/thanks",
    "cancel_url": "https://store.example/cart",
    "customer": { "email": "sara@example.com", "name": "Sara" }
  }'
@nbta/sdk
import { NbtaClient } from "@nbta/sdk";

const nbta = new NbtaClient({
  baseUrl: process.env.NBTA_BASE_URL!,
  apiKey: process.env.NBTA_API_KEY!,
});

const invoice = await nbta.createInvoice(
  {
    external_id: "order_2026_0042",
    amount: "50.00",
    payment_route_id: "00000000-0000-4000-8000-000000000001",
    success_url: "https://store.example/orders/0042/thanks",
    cancel_url: "https://store.example/cart",
    customer: { email: "sara@example.com", name: "Sara" },
  },
  { idempotencyKey: "order-2026-0042-create" },
);
  • success_urlاختياري. بعد تأكيد الدفع تعرض صفحة الدفع زر العودة إلى المتجر، وتنقل الدافع إليه تلقائيًا بعد 5 ثوانٍ ما لم يختر البقاء.
  • cancel_urlاختياري. ما دامت الفاتورة غير مدفوعة تعرض صفحة الدفع رابط إلغاء والعودة. عند النقر تُلغى الفاتورة ويصلك webhook باسم invoice.cancelled فورًا.
  • customerاختياري: بريد العميل email واسمه name. يظهران لك في تفاصيل الفاتورة ولا يظهران في صفحة الدفع. إذا فعّلت إيصال البريد للمشروع، يصل إلى هذا البريد إيصال واحد بعد تأكيد الدفع. يبقى webhook الموقّع وحده إشارة تسليم الطلب.

استخدم روابط تبدأ بـ https://، فصفحة الدفع لا تعرض أي رابط عودة آخر.

حقول من الاستجابة
{
  "id": "00000000-0000-4000-8000-000000000042",
  "livemode": false,
  "status": "pending",
  "environment": "test",
  "amount": {
    "base_atomic": "50000000",
    "payable_atomic": "50000001",
    "display_decimals": 6
  }
}

2. نفّذ دفعة وهمية

POST /v1/test/invoices/{id}/simulate
curl -X POST "$NBTA_BASE_URL/v1/test/invoices/$INVOICE_ID/simulate" \
  -H "Authorization: Bearer $NBTA_API_KEY" \
  -H "Idempotency-Key: order-2026-0042-simulate" \
  -H "Content-Type: application/json" \
  --data '{"scenario":"paid_immediately"}'

تستخدم بيئة الاختبار نقطة النهاية نفسها. أنشئ فاتورة، ثم نفّذ paid_immediately واقرأ الحالة المحفوظة من الخادم.

افتح مختبر الدفع

3. تحقق من النتيجة

GET /v1/invoices/{id}
curl "$NBTA_BASE_URL/v1/invoices/$INVOICE_ID" \
  -H "Authorization: Bearer $NBTA_API_KEY"

تحقق من id وlivemode: false وstatus: paid في الاستجابة المحفوظة. المحاكاة لا تثبت وصول Webhook إلى خادمك؛ افحص محاولات التسليم وتحقق من التوقيع في تكامل منفصل.

تنبيهات تيليغرام

من الإعدادات، اضغط ربط تيليغرام وافتح البوت. بعدها تصلك رسالة على تيليغرام كلما دُفعت فاتورة، مع رابط يفتح تفاصيلها في لوحة التحكم. تستطيع إيقاف أي محادثة أو إرسال تجربة أو إزالتها من القسم نفسه.

افتح الإعدادات