البيانات الوصفية
أرفق بياناتك الخاصة على شكل مفاتيح وقيم بعمليات الدفع، واقرأها مجددًا في استجابات الـ API والـ Webhooks.
يتيح لك الحقل metadata حفظ معلوماتك الخاصة على عملية الدفع، مثل رقم الطلب الداخلي أو معرّف العميل أو رمز الحملة. لا تستخدمه تيرا باي، بل تعيده كما هو في الكائن وفي نتائج القوائم وفي كل Webhook.
{
"amount": 12500,
"currency": "KWD",
"return_url": "https://shop.example.com/thanks",
"metadata": {
"order_id": "1042",
"customer_id": "cus_8812",
"campaign": "ramadan-2027"
}
}القواعد
| القاعدة | الحد |
|---|---|
| عدد المفاتيح | حتى 20 |
| المفاتيح | نصوص حتى 40 حرفًا |
| القيم | نصوص حتى 500 حرف. حوّل الأرقام والقيم المنطقية إلى نصوص ("42" و"true"). لا يُسمح بالكائنات المتداخلة أو المصفوفات. |
الطلبات المخالفة لهذه القواعد تفشل بالخطأ 422 validation_error، ويُوصف الخطأ في details.fields تحت metadata (مفاتيح كثيرة أو مفتاح طويل) أو تحت metadata.<key> (قيمة ليست نصًا).
استخدامات مناسبة
- ربط عملية الدفع بسجلات أنظمتك (
order_idوcart_idوinvoice_number). - تسجيل مصدر عملية الدفع (
source: "mobile-app"وcampaign). - مطابقة التحويلات والتصدير مع نظام ERP أو النظام المحاسبي.
ما لا يجب حفظه
لا تضع بيانات حساسة في metadata: لا أرقام بطاقات ولا CVV ولا كلمات مرور ولا أرقام بطاقات مدنية ولا معلومات صحية. البيانات الوصفية ظاهرة لكل فريقك في لوحة التحكم وتُرسل إلى نقاط الـ Webhook.
reference أم metadata؟
استخدم reference لمعرّفك الرئيسي الوحيد، وهو عادةً رقم الطلب: يمكنك التصفية به عبر GET /v1/payments?reference=1042، ويظهر في بحث لوحة التحكم وفي ملفات التصدير. واستخدم metadata لكل ما عدا ذلك.