Skip to Content
Payment LinksTổng quan

Payment Links — Tổng quan

Payment Link là một URL có thể chia sẻ, đưa người mua vào một checkout do hệ thống host mà bạn đã cấu hình sẵn. Không SDK, không tích hợp server — phát hành nó trong dashboard, chia sẻ, và cùng webhook payment.settled được phát khi vốn xác nhận on-chain.

Bên dưới, một Payment Link chính là một CheckoutSession — “Payment Link” chỉ là tên gọi phía dashboard của một session không được tạo bởi luồng SDK do người mua chủ động. Cùng webhook contract, cùng settlement on-chain, cùng phí.

Use case phổ biến:

  • Xuất hóa đơn cho một khách hàng đơn lẻ mà không cần code
  • Trang sales nơi đội dev quý này sẽ chưa wire cart tùy chỉnh
  • Follow-up B2B — paste link vào email và xong
  • Trang tip cố định kiểu “Buy me a coffee”

Hiện tại chỉ có thể qua dashboard:

  1. Đăng nhập vào merchant dashboard 
  2. Payments → Payment Links → + New link
  3. Chọn một trong hai path:
    • New order — nhập line items, currency, thông tin khách hàng, và metadata tùy chọn. Dashboard tạo Order và Payment Link trong cùng một lệnh gọi.
    • Existing order — chọn một order PENDING (ví dụ người mua đã từ bỏ link trước đó). Phát hành lại một link mới đứng sau cùng order, để lịch sử order giữ nguyên.
  4. Save → dashboard hiển thị URL https://checkout.infraio.xyz/cst_… với nút copy và download QR code. Link test-mode dùng checkout-dev.infraio.xyz để môi trường được mã hóa trong hostname.

Mỗi Payment Link hiện tại là single-use: khi người mua trả tiền, session là COMPLETED. Nếu một session hết hạn trước khi thanh toán (TTL mặc định 30 phút), mở trang chi tiết order và bấm Re-create link để phát hành một link mới cho cùng order.

Người mua thấy gì

  1. Họ vào checkout.infraio.xyz/<session_key> — cùng UI checkout do hệ thống host mà bạn sẽ nhận được từ session do SDK phát hành.
  2. Họ đi qua luồng chuẩn: chọn asset → gửi tiền → chờ confirmation được mô tả trong Checkout — Tổng quan.
  3. payment.settled được phát đến webhook của bạn với order, intent, receipt, tx hash on-chain, và số confirmation — cùng payload như bất kỳ thanh toán đã settle nào khác. Xem Webhooks để biết schema.

Dashboard cho bạn những gì

Surface Payment Links hiện đi kèm:

  • List view — mọi link bạn đã phát hành, cursor-paginated, với trạng thái, số tiền, số order cha, khách hàng, expiry, và mở bằng một cú click đến URL người mua.
  • Filters — trạng thái (ACTIVE / COMPLETED / EXPIRED / CANCELED), khoảng ngày, và tìm kiếm tự do trên số order, tên khách hàng, email, hoặc external ref.
  • CSV export — một cú click, tôn trọng filter hiện tại.
  • KPI strip — đếm theo trạng thái, scope theo môi trường hiện tại (live vs test) qua header X-Environment để số liệu luôn khớp với những gì bảng đang hiển thị.
  • Trang chi tiết — tóm tắt order, lịch sử session (mỗi lần thử cho order này), lịch sử on-chain với link đến block explorer, và hành động Re-create link cho các session đã hết hạn trước khi thanh toán.

Hạn chế hiện tại

  • Không có API programmatic — link phải được tạo trong dashboard. SDK có thể tạo session single-use tương đương qua POST /b2b/v1/checkout-sessions/quick (xem Tham chiếu API), nhưng UX “URL có thể chia sẻ tồn tại lâu” hiện chỉ qua dashboard.
  • Không xác thực theo từng người mua — bất kỳ ai có URL đều có thể trả. Mô hình single-use phần nào giảm thiểu điều này; gắn danh tính người mua đầy đủ nằm trong roadmap dưới.
  • Branding là toàn cục — link dùng logo, brand colour, và border radius theo merchant từ Settings → Branding. Override branding theo từng link chưa được surface trong UI dashboard.

Roadmap

Các mục chúng tôi biết mình muốn, xếp theo ưu tiên cao đến thấp:

  • Tạo programmatic — một endpoint POST /b2b/v1/payment-links phản chiếu hộp thoại hai tab của dashboard và trả về cùng checkout_url. Đi tự nhiên với liệt kê + thu hồi.
  • Hết hạn theo thời gian — link còn hiệu lực đến một ngày cụ thể, không chỉ đến khi TTL session hết. Cần cho luồng xuất hóa đơn nơi “due in 14 days” là deadline tự nhiên.
  • Link tái sử dụng — trang đa người mua kiểu Stripe (donation, tipping, tab định kỳ). Hiện mọi link đều single-use.
  • Danh tính theo từng người mua — khóa link vào một email hoặc ví cụ thể để không thể forward.
  • Tạo QR phía API — dashboard hiện render QR code phía client; surface điều này trên API cho việc in label và embed receipt nằm trong danh sách.

Xem thêm

Tổng quanJavaScript / Trình duyệt