> ## Documentation Index
> Fetch the complete documentation index at: https://ifdocdemo.lumivescence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bắt đầu nhanh

> Nhận khoản thanh toán đầu tiên từ agent trong sandbox bằng Pay (x402 và MPP). Sau đó thêm ghi danh và listing của bạn, chuyển sang production và xuất bản lên directory.

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.

> [!TIP]
>
> 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](https://ifdocdemo.lumivescence.com/vi/sellers/integrate-with-a-coding-agent.md).

## 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](https://ifdocdemo.lumivescence.com/vi/sellers/protect-an-endpoint-other-languages.md).

| Mục | Chi tiết |
| - | - |
| Node | Phiên bản 22 LTS trở lên. Node 20 đã hết vòng đời. |
| Một tài khoản **Seller** của InFlow | Tài khoản Developer xác thực được, nhưng mọi lời gọi của người bán đều thất bại với `403 SELLER_ACCOUNT_REQUIRED`. |
| Một server mà bạn có thể chỉnh sửa | Các ví dụ dùng Express. Hono, Fastify và Next 16 hoạt động theo cùng cách. |

## 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](https://ifdocdemo.lumivescence.com/vi/concepts/payments.md) 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.

> [accordion] 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](https://ifdocdemo.lumivescence.com/vi/sellers/protect-an-endpoint.md#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](https://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.

```bash .env theme={null}
INFLOW_ENVIRONMENT=sandbox
INFLOW_API_KEY=your_sandbox_key_here
PORT=3000
```

> [!WARNING]
>
> 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](https://ifdocdemo.lumivescence.com/vi/sellers/create-a-seller-account.md).

## 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ị.

> [tab] x402 (Express)
>
> ```bash theme={null}
> pnpm add @inflowpayai/x402-seller @x402/express @x402/core @x402/extensions express
> pnpm add -D dotenv
> ```
>
> ```ts server.ts theme={null}
> import 'dotenv/config';
> import express from 'express';
> import { paymentMiddlewareFromConfig } from '@x402/express';
> import {
>   createInflowFacilitator,
>   createInflowSellerClient,
>   inflowAccepts,
>   inflowSchemeRegistrations,
> } from '@inflowpayai/x402-seller';
>
> const environment = process.env.INFLOW_ENVIRONMENT as 'sandbox' | 'production';
> const apiKey = process.env.INFLOW_API_KEY;
> if (!environment || !apiKey) {
>   console.error('Set INFLOW_ENVIRONMENT and INFLOW_API_KEY (see .env).');
>   process.exit(1);
> }
>
> // Verifies and settles payments through InFlow.
> const inflow = createInflowFacilitator({ environment, apiKey });
>
> // Async. It primes its caches before it resolves.
> const seller = await createInflowSellerClient({ environment, apiKey });
>
> const app = express();
> app.use(express.json());
>
> app.use(
>   paymentMiddlewareFromConfig(
>     {
>       'GET /api/widgets': {
>         accepts: await inflowAccepts(seller, { price: '$0.01' }),
>       },
>     },
>     [inflow],
>     // Required third argument. The middleware refuses to boot without it.
>     await inflowSchemeRegistrations(seller),
>   ),
> );
>
> app.get('/api/widgets', (_req, res) => res.json({ widgets: [1, 2, 3] }));
> app.get('/free', (_req, res) => res.json({ ok: true }));
>
> app.listen(Number(process.env.PORT ?? 3000));
> ```
>
> `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.

> [tab] MPP (Express)
>
> ```bash theme={null}
> pnpm add @inflowpayai/mpp-seller mppx@^0.8.17
> pnpm add -D dotenv
> ```
>
> MPP cần thêm một giá trị. Tạo giá trị này bằng `openssl rand -base64 32`. Giữ giá trị này cố định qua các lần deploy.
>
> ```bash .env theme={null}
> INFLOW_ENVIRONMENT=sandbox
> INFLOW_API_KEY=your_sandbox_key_here
> MPP_SECRET_KEY=paste_the_openssl_output_here
> PORT=3000
> ```
>
> ```ts server.ts theme={null}
> import 'dotenv/config';
> import express from 'express';
> import { Mppx } from 'mppx/express';
> import { inflow, paymentHttpTransport } from '@inflowpayai/mpp-seller';
>
> const environment = process.env.INFLOW_ENVIRONMENT as 'sandbox' | 'production';
> const apiKey = process.env.INFLOW_API_KEY;
> if (!environment || !apiKey) {
>   console.error('Set INFLOW_ENVIRONMENT and INFLOW_API_KEY (see .env).');
>   process.exit(1);
> }
>
> const mppx = Mppx.create({
>   transport: paymentHttpTransport(),
>   methods: [inflow({ apiKey, environment })],
>   secretKey: process.env.MPP_SECRET_KEY,
> });
>
> const app = express();
> app.use(express.json());
>
> app.get('/api/widgets', mppx.charge({ amount: '0.01', currency: 'USDC' }), (_req, res) =>
>   res.json({ widgets: [1, 2, 3] }),
> );
> app.get('/free', (_req, res) => res.json({ ok: true }));
>
> app.listen(Number(process.env.PORT ?? 3000));
> ```
>
> Import `Mppx` từ `mppx/express`, không phải từ `@inflowpayai/mpp-seller`. Các adapter khác của `mppx` là `mppx/hono`, `mppx/nextjs` và `mppx/elysia`.
>
> Loại tiền quyết định rail. Người mua không bao giờ chọn rail. Tiền mã hóa như `USDC` dùng rail `balance`. Tiền pháp định như `USD` dùng rail `instrument`. 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.
>
> Một loại tiền không được hỗ trợ như `JPY` ném ra `MppUnsupportedCurrencyError`. Nếu bạn chấp nhận loại tiền động, đọc bảng ánh xạ rail bằng `createConfigClient`.

> [accordion] Các framework khác
>
> Chỉ phần import adapter thay đổi.
>
> * [x402 trên Hono](https://github.com/inflowpayai/inflow-node/tree/main/examples/x402-seller-hono)
> * [x402 trên Fastify](https://github.com/inflowpayai/inflow-node/tree/main/examples/x402-seller-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](https://github.com/inflowpayai/inflow-node/tree/main/examples/x402-seller-next). 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](https://github.com/inflowpayai/inflow-node/tree/main/examples/mpp-seller-express) và [MPP trên Hono](https://github.com/inflowpayai/inflow-node/tree/main/examples/mpp-seller-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](https://ifdocdemo.lumivescence.com/vi/sellers/protect-an-endpoint.md).

## 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.

```bash x402 theme={null}
curl -i http://localhost:3000/api/widgets
# HTTP/1.1 402 Payment Required
# PAYMENT-REQUIRED: <base64 JSON>

curl -i http://localhost:3000/free
# HTTP/1.1 200 OK
```

```bash MPP theme={null}
curl -i http://localhost:3000/api/widgets
# HTTP/1.1 402 Payment Required
# WWW-Authenticate: Payment id="…", realm="…", method="inflow", intent="charge", request="…"
```

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](https://ifdocdemo.lumivescence.com/vi/agents/authenticate.md#chọn-môi-trường).

**1. Cài đặt CLI**

```bash macOS / Linux theme={null}
curl -fsSL https://inflowcli.ai/install.sh | bash
```

```powershell Windows theme={null}
irm https://inflowcli.ai/install.ps1 | iex
```

**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.

```bash theme={null}
inflow vault unlock
```

**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.

```bash theme={null}
read -s INFLOW_API_KEY
export INFLOW_API_KEY
```

> [!WARNING]
>
> 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ì.

```bash theme={null}
inflow inspect http://localhost:3000/api/widgets
```

Thanh toán bằng lệnh dành cho giao thức của bạn.

```bash x402 theme={null}
inflow x402 pay http://localhost:3000/api/widgets --sandbox --interval 5
```

```bash MPP theme={null}
inflow mpp pay http://localhost:3000/api/widgets --sandbox --interval 5
```

`--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](https://ifdocdemo.lumivescence.com/vi/sellers/test-a-payment.md).

## 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](https://ifdocdemo.lumivescence.com/vi/sellers/enable-enrollment.md). Sau đó thêm Discover (ODP) theo [Niêm yết sản phẩm](https://ifdocdemo.lumivescence.com/vi/sellers/make-products-discoverable.md).

| Tài liệu | Đường dẫn | Package Node.js |
| - | - | - |
| Tài liệu ghi danh | `/.well-known/aep` | `@aep-foundation/service` cùng với `@aep-foundation/express`, `@aep-foundation/hono` hoặc `@aep-foundation/next` |
| Tài liệu khám phá | `/.well-known/odp` | `@offering-protocol/service` |

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`](https://github.com/inflowpayai/inflow-node/tree/main/examples/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](https://app.inflowpay.ai). Tạo một key tại đó. Thay đổi cả hai giá trị cùng nhau.

```bash .env theme={null}
INFLOW_ENVIRONMENT=production
INFLOW_API_KEY=your_production_key_here
```

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](https://ifdocdemo.lumivescence.com/vi/sellers/go-live.md).

Sau đó [kiểm tra tích hợp](https://ifdocdemo.lumivescence.com/vi/sellers/verify-your-integration.md) và [xuất bản lên directory](https://ifdocdemo.lumivescence.com/vi/sellers/publish-to-the-directory.md). 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](https://ifdocdemo.lumivescence.com/vi/reference/errors.md).

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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ề `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

> [card] [Ghi danh agent](https://ifdocdemo.lumivescence.com/vi/sellers/enable-enrollment.md)
>
> 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.

> [card] [Hỏi trên Discord](https://discord.gg/Z9nmMAgaR4)
>
> Cho đội ngũ biết bước nào thất bại và bạn gặp lỗi nào.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.