البدء السريع

أنشئ أول عملية دفع تجريبية، وادفعها في صفحة الدفع التجريبية، وتحقّق من النتيجة، في نحو خمس دقائق.

يأخذك هذا الدليل من الصفر إلى عملية دفع تجريبية مؤكدة. تحتاج إلى حساب في تيرا باي (سجّل من app.teyra.co) وإلى سطر الأوامر. وضع الاختبار متاح فور التسجيل، قبل اعتماد حسابك.

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

احصل على مفتاح الاختبار السري

افتح المطورون ← مفاتيح API في لوحة التحكم وأنشئ مفتاحًا في وضع الاختبار. انسخ المفتاح السري: يبدأ بـ sk_test_ ويُعرض مرة واحدة فقط.

احفظه في متغير بيئة على خادمك:

export TEYRA_SECRET_KEY="sk_test_..."

مكان المفاتيح السرية هو خادمك فقط. لا تضعها أبدًا في صفحة ويب أو تطبيق جوال أو مستودع عام.

أنشئ عملية دفع

استدعِ POST /v1/payments بالمبلغ بالوحدات الصغرى. القيمة 12500 بعملة KWD تعني 12.500 دينار كويتي.

curl https://api.teyra.co/v1/payments \
  -H "Authorization: Bearer $TEYRA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": 12500,
    "currency": "KWD",
    "return_url": "https://shop.example.com/thanks",
    "description": "Order #1042",
    "reference": "1042"
  }'

الاستجابة كائن Payment بالحالة requires_payment:

{
  "id": "pay_01JBX4T9W2",
  "object": "payment",
  "livemode": false,
  "amount": 12500,
  "currency": "KWD",
  "status": "requires_payment",
  "checkout_url": "https://api.teyra.co/checkout/pay_01JBX4T9W2",
  "return_url": "https://shop.example.com/thanks",
  "expires_at": "2026-10-28T15:07:00.000Z"
}

افتح checkout_url في المتصفح. ستظهر صفحة الدفع في تيرا باي مع شارة TEST، وفيها اسم نشاطك التجاري والوصف والمبلغ، وحقول بطاقة آمنة متصلة ببيئة الاختبار لدى معالج البطاقات. لا تنتقل أي أموال حقيقية.

ادفع ببطاقة اختبار. عند نجاح الدفع تُوجَّه إلى return_url:

https://shop.example.com/thanks?payment_id=pay_01JBX4T9W2&status=succeeded

تحقّق من الدفع من خادمك

قيم الرابط مجرد إشارة، ويستطيع أي شخص كتابتها بنفسه. قبل تنفيذ الطلب، اجلب عملية الدفع بمفتاحك السري وتحقق من حالتها.

curl https://api.teyra.co/v1/payments/pay_01JBX4T9W2 \
  -H "Authorization: Bearer $TEYRA_SECRET_KEY"

يجب أن ترى "status": "succeeded" مع قيمة في paid_at. وتظهر عملية الدفع أيضًا في لوحة التحكم ضمن المدفوعات.

ما التالي

أضف نقطة Webhook لتعرف بنتيجة الدفع حتى لو لم يعد العميل إلى موقعك.
اقرأ معالجة رابط العودة لبناء صفحة عودة جاهزة للإنتاج.
عندما تكون جاهزًا، انتقل إلى الوضع الحي.