Pay.sh

اقبل المدفوعات باستخدام Pay.sh

يمكنك قبول المدفوعات على طلبات API عبر Pay.sh من خلال إعداد خادم Pay. ثبّت Pay باستخدام:

brew install pay

أو

npm install -g @solana/pay

تحقق من التثبيت باستخدام:

pay --version

ستقوم سلسلة الأدوات بإعداد عنوانك تلقائيًا. شغّل الأمر التالي لإعداد محفظتك وتعبئتها:

pay setup

إعداد الخادم التجريبي

يمكنك البدء في قبول المدفوعات عن طريق تشغيل الخادم الخاص بك. يمكنك مشاهدة الخادم التجريبي في العمل باستخدام:

pay server demo

يؤدي هذا وظيفتين: يشغّل خادم Pay مباشرةً يمكنك الاستعلام عنه عبر طلب HTTP، ويُنشئ ملف pay-demo.yml في دليلك الحالي.

يتم تكوين جميع مسارات API عبر إعداد YAML الخاص بـ endpoints. لقبول المدفوعات، يجب عليك إضافة سمة metering:. وقد تم تنفيذ مسار /api/v1/reports/usage كمثال توضيحي لك:

endpoints:
  - method: GET
    path: "api/v1/reports/usage"
    resource: "reports"
    description: "Usage report — flat fee, no splits."
    metering:
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.01

يمكنك اختبار عمل المدفوعات عن طريق تشغيل الأمر التالي كعميل في محطة طرفية أخرى:

pay --sandbox curl http://127.0.0.1:1402/api/v1/reports/usage

يمكنك الاطلاع على مزيد من المعلومات حول كيفية تحديد الأسعار في وثائق Pay.sh - البناء مع Pay > التسعير

تعرف على المزيد حول إعداد Pay.sh في بيئة الإنتاج في وثائق تكوين Pay.sh.

أنشئ اشتراكات باستخدام Pay.sh

يمكنك إعداد الاشتراكات عبر Pay.sh من خلال تهيئة عميل Pay على جهازك أو إعداد خادم Pay. قم بتثبيت Pay باستخدام:

brew install pay

أو

npm install -g @solana/pay

تحقق من التثبيت باستخدام:

pay --version

ستقوم سلسلة الأدوات بإعداد عنوانك تلقائيًا. شغّل الأمر التالي لإعداد محفظتك وتعبئتها:

pay setup

الاشتراكات كعميل

يشترك المستخدمون في نقاط نهاية API المحمية بالاشتراك عن طريق استدعاء pay بالطريقة المعتادة. يقع على عاتق الـ API إرسال تفاصيل الاشتراك في استجابة 402 Status الأولية. يتولى Pay إدارة الاشتراك تلقائيًا، بما في ذلك استدعاء التعليمات على برنامج سولانا SPL Subscriptions.

يمكن للمستخدمين إدارة اشتراكاتهم باستخدام الأوامر التالية:

pay subscriptions                       # default: list + show available subcommands
pay subscriptions list                  # same, scriptable
pay subscriptions list --network mainnet
pay subscriptions list --json

يمكنك الاطلاع على مزيد من المعلومات حول إدارة اشتراكاتك كمستخدم في Pay.sh > استخدام Pay > وثائق إدارة الاشتراكات.

إدارة الاشتراكات كمزوّد (عرض توضيحي)

تتيح خوادم Pay تهيئة المشتركين واشتراكاتهم لكل نقطة نهاية. فيما يلي مثال على نقطة نهاية تستخدم pay يمكنك تجربته مع مشروعك:

# monthly.yml
name: Subscriptions Example
subdomain: subscriptions-example
title: "Subscription Example"
description: "Demo Subscriptions"
category: ai_ml
version: v1
routing:
  type: respond
operator:
  currencies:
    usd: ["USDC", "USDT", "CASH"]
  network: "localnet"
  fee_payer: true
  challenge_binding_secret: d858d9104afd728f58a1f73d806dd75d8f32ebd37c9707145816b490e8631d41
  # insert your own challenge_binding_secret here. use `openssl rand -hex 32`

endpoints:
  - method: GET
    path: "api/v1/pro/feed"
    resource: "pro-feed"
    description: "Pro feed — monthly subscription, 30-day billing period."
    subscription:
      period: "30d"
      price_usd: 9.99
      currency: USDC
      plan_id_numeric: 1

يتعامل Pay مع الاشتراكات باستخدام السمة subscription: في مواصفات endpoints بصيغة YAML. وهذا يختلف عن السمة metering: المستخدمة لنقاط نهاية الدفع لكل استخدام.

يؤدي تشغيل الخادم في المثال أعلاه إلى إنشاء نقطة نهاية تُسمى api/v1/pro/feed تتطلب من المستخدم إجراء مدفوعات دورية بقيمة 9.99 USDC كل 30 يومًا.

يمكنك تجربة ذلك بتشغيل الأمر التالي:

pay server start monthly.yml

سيطالبك تشغيل هذا الأمر بإنشاء خطة. يؤدي ذلك إلى إنشاء الخطة وتحديث ملف yml. إذا كنت ستستخدمه مجددًا، احتفظ بعنوان الخطة واستخدمه في إعداداتك أثناء إجراء التغييرات.

يمكنك اختبار أن الاشتراكات تعمل بشكل صحيح عن طريق تشغيل الأوامر التالية كعميل في طرفية أخرى:

# First call — activates the subscription, $9.99 USDC charge settles.
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed

# Same call within 30 days — no payment prompt, just the response.
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed

يجب أن ترى حالة OK كاستجابة على النحو التالي:

{ "status": "ok" }

يمكنك معرفة المزيد حول إدارة الاشتراكات على خادم Pay عبر Pay.sh > Building with Pay > Subscriptions > YAML Specification docs.