402 Payment Required cho đến khi agent thanh toán. InFlow kiểm tra khoản thanh toán trước khi code của bạn chạy. Khoản thanh toán bằng stablecoin quyết toán vào tài khoản InFlow của bạn. Khoản thanh toán bằng thẻ quyết toán vào tài khoản Stripe của bạn.
Để đi theo cách ngắn nhất, đọc Bắt đầu nhanh trước. Với Python, Go và Rust, xem Python, Go và Rust.
Trước khi bắt đầu
Chấp nhận MPP và x402
Tích hợp cả hai giao thức trong cùng một dịch vụ, để agent dùng giao thức nào cũng có thể thanh toán. Dùng chung logic định giá và logic xử lý đơn hàng cho hai giao thức. Một request không bao giờ được đi qua hai luồng thu phí độc lập. Cách Pay hoạt động so sánh các giao thức. Số dư InFlow là cách thanh toán mặc định của agent. Đó là railbalance trong MPP và scheme balance trong x402. Agent cũng có thể thanh toán onchain hoặc bằng thẻ đã liên kết.
Cài đặt các package
Với MPP,
mppx là một peer dependency. Mỗi framework có một ví dụ chạy được trong Tham khảo SDK.
Bảo vệ endpoint bằng x402
Server này từ ví dụx402-seller-express bảo vệ hai endpoint và để một endpoint miễn phí.
server.ts
Chức năng của từng phần
Truyền
inflowSchemeRegistrations làm đối số thứ ba. Nếu thiếu đối số này, middleware dừng lúc khởi động với RouteConfigurationError.
Biết khi nào khoản thanh toán quyết toán
Middleware kiểm tra khoản thanh toán trước khi handler của bạn chạy. Middleware quyết toán khoản thanh toán sau khi handler của bạn chạy. Vì vậy, không cộng credit hoặc làm việc khác mà bạn không thể hoàn tác trong handler. Xem Bán credit trả trước.Viết giá
inflowAccepts đọc ba định dạng giá. Mỗi định dạng chấp nhận tối đa 8 chữ số thập phân.
Với các offer
balance và exact, USD khớp với mọi stablecoin trong cấu hình người bán của bạn. Với một offer instrument, USD là USD pháp định.
Khoản thanh toán bằng stablecoin không có số tiền tối thiểu. Giá instrument phải bằng USD, tối thiểu USD 0.50 và là số cent nguyên.
Giới hạn các scheme
Truyềnschemes để giới hạn các tùy chọn thanh toán trên một endpoint, như POST /api/upload ở trên.
Dùng nhiều facilitator
Middleware chấp nhận một danh sách facilitator. Các khoản thanh toán của một cặp scheme và network thuộc về facilitator đầu tiên nhận quyền với cặp đó.Lưu cache
Middleware x402 đặt các header cache. Một challenge chưa thanh toán nhậnno-store. Một response đã quyết toán nhận private.
Bảo vệ endpoint bằng MPP
MPP dùng packagemppx. Thêm phương thức InFlow vào Mppx.create. Sau đó charge() trả về một challenge 402 cho request chưa thanh toán.
mppx/express, mppx/hono, mppx/nextjs hoặc mppx/elysia. Bắt đầu nhanh trình bày adapter Express.
Truyền paymentHttpTransport() làm transport. Nếu thiếu giá trị này, một lỗi server cũng gửi một challenge thanh toán.
Đặt khóa bí mật
Mppx.create cần một secretKey. Hàm này cũng đọc biến MPP_SECRET_KEY. Tạo khóa bí mật.
Chọn loại tiền
Loại tiền của khoản thu quyết định rail. SDK đọc rail của mỗi loại tiền từGET /v1/mpp/config, một lần lúc khởi động.
Khoản thanh toán bằng stablecoin không có số tiền tối thiểu. Khoản thanh toán thẻ bằng USD có mức tối thiểu USD 0.50 và phải là số cent nguyên. Điều này áp dụng cho rail
instrument, card và stripe.
Chấp nhận nhiều loại tiền
charge() công bố một loại tiền. Với nhiều loại tiền, dùng inflowChargesNodeListener hoặc inflowCharges. Endpoint gửi một challenge cho mỗi mức giá. Phương thức suy ra rail từ loại tiền.
checkout(req, res) vào một server http của Node hoặc vào một endpoint Express. Với handler Web Fetch, dùng inflowCharges(mppx, prices).
Các adapter framework chỉ cung cấp charge và loại bỏ compose. Do đó, endpoint nhiều loại tiền cần instance Mppx lõi từ @inflowpayai/mpp-seller. Instance này cũng có thể phục vụ các endpoint một loại tiền.
Người mua thanh toán một challenge. Mỗi số tiền là độc lập. Số tiền không phải là tỷ giá.
Kiểm soát các offer xuất hiện
Hai hook chọn các challenge cho một request.canOffer hoạt động trên một phương thức. selectOffers hoạt động trên server và chạy sau mọi canOffer.
canOffer từ chối mọi offer, handler thất bại với No payment offers are available for this request. selectOffers phải trả về ít nhất một offer.
Cung cấp gói thuê bao
Gói thuê bao bảo vệ một resource bằng các điều khoản thanh toán định kỳ. Người mua phê duyệt các điều khoản và InFlow thu phí kỳ đầu tiên. Sau đó InFlow quản lý các khoản thu tiếp theo, các trạng thái quá hạn và hủy thuê bao. Gói thuê bao dùng railbalance của InFlow. Người mua và người bán không cần ví blockchain.
inflowSubscriptions(mppx, plans).
SDK cũng chấp nhận minute để kiểm thử, với periodCount tối thiểu là 5. Không cung cấp gói theo phút cho khách hàng.
Thu phí bằng token TIP-20 trên Tempo
@inflowpayai/mpp-seller cũng export phương thức tempo cho các khoản thu TIP-20 trên Tempo. Truyền phương thức này vào Mppx.create dưới dạng tempo({ apiKey, currency, recipient }). Tài trợ fee-payer mặc định tắt. Đặt methodDetails.feePayer: true để cấp một challenge có tài trợ.
Package này cũng export card cho thanh toán USD bằng network token của Visa và stripe cho thanh toán USD bằng Stripe Shared Payment Tokens. Ví dụ mpp-card-seller-express dùng card.
Chấp nhận cả hai giao thức trên một endpoint
Một endpoint có thể bán cùng một resource qua MPP và x402. Một request chưa thanh toán nhận một response402 với các tùy chọn của cả hai giao thức. Người mua chọn một giao thức và gửi credential của giao thức đó đến cùng URL.
Ví dụ Express này bán một báo cáo với giá 0.01 USDC. Ví dụ kết nối hai middleware trong code của ứng dụng. Đây không phải một helper của SDK. Ví dụ dùng các giá trị sau từ các phần ở trên:
response.json, vì middleware MPP gắn receipt của nó vào đó.
Với Python, Go và Rust, không có ví dụ SDK nào cho một endpoint. Xây dựng cùng cách chọn request, hoặc dùng một endpoint cho mỗi giao thức.
Kiểm tra kích thước các header của response
Một response402 với cả hai giao thức có các header lớn hơn. Proxy có thể từ chối response đó. Ví dụ, NGINX có thể trả về 502 với upstream sent too big header. Gửi một request chưa thanh toán qua hostname công khai của bạn, không chỉ đến server của ứng dụng.
Nếu các header quá lớn, làm một trong các việc sau:
- Công bố ít tùy chọn hơn.
- Tăng bộ đệm cho các header của response trong proxy. Với NGINX, đó là
proxy_buffer_size. - Dùng một endpoint cho mỗi giao thức.
Tính đến thời điểm thanh toán
Hai middleware chạy handler của bạn vào các thời điểm khác nhau.
Không bao giờ tự động thử lại một khoản thanh toán lỗi qua giao thức còn lại. Một timeout có thể để khoản thanh toán đầu tiên ở trạng thái không xác định. Kiểm tra trạng thái của khoản thanh toán đó trước. Webhook cho bạn biết trạng thái của từng khoản thanh toán.
Kiểm tra chữ ký trusted agent
@inflowpayai/tap-seller kiểm tra chữ ký request của trusted agent trên chính server của bạn. Xem Tham khảo SDK.
Bước tiếp theo
Kiểm thử thanh toán
Thanh toán cho endpoint của chính bạn trong sandbox.