Chuyển đến nội dung chính
Nhận khoản thanh toán đầu tiên từ agent trên endpoint của chính bạn trong sandbox, bằng Pay (x402 và MPP). Các bước 1 đến 5 không cần tiền thật và không cần server công khai.
Một coding agent có thể làm việc này cùng bạn. Xem Xây dựng với coding agent.

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.
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
Không bao giờ đặt baseUrl. SDK xác định host đúng chỉ từ environment. Một baseUrl gửi lưu lượng của bạn đến một host ngoài dự kiến.
Về các loại tài khoản và an toàn của key, xem Tạo tài khoản Seller.

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ị.
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.
Chỉ phần import adapter thay đổi.
  • x402 trên Hono
  • x402 trên Fastify. paymentMiddlewareFromConfig thay đổi instance Fastify tại chỗ. Hàm này không trả về một middleware. Gọi hàm theo dạng paymentMiddlewareFromConfig(app, routes, [inflow], regs).
  • x402 trên Next 16. Next 16 đã đổi tên middleware.ts thành proxy.ts. Dùng một proxy.ts ở cấp gốc với paymentProxyFromConfig.
  • MPP trên Express và MPP trên Hono.
Về scheme, thu phí bằng nhiều loại tiền và gói thuê bao, xem Nhận thanh toán từ agent.

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.
Response 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ùng production 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.
Dùng một API key, không dùng inflow auth login, để thanh toán cho một endpoint trên localhost. Với đăng nhập bằng thiết bị, InFlow ký mỗi request bằng Visa Trusted Agent Protocol (TAP). InFlow không ký các request đến URL http://, chẳng hạn http://localhost. Khi đó lệnh thất bại với TAP signing failed.
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ì.
Thanh toán bằng lệnh dành cho giao thức của bạn.
--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.
Về các ví dụ cho người mua và các bước kiểm tra khác, xem Kiểm thử thanh toá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
Với MPP, cũng đặt một 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ạn 403 SELLER_ACCOUNT_REQUIRED và RouteConfigurationError, xem 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.
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.
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.
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ề 402 vớ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.
Lần sửa đổi cuối 27 tháng 10, 2026