Trước khi bắt đầu
Hướng dẫn này dùng Node.js. Với Python, Go hoặc Rust, xem Python, Go và Rust.Bước 1: Tích hợp cả hai giao thức
InFlow chấp nhận MPP và x402. Tích hợp cả hai để agent của giao thức nào cũng có thể thanh toán cho bạn. Cả hai giao thức đều chấp nhận số dư InFlow. Cách Pay hoạt động so sánh hai giao thức này. Dùng chung logic định giá và logic xử lý đơn hàng cho cả hai giao thức. Mỗi request chỉ đi qua một luồng thu phí. Bạn có thể bắt đầu với một giao thức và thêm giao thức còn lại sau.Công bố cả hai giao thức trên một endpoint
Công bố cả hai giao thức trên một endpoint
Một endpoint có thể chấp nhận MPP và x402. Khi đó, response
402 của endpoint chứa các tùy chọn MPP trong WWW-Authenticate và các tùy chọn x402 trong PAYMENT-REQUIRED. Không package InFlow nào làm việc này cho bạn. Bạn kết nối hai middleware trong code của ứng dụng. Xem Chấp nhận cả hai giao thức trên một endpoint.Không đặt paymentMiddlewareFromConfig và mppx.charge(...) nối tiếp nhau trên một endpoint. Middleware đầu tiên gửi toàn bộ response 402 và kết thúc request.Bước 2: Đăng ký tài khoản Seller
Đăng ký tài khoản Seller tại sandbox.inflowpay.ai. Trong dashboard, mở Configuration > API Keys và thêm một key. Dùng giá trị Private Key, không dùng Public Key. Đặt key và môi trường của key trong cùng một file.env. Hai giá trị này phải luôn thay đổi cùng nhau.
.env
Bước 3: Bảo vệ một endpoint
Làm theo cả hai tab. Một server bảo vệ một số endpoint bằng x402 và các endpoint khác bằng MPP. Code đọc cả hai giá trị từ môi trường và dừng khi khởi động nếu thiếu một giá trị.- x402 (Express)
- MPP (Express)
server.ts
inflowAccepts đọc giá ở dạng '$0.01', dạng '0.10 USDC' hoặc dạng '0.01' không có đơn vị, kèm trường currency. Thanh toán bằng stablecoin không có số tiền tối thiểu. Thanh toán bằng thẻ theo USD có mức tối thiểu USD 0.50, tính bằng số cent nguyên.Các framework khác
Các framework khác
Chỉ phần import adapter thay đổi.
- x402 trên Hono
- x402 trên Fastify.
paymentMiddlewareFromConfigthay đổi instance Fastify tại chỗ. Hàm này không trả về một middleware. Gọi hàm theo dạngpaymentMiddlewareFromConfig(app, routes, [inflow], regs). - x402 trên Next 16. Next 16 đã đổi tên
middleware.tsthànhproxy.ts. Dùng mộtproxy.tsở cấp gốc vớipaymentProxyFromConfig. - MPP trên Express và MPP trên Hono.
Bước 4: Xác nhận challenge
Khởi động server của bạn. Gọi endpoint trả phí mà không thanh toán.200 trên một endpoint trả phí nghĩa là middleware không chạy.
Bước 5: Thanh toán cho endpoint của chính bạn
CLI dùngproduction theo mặc định. Server của bạn chạy trong sandbox, nên thêm --sandbox vào lệnh đăng nhập và vào từng lệnh thanh toán. Xem Xác thực.
1
Cài đặt CLI
2
Mở khóa vault
Tự chạy lệnh này trong một terminal. Chọn một PIN hoặc một cụm mật khẩu. Không bao giờ đưa PIN hoặc cụm mật khẩu đó cho một agent.
3
Cung cấp cho CLI một API key sandbox
Dùng một key từ một tài khoản người mua sandbox riêng, ví dụ một tài khoản Developer. Không dùng key của tài khoản Seller nhận khoản thanh toán. Dán key sau lệnh đầu tiên. Sau đó nhấn Enter.
4
Kiểm tra, sau đó thanh toán
inspect báo cáo các khả năng của endpoint. Lệnh này không thanh toán gì.--interval 5 thăm dò mỗi 5 giây cho đến khi khoản thanh toán được quyết toán. Giá trị mặc định 0 trả về ngay một ID giao dịch và không chặn.Bước 6: Ghi danh agent và niêm yết sản phẩm của bạn
Các bước 1 đến 5 cho phép một agent thanh toán cho bạn. Agent chưa thể ghi danh với dịch vụ của bạn hoặc tìm thấy dịch vụ đó. Thêm Onboard (AEP) theo Ghi danh agent. Sau đó thêm Discover (ODP) theo Niêm yết sản phẩm.
Gán endpoint mà bạn bảo vệ ở bước 3 cho từng hành động mua trong danh mục của bạn. Ví dụ
mpp-aep-seller-express đặt bước ghi danh trước một endpoint MPP. Ví dụ này gửi credential ghi danh trong x-aep-api-key. Nhờ đó Authorization: Payment vẫn còn trống cho MPP.
Bước 7: Chuyển sang production và xuất bản
Production chỉ thay đổi file.env của bạn, không thay đổi gì khác. Đăng ký một tài khoản Seller production tại app.inflowpay.ai. Tạo một key tại đó. Thay đổi cả hai giá trị cùng nhau.
.env
MPP_SECRET_KEY production. Không bao giờ dùng lại secret của sandbox. Deploy đúng bản build mà bạn đã kiểm thử. Xem Chuyển sang production.
Sau đó kiểm tra tích hợp và xuất bản lên directory. Directory không có sandbox và không chấp nhận localhost.
Khắc phục sự cố
Về các lỗi khác, chẳng hạn403 SELLER_ACCOUNT_REQUIRED và RouteConfigurationError, xem Lỗi.
createInflowSellerClient bị treo hoặc báo lỗi
createInflowSellerClient bị treo hoặc báo lỗi
Hàm này gửi các lời gọi có xác thực khi khởi tạo để nạp sẵn cache của nó. Kiểm tra API key. Kiểm tra xem
INFLOW_ENVIRONMENT có khớp với dashboard đã cấp key không.Mọi request đều trả về 402, kể cả sau khi thanh toán
Mọi request đều trả về 402, kể cả sau khi thanh toán
Kiểm tra header mà người mua gửi. x402 dùng
PAYMENT-SIGNATURE. MPP dùng Authorization: Payment.Sau đó kiểm tra xem người mua có dùng giao thức mà server của bạn triển khai không. Người mua MPP không thể thanh toán cho một endpoint x402.X402PriceParseError
X402PriceParseError
inflowAccepts không đọc được chuỗi price của bạn. Bắt lỗi này khi khởi động, không bắt theo từng request. Bước 3 liệt kê các dạng được chấp nhận.MppCredentialProblemError
MppCredentialProblemError
Credential không qua được bước kiểm tra tính hợp lệ hoặc bước phát đi. Đọc trường
type trong problem detail RFC 9457 của lỗi này. Dùng type để quyết định giữa một challenge mới và một lỗi dứt điểm.Trạng thái 500 nghĩa là chưa biết kết quả. Không tạo khoản thanh toán mới. Kiểm tra trạng thái thanh toán trước.Kiểm tra kết quả
- Một lời gọi chưa thanh toán đến endpoint của bạn trả về
402với header đúng. - Một endpoint không đặt giá vẫn trả về
200. -
inflow inspect <your-url>báo cáo giao thức mà bạn công bố. - Một khoản thanh toán bằng CLI trả về nội dung response thật từ endpoint của bạn.
- Khoản thanh toán xuất hiện trong dashboard của bạn.
- Bản deploy production của bạn dùng cùng bản build với bản deploy sandbox.
Bước tiếp theo
Ghi danh agent
Cho phép agent ghi danh với dịch vụ của bạn với tư cách khách hàng được nhận biết.
Hỏi trên Discord
Cho đội ngũ biết bước nào thất bại và bạn gặp lỗi nào.