Giải thích các cách dùng

Quầy thu ngân KAI-Pay nhận thanh toán bằng bitcoin qua Lightning – tại quầy bán hàng, sạp chợ hay sự kiện, trên một thiết bị thu ngân riêng hoặc ngay trên điện thoại của bạn.

Lợi ích cho bạn

• Tiền về ví tự lưu ký của chính bạn chỉ trong vài giây – không ai giữ hộ ở giữa.
• Không cần máy quẹt thẻ, không hợp đồng, không đăng ký: chỉ cần một trình duyệt trên máy tính bảng, điện thoại hoặc laptop.
• An toàn cho đội ngũ của bạn: thiết bị thu ngân chỉ có thể thu tiền, không bao giờ gửi tiền đi được – lý tưởng cho thiết bị của nhân viên.
• Khách hàng trả tiền bằng bất kỳ ví Lightning nào, ở khắp nơi trên thế giới.
• Thu tiền bằng sat hoặc bằng EUR, USD, GBP, CHF, CAD, AUD và JPY – tỷ giá được chốt cố định cho từng hóa đơn.
• Chạm chọn mặt hàng, biên lai PDF, chốt sổ ngày và tháng kèm xuất CSV, hoàn tiền ngay trong ví.

Cách hoạt động

1. Trong ví, vào “Quầy thu ngân & chốt sổ” để thiết lập quầy thu ngân – mở ngay trên cùng thiết bị hoặc chuyển sang thiết bị thu ngân bằng mã QR.
2. Nhập số tiền hoặc chạm chọn mặt hàng rồi chọn “Thu tiền”. Quầy thu ngân hiển thị hóa đơn Lightning dưới dạng mã QR.
3. Khách quét mã và thanh toán. Quầy thu ngân hiển thị “Đã thanh toán” cùng một biên lai thanh toán có đánh số.

Cách tiếp cận của chúng tôi

Quầy thu ngân được cố ý làm thành một trang riêng, không chứa khóa: nó có thể tạo hóa đơn nhưng không thể chuyển tiền. Nó chỉ dùng tỷ giá mới (lấy cách đây tối đa 5 phút) từ mempool.space. Kèm mỗi khoản thanh toán, nó gửi một ghi chú được mã hóa gồm quầy thu ngân, số biên lai, số tiền và các dòng hàng mà chỉ ví của bạn đọc được – từ đó ví tính ra báo cáo chốt sổ của bạn.

Nên biết: Quầy thu ngân là thiết bị đầu cuối thanh toán, không phải máy tính tiền; biên lai là bằng chứng thanh toán, không phải phiếu tính tiền. KAI-Pay đang ở giai đoạn beta công khai.

Giải thích bằng hoạt hình · Hướng dẫn quầy thu ngân · Mở quầy thu ngân

L402 là một tiêu chuẩn mở cho phép các trang web, giao diện lập trình (API) và các dịch vụ trực tuyến khác thu những khoản tiền nhỏ trực tiếp qua Lightning – thay vì tài khoản người dùng, gói đăng ký hay thẻ tín dụng. Tên gọi này bắt nguồn từ mã trạng thái HTTP 402 “Payment Required” (yêu cầu thanh toán); L402 do Lightning Labs phát triển (tên cũ: LSAT).

Lợi ích cho bạn

• Không tài khoản, không gói đăng ký, không thông tin thẻ: thanh toán là dùng được ngay.
• Chỉ trả cho những gì bạn thực sự dùng – từ vài sat mỗi lần truy vấn, kể cả những khoản dưới một cent.
• Thanh toán xong trong vài giây, trên toàn thế giới và suốt ngày đêm – không có ngân hàng đứng giữa.
• Riêng tư hơn: qua khoản thanh toán, dịch vụ không biết tên bạn cũng như thông tin thẻ.
• Cả chương trình máy tính và tác tử AI cũng có thể thanh toán theo cách này – một chương trình không có tài khoản ngân hàng, nhưng vẫn có thể trả một hóa đơn Lightning.

Bạn có thể dùng vào việc gì

• Trả tiền theo từng lần truy vấn thay vì gói đăng ký: ví dụ dữ liệu, giá thị trường, dữ liệu bản đồ hoặc thời tiết, câu trả lời của AI hoặc năng lực tính toán.
• Mở khóa nội dung và công cụ mà không cần tạo tài khoản người dùng.
• Quy trình tự động: chương trình và tác tử AI trả tiền dịch vụ theo từng lần gọi, không cần tạo tài khoản kèm thông tin đăng nhập ở từng nhà cung cấp.

Cách hoạt động

1. Bạn – hoặc chương trình của bạn – gửi yêu cầu đến dịch vụ. Thay vì câu trả lời, bạn nhận được một yêu cầu thanh toán L402: một khóa truy cập (“Macaroon”) và một hóa đơn Lightning tương ứng.
2. Bạn dán yêu cầu này vào ví ở mục “Gửi” rồi thanh toán. Ví nhận được một giá trị bí mật (“Preimage”) làm biên nhận – chỉ người đã thanh toán mới có được giá trị này.
3. Khóa truy cập cùng với biên nhận tạo thành bằng chứng truy cập. Chương trình của bạn gửi kèm bằng chứng này dưới dạng Authorization-Header; dịch vụ kiểm tra rồi trả về câu trả lời.

Cách tiếp cận của chúng tôi

Trong KAI-Pay, L402 thuần túy là một chức năng của ví: ví không tự gọi đến dịch vụ và không báo gì cho KAI-Pay. Ví chỉ thanh toán khi hóa đơn được chứng minh là thuộc về khóa truy cập, tối đa 1.000 sat mỗi lần thanh toán (beta), và không trả lại lần nữa cho một quyền truy cập đã trả, chừng nào khoản thanh toán đó còn trong lịch sử trên thiết bị của bạn. Với dịch vụ lạ, ví hiển thị kèm cảnh báo. Ví chỉ lưu bằng chứng truy cập trên thiết bị của bạn. Đối với tác tử AI: kiểm soát thay vì lái tự động – xem “Quản lý ngân sách AI”.

Nên biết: Ví chỉ trả hóa đơn; dịch vụ có mở quyền truy cập hay không và trong bao lâu là do dịch vụ quyết định. Ví bảo vệ bạn khỏi một hóa đơn bị đánh tráo, nhưng không bảo vệ khỏi một yêu cầu bị giả mạo hoàn toàn – vì vậy hãy kiểm tra xem yêu cầu đến từ ai. Hiện nay tính năng này chủ yếu dành cho nhà phát triển và những người quan tâm đến kỹ thuật.

Giải thích bằng hoạt hình · Mở ví

Nhận thanh toán cho cửa hàng, dự án hay trang web của bạn – bằng một liên kết hoặc nút bấm, không cần hợp đồng với nhà cung cấp dịch vụ thanh toán, không cần máy chủ riêng và không cần nút Lightning riêng. Nếu bạn muốn, mỗi khoản thanh toán sẽ được báo về cửa hàng của bạn kèm chữ ký.

Lợi ích cho bạn

• Không hợp đồng với nhà cung cấp dịch vụ thanh toán, không phí thiết lập: chỉ cần một liên kết.
• Tiền về thẳng ví tự lưu ký của bạn.
• Cửa hàng của bạn biết ngay mỗi khoản tiền về – được ký bằng một mã bí mật mà chỉ cửa hàng của bạn và nhà cung cấp dịch vụ Spark biết. Nếu cửa hàng của bạn kiểm tra thông báo, cửa hàng có thể tự động ghi nhận đơn hàng.
• Thanh toán qua Lightning là không thể đảo ngược – không có bồi hoàn (chargeback) như với thẻ.
• Khách hàng khắp thế giới thanh toán trong vài giây, bằng bất kỳ ví Lightning nào.

Cách hoạt động

1. Trong ví: Menu → Kết nối dịch vụ. Tại đó có liên kết thanh toán của bạn kai-pay.net/@tencuaban (bạn cần một địa chỉ Lightning, thiết lập ở mục “Nhận”).
2. Tùy chọn: nhập số tiền và mã đơn hàng – liên kết sẽ tạo ngay một hóa đơn tương ứng. Sao chép liên kết hoặc nút bấm làm sẵn (HTML, không có script) vào trang web, hóa đơn hoặc email của bạn.
3. Để xác nhận tự động: ở mục “Thông báo đến cửa hàng của bạn”, nhập địa chỉ cửa hàng của bạn (https://…), xác nhận rồi sao chép mã bí mật hiển thị vào cửa hàng. Từ đó trở đi, nhà cung cấp dịch vụ Spark là Lightspark sẽ gửi một thông báo có chữ ký đến địa chỉ đó mỗi khi có tiền Lightning về.
4. Cửa hàng của bạn kiểm tra chữ ký và gán khoản thanh toán cho đơn hàng – cách làm có ở mục “Dành cho nhà phát triển” bên dưới.

Cách tiếp cận của chúng tôi

Không có bên trung gian: trang thanh toán không giữ gì cả, và thông báo đi thẳng từ nhà cung cấp dịch vụ Spark đến cửa hàng của bạn – máy chủ của chúng tôi không thấy chúng. Ví chỉ hiển thị mã bí mật dùng để ký đúng một lần và không lưu lại.

Dành cho nhà phát triển

Mỗi đơn hàng một hóa đơn: hỏi máy chủ thanh toán của địa chỉ Lightning của bạn (LNURL-pay, LUD-06): trước tiên là /.well-known/lnurlp/tencuaban trên tên miền của máy chủ đó, sau đó gọi callback của nó với amount (tính bằng millisatoshi) và tùy chọn comment. Phản hồi chứa hóa đơn (pr) và một địa chỉ kiểm tra (verify, LUD-21). Lưu payment_hash của hóa đơn cùng với đơn hàng.

Thông báo đến dưới dạng POST với JSON. Trước tiên hãy kiểm tra header X-Spark-Signature: HMAC-SHA256 của nội dung nguyên vẹn (chưa sửa đổi) với mã bí mật của bạn, dạng hex. Sau đó: type = SPARK_LIGHTNING_RECEIVE_FINISHED, status = TRANSFER_COMPLETED, và SHA-256 của payment_preimage chính là payment_hash của hóa đơn đã thanh toán (các trường theo tài liệu của Breez về webhook). Ví dụ cho 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
}

Chỉ trả lời HTTP 401 khi chữ ký sai, còn lại luôn trả lời 200 – kể cả với thông báo lặp lại hoặc khoản tiền không thuộc đơn hàng nào; mỗi khoản chỉ được ghi nhận một lần. Số tiền nằm trong invoice_amount kèm đơn vị (unit); hãy so sánh với đơn hàng theo cùng đơn vị. Khi còn nghi ngờ, địa chỉ kiểm tra của hóa đơn (settled: true) sẽ xác nhận khoản tiền đã về.

Nên biết: Thông báo được gửi với mọi khoản tiền Lightning về ví, kể cả các khoản riêng tư – tốt nhất hãy dùng một ví riêng cho cửa hàng. Liên kết thanh toán kai-pay.net/@ten hiện có cho các địa chỉ Lightning tại breez.tips. KAI-Pay đang ở giai đoạn beta công khai.

Giải thích bằng hoạt hình · Mở trong ví

Một trợ lý AI – chẳng hạn một tác tử cá nhân, một script hoặc KAI – được phép đề xuất thanh toán cho bạn. Bạn quyết định trả cho ai và bao nhiêu mỗi ngày, mỗi tháng; mọi khoản thanh toán đều do chính bạn xác nhận.

Lợi ích cho bạn

• Để trợ lý chuẩn bị sẵn các khoản thanh toán định kỳ mà không có gì xảy ra sau lưng bạn: một đề xuất không bao giờ tự thanh toán.
• Giới hạn chặt chẽ: chỉ trả cho những người nhận bạn đã cho phép và trong phạm vi ngân sách ngày và tháng (đã gồm phí).
• Chống giả mạo: mỗi đề xuất đều được ký; ví kiểm tra người gửi, người nhận, ngân sách và thời hạn hiệu lực, và chỉ chấp nhận mỗi đề xuất một lần.
• Nắm rõ toàn bộ: với từng trợ lý, ví hiển thị đã dùng bao nhiêu trong ngân sách ngày và tháng.

Cách dùng thử

1. Mở ví: Menu → Ngân sách AI.
2. Chạm “Tạo trợ lý thử nghiệm”. Ở mục người nhận được phép, nhập một địa chỉ mà bạn thực sự muốn trả tiền – ví dụ một ví thứ hai của chính bạn – và đặt một ngân sách ngày và tháng nhỏ. Chọn “Lưu”.
3. Tại trợ lý đó, chạm “Tạo đề xuất”, nhập số tiền rồi chọn “Tạo và kiểm tra đề xuất”. Lúc này bạn thấy những gì một trợ lý AI sẽ gửi cho bạn: người gửi, người nhận, số tiền và ngân sách còn lại.
4. “Tiếp tục đến thanh toán”: ví kiểm tra lại người nhận và ngân sách, và hiển thị phí. Chỉ khi chọn “Xác nhận và gửi” thì mới thanh toán – sau đó ngân sách giảm đúng bằng số tiền cộng phí. Lần thử thứ hai với cùng đề xuất sẽ bị từ chối.

Kết nối một trợ lý

Nếu một trợ lý đã đưa cho bạn một mã, liên kết hoặc mã QR (với KAI trên Telegram: /vorschlag quelle), hãy mở nó tại Menu → Ngân sách AI → “Kết nối trợ lý”, so sánh dấu vân tay rồi đặt người nhận và ngân sách. Các đề xuất của trợ lý đó sẽ đến dưới dạng liên kết và mở thẳng trang kiểm tra.

Cách tiếp cận của chúng tôi

Kiểm soát thay vì lái tự động: trợ lý không bao giờ được truy cập khóa của bạn và chỉ có thể đề xuất. Ví cố ý không chấp nhận hóa đơn Lightning trong đề xuất, vì ví không thể kiểm tra người nhận của chúng. Nhờ vậy bạn tận dụng được lợi ích của AI mà không phải trao quyền kiểm soát tiền của mình.

Dành cho nhà phát triển: kết nối tác tử của riêng bạn

Tạo một trợ lý trong ví và lưu “Tệp truy cập cho tác tử” của trợ lý đó. Tác tử của bạn – một script, một quy trình tự động hoặc một AI có khả năng chạy mã – dùng tệp này để tạo các đề xuất có chữ ký. Script dưới đây (Node.js 20 trở lên, không cần gói nào) in ra một liên kết mà tác tử gửi cho bạn và bạn mở trong ví:

// 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))))

Một đề xuất có hiệu lực tối đa 7 ngày và ghi rõ một đích đến (địa chỉ Lightning hoặc Bitcoin, không phải hóa đơn), một số tiền tính bằng sat (tối đa 1.000.000) và một mục đích (tối đa 140 ký tự). Ai có tệp truy cập thì có thể gửi đề xuất cho bạn nhưng không thể thanh toán bất cứ khoản nào – chỉ đưa tệp này cho tác tử của chính bạn.

Nên biết: Tính năng này đang ở giai đoạn beta. Mục đích của đề xuất do trợ lý ghi; ví không kiểm tra nội dung này.

Giải thích bằng hoạt hình · Mở trong ví