# Bắt đầu nhanh (/vi/developers/quickstart)





Mục tiêu của hướng dẫn này là giúp hệ thống của bạn nhận thông báo ngay khi tài khoản
ngân hàng có tiền vào.

## Cách PayFS hoạt động [#cách-payfs-hoạt-động]

<Mermaid
  chart="sequenceDiagram
    participant B as Ngân hàng
    participant P as PayFS
    participant Y as Hệ thống của bạn

    B->>P: Có giao dịch mới
    P->>Y: POST webhook, kèm chữ ký
    Y->>Y: Kiểm tra chữ ký
    Y->>P: HTTP 200"
/>

Bạn không cần liên tục gọi PayFS để kiểm tra giao dịch mới. PayFS sẽ chủ động gọi đến
endpoint của bạn.

## Bốn bước [#bốn-bước]

### 1. Tạo Workspace và kết nối ngân hàng [#1-tạo-workspace-và-kết-nối-ngân-hàng]

Thực hiện trên Client Portal. Xem [Tạo Workspace](/vi/workspace/create) và
[Kết nối ngân hàng](/vi/bank-accounts/organization).

### 2. Dựng một endpoint nhận webhook [#2-dựng-một-endpoint-nhận-webhook]

Endpoint cần công khai trên Internet và trả về HTTP 200.

```javascript
const express = require('express');
const app = express();
app.use(express.json());

app.post('/payfs-webhook', (req, res) => {
  const apiKey = req.headers['x-client-api-key'];
  if (apiKey !== process.env.PAYFS_WEBHOOK_API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const tx = req.body;
  if (tx.transfer_type === 'credit') {
    console.log('Tiền về:', tx.amount, 'VND —', tx.content);
  }

  res.status(200).json({ status: 'ok' });
});

app.listen(3000);
```

### 3. Khai báo endpoint trong Client Portal [#3-khai-báo-endpoint-trong-client-portal]

Vào phần thông báo của Workspace, tạo webhook rồi dán URL endpoint. PayFS sẽ tạo sẵn
API key và secret cho webhook đó.

### 4. Thử một giao dịch thật [#4-thử-một-giao-dịch-thật]

Chuyển một khoản nhỏ vào tài khoản đã kết nối. Endpoint của bạn sẽ nhận webhook trong
vài giây.

<Callout type="warn">
  Endpoint phải trả lời trong **30 giây**. Nếu xử lý nghiệp vụ lâu, hãy trả 200 trước
  rồi đẩy việc sang hàng đợi nền. Trả lời chậm bị tính là thất bại và PayFS sẽ gửi lại.
</Callout>

## Tiếp theo [#tiếp-theo]

| Việc                              | Đọc trang                                          |
| --------------------------------- | -------------------------------------------------- |
| Hiểu payload và các sự kiện       | [Webhook](/vi/developers/webhooks)                 |
| Xác minh chữ ký để chống giả mạo  | [Chữ ký webhook](/vi/developers/webhook-signature) |
| Gọi API của PayFS                 | [API Token](/vi/developers/api-token)              |
| Thu một khoản qua trang công khai | [Liên kết thanh toán](/vi/developers/payment-link) |