بيع الرصيد

يناسب الرصيد كل ما يُباع حسب الاستخدام: الرموز، والصور، والدقائق، وعمليات البحث. يدفع المشتري ثمن باقة بالعملات المشفرة؛ وتستهلك منها مع كل استدعاء؛ وحين ينفد الرصيد يشحن من صفحته الخاصة. لا يُخصم شيء تلقائيًا — المشتري يدفع بنفسه دائمًا — ولا يأخذ Perly شيئًا من الشحن.

الإعداد

1. 1

   أنشئ منتجًا وباقات

   Dashboard → Products → New، ثم New price → Credit pack: مثلًا 1 000 وحدة مقابل $10، و5 000 مقابل $40. أو pay.prices.create({ product, model: "credit_pack", unit_amount: 1000, credits: 1000 }).

2. 2

   اختر متى يعرف المشتري برصيده

   في صفحة المنتج، في قسم Credits: حد التنبيه، ورسالة للمشتري، وAny amount — عدد N من باقة واحدة، ليتمكن المشتري من الشحن بـ $25 لا بباقة ثابتة فقط.

3. 3

   امنح كل مشترٍ عميلًا

   أنشئ عميلًا لكل مستخدم بمعرّفك: pay.customers.create({ email, external_id: user.id }). بعدها تقبل SDK هذا المعرّف.

استهلك، تحقق، اشحن

import { PerlyPay, InvalidRequestError } from "perly-pay";
const pay = new PerlyPay(process.env.PERLY_PAY_SECRET_KEY);

// Before the work: enough left?
const { balance, top_up_url } = await pay.credits.balance(user.id);

// After it: spend. The same idempotencyKey never spends twice.
try {
  await pay.credits.consume(user.id, 3, { action: "chat", idempotencyKey: request.id });
} catch (e) {
  if (e instanceof InvalidRequestError && e.code === "insufficient_credits") {
    return { error: "Out of credits", topUp: await pay.credits.topUpUrl(user.id) };
  }
  throw e;
}

• العميل هو معرّف cus_… أو بريد إلكتروني أو معرّفك الخاص له (external_id). حدد product إن كنت تبيع رصيدًا لعدة منتجات.
• الاستهلاك ذرّي ولا ينزل تحت الصفر أبدًا: لن تمر عمليتان متزامنتان على الرصيد نفسه. النقص هو insufficient_credits (409)، ولا يُستهلك شيء.
• مرّر معرّف طلبك كمفتاح عدم تكرار. الإعادة — بعد انتهاء المهلة، أو عطل، أو حتى في اليوم التالي — تعيد الاستهلاك الأول، ولا تستهلك مرة أخرى.
• action هو وسمك (chat، image.hd، api/search). تجمع صفحة المنتج الاستهلاك حسب الإجراء وحسب العميل.

صفحة الشحن

top_up_url صفحة المشتري الخاصة، وهي نفسها في كل مرة: تُظهر الرصيد وباقاتك بمظهر صفحة الدفع لديك، وتفتح فاتورة عادية حين يختار المشتري باقة. فور دفعها يُضاف الرصيد مرة واحدة. اعرض الرابط في التطبيق، أو في خطأ «نفد الرصيد»، أو أرسله — وفي بوابة المشتري أيضًا زر اشحن.

حين ينفد الرصيد

كلاهما يحمل العميل في data.object، إضافة إلى data.product وdata.balance. إن كان الحد محددًا والرسالة مفعّلة، يتلقى المشتري أيضًا رسالة واحدة برابط الشحن — مرة في اليوم على الأكثر. في وضع الاختبار تذهب الرسائل إلى فريقك فقط.