Chuyển đến nội dung chính
Thu phí agent cho các endpoint của bạn bằng Pay (x402 và MPP) và các SDK người bán Node.js của InFlow. Endpoint được bảo vệ trả về 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à rail balance 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ền schemes để 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ận no-store. Một response đã quyết toán nhận private.

Bảo vệ endpoint bằng MPP

MPP dùng package mppx. 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.
Handler này dùng Web Fetch API. Với Express, Hono, Next.js hoặc Elysia, dùng 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.
Khóa bí mật phải dài ít nhất 32 byte. Giữ nguyên khóa này qua các lần deploy, vì server dùng khóa này để kiểm tra các challenge mà server cấp.

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.
Gắ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.
Các hook này không phải là bước kiểm tra phân quyền. Người mua vẫn có thể dùng một credential sau khi offer của credential đó dừng. Áp dụng chính sách truy cập riêng.
Khi 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 rail balance của InFlow. Người mua và người bán không cần ví blockchain.
Với handler Web Fetch, dùng 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 response 402 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:
Dùng một app Express. Chạy các kiểm tra xác thực và kiểm tra đầu vào của bạn trước endpoint này. Không đăng ký thêm middleware x402 ở cấp toàn cục cho endpoint này. Giữ 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 response 402 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.
Lần sửa đổi cuối 13 tháng 11, 2026