شرح حالات الاستخدام

تقبل نقطة البيع في KAI-Pay مدفوعات البيتكوين عبر Lightning – عند منضدة البيع أو في كشك السوق أو في الفعاليات، على جهاز مخصص لنقطة البيع أو مباشرةً على هاتفك.

مزاياك

• يصل المال خلال ثوانٍ إلى محفظتك الخاصة ذات الحفظ الذاتي – ولا يحتفظ به أي طرف وسيط في أثناء ذلك.
• لا جهاز دفع بالبطاقات، ولا عقد، ولا تسجيل: يكفي متصفح على جهاز لوحي أو هاتف أو حاسوب محمول.
• آمنة لفريقك: أجهزة نقطة البيع تستطيع التحصيل فقط، ولا يمكنها أبدًا إرسال المال – مثالية لأجهزة الموظفين.
• يدفع عملاؤك بأي محفظة Lightning، في أي مكان في العالم.
• التحصيل بوحدة sat أو بعملات EUR وUSD وGBP وCHF وCAD وAUD وJPY – ويُثبَّت سعر الصرف لكل فاتورة.
• اختيار المنتجات بلمسة، وإيصال بصيغة PDF، وإقفال يومي وشهري مع تصدير CSV، واسترداد المبالغ مباشرةً في المحفظة.

كيف يعمل

1. في المحفظة، ضمن «نقطة البيع والإقفال»، أعِدّ نقطة البيع – افتحها على الجهاز نفسه أو انقلها إلى جهاز نقطة بيع عبر رمز QR.
2. اكتب المبلغ أو المس المنتجات، ثم اختر «تحصيل». تعرض نقطة البيع فاتورة Lightning على شكل رمز QR.
3. يمسح العميل الرمز ويدفع. تعرض نقطة البيع «تم الدفع» وإيصال دفع مرقّمًا.

نهجنا

نقطة البيع عن قصد صفحة مستقلة بلا مفاتيح: تستطيع إنشاء الفواتير، لكنها لا تستطيع تحريك المال. ولا تأخذ أسعار الصرف إلا حديثة (جُلبت قبل 5 دقائق على الأكثر) من mempool.space. ومع كل دفعة ترسل ملاحظة مشفّرة تتضمن نقطة البيع ورقم الإيصال والمبلغ والبنود، لا تستطيع قراءتها إلا محفظتك – ومنها تحسب المحفظة إقفالك.

من المفيد أن تعرف: نقطة البيع طرفية دفع، وليست آلة تسجيل نقدية؛ والإيصال إثبات للدفع، وليس إيصال آلة تسجيل نقدية. KAI-Pay نسخة تجريبية عامة.

شرح بالرسوم المتحركة · دليل نقطة البيع · فتح نقطة البيع

L402 معيار مفتوح يتيح للمواقع الإلكترونية وواجهات البرمجة (APIs) وغيرها من الخدمات الإلكترونية طلب مبالغ صغيرة مباشرةً عبر Lightning – بدلًا من حساب مستخدم أو اشتراك أو بطاقة ائتمان. يشير الاسم إلى رمز حالة HTTP رقم 402 «Payment Required» (الدفع مطلوب)؛ وقد طوّرت L402 شركة Lightning Labs (الاسم السابق: LSAT).

مزاياك

• لا حساب، ولا اشتراك، ولا بيانات بطاقة: ادفع واستخدم الخدمة فورًا.
• ادفع فقط مقابل ما تستخدمه فعلًا – بدءًا من بضع sat لكل طلب، بل حتى مبالغ تقل عن سنت واحد.
• يتم الدفع خلال ثوانٍ، في أي مكان في العالم وعلى مدار الساعة – دون بنك وسيط.
• خصوصية أكبر: لا تكشف الدفعة للخدمة اسمك ولا بيانات بطاقتك.
• يمكن للبرامج ووكلاء الذكاء الاصطناعي أيضًا الدفع بهذه الطريقة – فالبرنامج ليس لديه حساب مصرفي، لكنه يستطيع مع ذلك سداد فاتورة Lightning.

فيمَ يمكنك استخدامه

• الدفع لكل طلب بدلًا من الاشتراك: مثل البيانات، أو الأسعار، أو بيانات الخرائط أو الطقس، أو إجابات الذكاء الاصطناعي، أو القدرة الحاسوبية.
• فتح المحتوى والأدوات دون إنشاء حساب مستخدم.
• العمليات المؤتمتة: تدفع البرامج ووكلاء الذكاء الاصطناعي للخدمات عن كل استدعاء، دون الحاجة إلى إنشاء حساب ببيانات دخول لدى كل مزوّد.

كيف يعمل

1. ترسل أنت – أو برنامجك – طلبًا إلى الخدمة. وبدلًا من الإجابة تصل مطالبة L402: مفتاح وصول («Macaroon») وفاتورة Lightning مطابقة له.
2. تلصق المطالبة في المحفظة ضمن «إرسال» وتدفع. وكإيصال تحصل المحفظة على قيمة سرية («Preimage») لا يحصل عليها إلا من دفع.
3. يشكّل مفتاح الوصول والإيصال معًا إثبات الوصول. يرسله برنامجك في ترويسة Authorization؛ فتتحقق منه الخدمة وتتيح الإجابة.

نهجنا

في KAI-Pay، تُعدّ L402 وظيفة خاصة بالمحفظة وحدها: فالمحفظة لا تتصل بالخدمة بنفسها ولا تُبلغ KAI-Pay بأي شيء. ولا تدفع إلا إذا ثبت أن الفاتورة تعود إلى مفتاح الوصول، وبحد أقصى 1000 sat لكل دفعة (في المرحلة التجريبية)، ولا تدفع مرة أخرى مقابل وصول مدفوع مسبقًا ما دامت الدفعة مسجّلة في السجل على جهازك. وتعرض الخدمات غير المعروفة مع تحذير. وتحفظ إثبات الوصول على جهازك فقط. وبالنسبة إلى وكلاء الذكاء الاصطناعي: التحكم بدلًا من القيادة الآلية – راجع «إدارة ميزانية الذكاء الاصطناعي».

من المفيد أن تعرف: المحفظة تدفع الفاتورة فقط؛ أما إن كانت الخدمة ستتيح الوصول ولأي مدة، فالخدمة هي التي تقرر ذلك. وهي تحميك من فاتورة مستبدَلة، لا من مطالبة مزوّرة بالكامل – لذا تحقّق ممن صدرت. وهذه الميزة موجّهة اليوم أساسًا إلى المطورين والمهتمين بالتقنية.

شرح بالرسوم المتحركة · فتح المحفظة

استلام المدفوعات لمتجرك أو مشروعك أو موقعك الإلكتروني – برابط أو زر، دون عقد مع مزوّد خدمات دفع، ودون خادم خاص بك، ودون عقدة Lightning خاصة بك. وإن أردت، تُبلغ كل دفعة متجرك بإشعار موقَّع.

مزاياك

• لا عقد مع مزوّد خدمات دفع ولا تكاليف إعداد: يكفي رابط واحد.
• يذهب المال مباشرةً إلى محفظتك ذات الحفظ الذاتي.
• يعلم متجرك بكل دفعة واردة فورًا – بإشعار موقَّع بسرّ لا يعرفه إلا متجرك ومزوّد خدمة Spark. وإذا تحقّق متجرك من الإشعار، أمكنه تسجيل الطلبات تلقائيًا.
• المدفوعات عبر Lightning نهائية – لا عمليات استرجاع للمدفوعات (Chargebacks) كما في البطاقات.
• يدفع العملاء من جميع أنحاء العالم خلال ثوانٍ، بأي محفظة Lightning.

كيف يعمل

1. في المحفظة: القائمة ← ربط خدمة. هناك تجد رابط الدفع الخاص بك kai-pay.net/@yourname (لذلك تحتاج إلى عنوان Lightning، تُعدّه ضمن «استلام»).
2. اختياريًا: أدخل المبلغ ورقم الطلب – فيُنشئ الرابط فورًا فاتورة مطابقة. انسخ الرابط أو الزر الجاهز (HTML، بلا سكربت) إلى موقعك الإلكتروني أو فواتيرك أو رسائل بريدك الإلكتروني.
3. للتأكيدات التلقائية: ضمن «إشعار إلى متجرك» أدخل عنوان متجرك (https://…)، وأكّد، ثم انسخ السرّ المعروض إلى متجرك. ومنذ ذلك الحين يرسل مزوّد خدمة Spark، أي Lightspark، إشعارًا موقَّعًا إلى هناك مع كل دفعة Lightning واردة.
4. يتحقق متجرك من التوقيع ويربط الدفعة بالطلب – وتجد الطريقة أدناه في «للمطورين».

نهجنا

بلا وسيط: صفحة الدفع لا تحتفظ بشيء، والإشعارات تذهب مباشرةً من مزوّد خدمة Spark إلى متجرك – ولا يراها خادمنا. وتعرض المحفظة سرّ التوقيع مرة واحدة فقط ولا تحفظه.

للمطورين

فاتورة لكل طلب: استعلم من خادم الدفع الخاص بعنوان Lightning لديك (LNURL-pay، LUD-06): أولًا /.well-known/lnurlp/yourname على نطاقه، ثم callback الخاص به مع amount (بوحدة millisatoshi) واختياريًا comment. يتضمن الرد الفاتورة (pr) وعنوان تحقق (verify، LUD-21). احفظ مع الطلب قيمة payment_hash الخاصة بالفاتورة.

الإشعار يصل كطلب POST بصيغة JSON. تحقّق أولًا من الترويسة X-Spark-Signature: قيمة HMAC-SHA256 للمحتوى غير المعدَّل باستخدام سرّك، بالصيغة الست عشرية (hex). بعد ذلك يجب أن يكون type = SPARK_LIGHTNING_RECEIVE_FINISHED، وstatus = TRANSFER_COMPLETED، وأن تكون قيمة SHA-256 للحقل payment_preimage هي payment_hash الخاص بالفاتورة المدفوعة (الحقول وفق توثيق Breez حول Webhooks). مثال لبيئة Node.js:

import { createHash, createHmac, timingSafeEqual } from 'node:crypto'

// raw: the unmodified request body (Buffer); secret: the secret shown once in the wallet
// orders: your order store; amountMatches(order, amount): compares in the same unit (amount = { value, unit })
// Returns 'reject' (answer 401), null (nothing to do - answer 200) or the booked order (answer 200).
export function kaiPayPayment(raw, signatureHeader, secret, orders) {
  const expected = createHmac('sha256', secret).update(raw).digest()
  const given = Buffer.from(String(signatureHeader ?? '').replace(/^sha256=/, ''), 'hex')
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return 'reject'  // wrong seal: answer 401
  // From here on always answer 200 - the notification comes for every Lightning payment of the wallet.
  const e = JSON.parse(raw)
  if (e.type !== 'SPARK_LIGHTNING_RECEIVE_FINISHED' || e.status !== 'TRANSFER_COMPLETED' || !e.payment_preimage) return null
  // SHA-256 of the preimage = payment_hash of the paid invoice
  const paymentHash = createHash('sha256').update(Buffer.from(e.payment_preimage, 'hex')).digest('hex')
  const order = orders.byPaymentHash(paymentHash)
  if (!order) return null                                    // not one of your invoices (e.g. a private payment)
  if (order.paid) return order                               // repeated notification: already booked
  if (!amountMatches(order, e.invoice_amount)) return null   // wrong amount: do not release, check by hand
  return orders.markPaid(order)                              // markPaid must be atomic: only the first call books
}

أجب برمز HTTP 401 فقط إذا كان التوقيع غير صحيح، وفي غير ذلك دائمًا برمز 200 – حتى على إشعار متكرر أو على دفعة لا تخص أي طلب؛ ولا تُسجَّل الدفعة إلا مرة واحدة. المبلغ موجود في invoice_amount مع وحدته (unit)؛ قارنه بالطلب بالوحدة نفسها. وعند الشك، يؤكد عنوان التحقق الخاص بالفاتورة (settled: true) وصول الدفعة.

من المفيد أن تعرف: يصل الإشعار مع كل دفعة Lightning واردة إلى المحفظة، بما فيها الدفعات الخاصة – لذا يُفضَّل أن تستخدم محفظة مستقلة للمتجر. روابط الدفع kai-pay.net/@name متاحة لعناوين Lightning لدى breez.tips. KAI-Pay نسخة تجريبية عامة.

شرح بالرسوم المتحركة · فتح في المحفظة

يمكن لمساعد ذكاء اصطناعي – مثل وكيل شخصي أو سكربت أو KAI – أن يقترح عليك مدفوعات. أنت تحدد لمن تُدفع وكم في اليوم وفي الشهر؛ وكل دفعة تؤكدها بنفسك.

مزاياك

• دع المدفوعات المتكررة تُجهَّز لك، ولا يحدث شيء من دونك: الاقتراح لا يدفع أبدًا من تلقاء نفسه.
• حدود ثابتة: الدفع فقط إلى مستلمين سمحت بهم، وضمن ميزانية يومية وشهرية (شاملة الرسوم).
• مقاوم للتزوير: كل اقتراح موقَّع؛ وتتحقق المحفظة من المرسِل والمستلم والميزانية والصلاحية، ولا تقبل أي اقتراح إلا مرة واحدة.
• رؤية كاملة: تعرض المحفظة لكل مساعد مقدار ما استُهلك من الميزانية اليومية والشهرية.

كيف تجرّبه

1. افتح المحفظة: القائمة ← ميزانية الذكاء الاصطناعي.
2. المس «إنشاء مساعد تجريبي». وأدخل كمستلم مسموح به عنوانًا تريد فعلًا الدفع إليه – مثل محفظة ثانية لك – وحدّد ميزانية يومية وشهرية صغيرة. ثم احفظ.
3. لدى المساعد المس «إنشاء اقتراح»، وأدخل المبلغ، ثم «إنشاء الاقتراح والتحقق منه». سترى الآن ما كان سيرسله إليك مساعد ذكاء اصطناعي: المرسِل والمستلم والمبلغ والميزانية المتبقية.
4. «متابعة إلى الدفع»: تتحقق المحفظة من المستلم والميزانية مرة أخرى وتعرض الرسوم. ولا يتم الدفع إلا عند «تأكيد وإرسال» – وبعدها تنخفض الميزانية بمقدار المبلغ والرسوم. وتُرفض أي محاولة ثانية بالاقتراح نفسه.

ربط مساعد

إذا أعطاك مساعد رمزًا أو رابطًا أو رمز QR (مع KAI في Telegram: /vorschlag quelle)، فافتحه من القائمة ← ميزانية الذكاء الاصطناعي ← «ربط مساعد»، وقارن البصمة، وحدّد المستلمين والميزانية. تصل اقتراحاته على شكل رابط وتفتح صفحة التحقق مباشرةً.

نهجنا

التحكم بدلًا من القيادة الآلية: لا يحصل المساعد أبدًا على وصول إلى مفاتيحك، ولا يستطيع إلا الاقتراح. ولا تقبل المحفظة عن قصد فواتير Lightning في الاقتراحات، لأنها لا تستطيع التحقق من مستلمها. وهكذا تستفيد من مزايا الذكاء الاصطناعي دون التخلي عن السيطرة على مالك.

للمطورين: ربط وكيلك الخاص

أنشئ مساعدًا في المحفظة واحفظ «ملف الوصول للوكلاء» الخاص به. يستخدمه وكيلك – سواء كان سكربتًا أو أتمتة أو ذكاءً اصطناعيًا قادرًا على تنفيذ الشيفرة – لإنشاء اقتراحات موقَّعة. يُخرج هذا السكربت (Node.js 20 أو أحدث، دون حزم) رابطًا يرسله إليك وكيلك وتفتحه في المحفظة:

// kai-vorschlag.mjs - signed KAI-Pay proposal from the access file (Node.js 20+, no packages)
// node kai-vorschlag.mjs access.json name@provider.com 2100 "Server bill October"
import { readFileSync } from 'node:fs'
const [file, to, sat, purpose] = process.argv.slice(2)
const acc = JSON.parse(readFileSync(file, 'utf8'))
const b64u = (b) => Buffer.from(b).toString('base64url')
const now = Math.floor(Date.now() / 1000)
const p = { v: 1, id: b64u(crypto.getRandomValues(new Uint8Array(16))), src: acc.id,
  iat: now, exp: now + 24 * 3600, to, sat: Number(sat), purpose }
const signed = 'kaiprop1.' + b64u(JSON.stringify(p))
const key = await crypto.subtle.importKey('pkcs8', Buffer.from(acc.pkcs8, 'base64url'),
  { name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign'])
const sig = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, key, new TextEncoder().encode(signed))
console.log(acc.app + '#kaiprop=' + encodeURIComponent(signed + '.' + b64u(new Uint8Array(sig))))

يبقى الاقتراح صالحًا 7 أيام كحد أقصى، ويحدد وجهة (عنوان Lightning أو Bitcoin، وليس فاتورة)، ومبلغًا بوحدة sat (بحد أقصى 1,000,000)، وغرضًا (بحد أقصى 140 حرفًا). من يملك ملف الوصول يستطيع أن يرسل إليك اقتراحات، لكنه لا يستطيع دفع أي شيء – لذا لا تعطه إلا لوكيلك الخاص.

من المفيد أن تعرف: هذه الميزة في المرحلة التجريبية. غرض الاقتراح يحدده المساعد؛ والمحفظة لا تتحقق منه.

شرح بالرسوم المتحركة · فتح في المحفظة