Thanh toán (Checkout)

Checkout API cung cấp một cách mạnh mẽ để tạo phiên thanh toán, quản lý luồng thanh toán và xử lý giao dịch thông qua hạ tầng bảo mật của Fystack.

Tạo checkout

POST

/checkouts

Để tạo checkout mới, hãy gửi một request POST đến endpoint /checkouts với các tham số bắt buộc.

Tham số

Name
price
Type
string
Required
required
Description
Số tiền thanh toán dưới dạng chuỗi (ví dụ: "66").
Name
currency
Type
string
Required
required
Description
Mã tiền tệ ISO gồm ba chữ cái (ví dụ: USD, EUR). Hiện chỉ hỗ trợ USD.
Name
expiry_duration_seconds
Type
number
Required
required
Description
Số giây cho đến khi phiên checkout hết hạn. Phải nằm trong khoảng từ 0 đến 31536000.
Name
destination_wallet_id
Type
string
Required
required
Description
ID ví sẽ nhận khoản thanh toán.

Tham số tài sản

Cung cấp supported_assets hoặc accepted_assets.

Name
supported_assets
Type
array
Description
Danh sách tài sản tiền mã hóa được hỗ trợ. Mỗi mục có thể là UUID tài sản hoặc bí danh theo định dạng "SYMBOL:CHAIN_ID" (ví dụ: "SOL:1399811149").
Chuỗi Chain ID Ví dụ định dạng
Solana 1399811149 SOL:1399811149
Ethereum 1 ETH:1, USDC:1
BNB Chain 56 BNB:56
Base 8453 ETH:8453
Polygon 137 POL:137
Name
accepted_assets
Type
array
Description
Danh sách tài sản tiền mã hóa được hỗ trợ ở dạng dễ đọc. Mỗi mục gồm asset và network, ví dụ tài sản USDC trên mạng lưới ETHEREUM_MAINNET.
Name
success_url
Type
string
Description
URL để chuyển hướng khách hàng sau khi thanh toán thành công.
Name
cancel_url
Type
string
Description
URL để chuyển hướng khách hàng nếu họ hủy quá trình checkout.
Name
description
Type
string
Description
Mô tả sản phẩm hoặc dịch vụ khách hàng đang mua.
Name
product_id
Type
string
Description
Mã định danh duy nhất của sản phẩm đang được mua.
Name
customer_id
Type
string
Description
Liên kết checkout này với một khách hàng hiện có trong hệ thống của bạn.
Name
order_id
Type
string
Description
Mã định danh duy nhất của đơn hàng.
Name
enable_localization
Type
boolean
Description
Có bật bản địa hóa cho trang checkout hay không. Mặc định là false.
Name
from_address
Type
string
Description
Địa chỉ người trả tiền (tùy chọn). Nếu được cung cấp, Fystack sẽ dùng luồng thanh toán từ một ví duy nhất.
Name
underpaid_cover_percent
Type
number
Description
Tỷ lệ phần trăm cho phép thanh toán thiếu. Phải nằm trong khoảng từ 0 đến 100.

Chuỗi	Chain ID	Ví dụ định dạng
Solana	1399811149	`SOL:1399811149`
Ethereum	1	`ETH:1`, `USDC:1`
BNB Chain	56	`BNB:56`
Base	8453	`ETH:8453`
Polygon	137	`POL:137`

Phản hồi

Name
id
Type
string
Description
Mã định danh duy nhất của phiên checkout.
Name
checkout_url
Type
string
Description
URL của trang checkout được lưu trữ sẵn. Hãy chuyển hướng khách hàng đến URL này.
Name
status
Type
string
Description
Trạng thái của phiên checkout. Có thể là Pending, Confirming, Success, Expired, Unresolved, Resolved hoặc Cancelled.
Name
created_at
Type
timestamp
Description
Thời điểm phiên checkout được tạo.
Name
updated_at
Type
timestamp
Description
Thời điểm phiên checkout được cập nhật gần nhất.
Name
currency
Type
string
Description
Mã tiền tệ ISO gồm ba chữ cái.
Name
price
Type
string
Description
Số tiền thanh toán dưới dạng chuỗi.
Name
product_id
Type
string
Description
Mã định danh duy nhất của sản phẩm đang được mua.
Name
order_id
Type
string
Description
Mã định danh duy nhất của đơn hàng.
Name
workspace_id
Type
string
Description
Mã định danh của workspace sở hữu checkout này.
Name
description
Type
string
Description
Mô tả sản phẩm hoặc dịch vụ khách hàng đang mua.
Name
supported_assets
Type
array
Description
Danh sách tài sản tiền mã hóa được hỗ trợ cho checkout này.
Name
customer_id
Type
string
Description
Mã định danh của khách hàng gắn với checkout này.
Name
expiry_duration_seconds
Type
number
Description
Số giây cho đến khi phiên checkout hết hạn.
Name
enable_localization
Type
boolean
Description
Trang checkout có bật bản địa hóa hay không.
Name
success_url
Type
string
Description
URL để chuyển hướng khách hàng sau khi thanh toán thành công.
Name
cancel_url
Type
string
Description
URL để chuyển hướng khách hàng nếu họ hủy quá trình checkout.
Name
outcome
Type
object|null
Description
Thông tin về kết quả thanh toán, nếu có.
Name
from_address
Type
string|null
Description
Địa chỉ đã thực hiện thanh toán, nếu có.

Request

POST

/checkouts

import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

await paymentService.createCheckout({
  price: '66',
  currency: 'USD',
  supported_assets: ['SOL:1399811149', 'USDC:1399811149', 'ETH:8453', 'ETH:1', 'USDC:1'],
  description: 'Access to premium features and exclusive content.',
  success_url: 'https://example.com/payment/success',
  cancel_url: 'https://example.com/payment/cancel',
  product_id: '4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2',
  customer_id: 'bc5bd50d-265e-4ea9-b312-bd8de5118683',
  order_id: 'bc5bd50d-265e-4ea9-b312-bd8de5118683',
  enable_localization: false,
  destination_wallet_id: 'ca6b5c4d-753f-4c2d-af18-520f66a42bd4',
  expiry_duration_seconds: 3600
})

Response

200

{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "17976d0a-e4ff-44a6-a47e-c7e2bbab3db2",
    "created_at": "2025-05-17T12:39:27.308105515+07:00",
    "updated_at": "2025-05-17T12:39:27.308105515+07:00",
    "currency": "USD",
    "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
    "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
    "underpaid_cover_percent": 0,
    "description": "Access to premium features and exclusive content.",
    "price": "66",
    "supported_assets": [
      {
        "id": "6f4b5818-967f-4132-a475-20fe766c6c0e",
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "is_native": false,
        "is_whitelisted": false
      },
      {
        "id": "c0b89aea-08b1-4a10-a754-17f3b133be24",
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "is_native": false,
        "is_whitelisted": false
      }
    ],
    "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "expiry_duration_seconds": 3600,
    "enable_localization": false,
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "status": "Pending",
    "outcome": null,
    "from_address": null,
    "checkout_url": "https://app.fystack.io/checkout/17976d0a-e4ff-44a6-a47e-c7e2bbab3db2"
  }
}

Lấy thông tin checkout

GET

/checkouts/{id}

Lấy thông tin chi tiết của một checkout theo ID.

Phản hồi

Name
id
Type
string
Description
Mã định danh duy nhất của checkout.
Name
status
Type
string
Description
Trạng thái của checkout. Có thể là Pending, Confirming, Success, Expired, Unresolved, Resolved hoặc Cancelled.
Name
price
Type
string
Description
Số tiền thanh toán dưới dạng chuỗi.
Name
currency
Type
string
Description
Mã tiền tệ ISO gồm ba chữ cái.
Name
created_at
Type
timestamp
Description
Thời điểm checkout được tạo.
Name
updated_at
Type
timestamp
Description
Thời điểm checkout được cập nhật gần nhất.
Name
product_id
Type
string
Description
Mã định danh duy nhất của sản phẩm đang được mua.
Name
order_id
Type
string
Description
Mã định danh duy nhất của đơn hàng.
Name
workspace_id
Type
string
Description
Mã định danh của workspace sở hữu checkout này.
Name
description
Type
string
Description
Mô tả sản phẩm hoặc dịch vụ khách hàng đang mua.
Name
supported_assets
Type
array
Description
Danh sách tài sản tiền mã hóa được hỗ trợ cho checkout này.
Name
customer_id
Type
string
Description
Mã định danh của khách hàng gắn với checkout này.
Name
expiry_duration_seconds
Type
number
Description
Số giây cho đến khi checkout hết hạn.
Name
success_url
Type
string
Description
URL để chuyển hướng khách hàng sau khi thanh toán thành công.
Name
cancel_url
Type
string
Description
URL để chuyển hướng khách hàng nếu họ hủy quá trình checkout.
Name
checkout_url
Type
string
Description
URL của trang checkout được lưu trữ sẵn.
Name
outcome
Type
object|null
Description
Thông tin về kết quả thanh toán, nếu có.
Name
from_address
Type
string|null
Description
Địa chỉ đã thực hiện thanh toán, nếu có.

Request

GET

/checkouts/:id

import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

const checkout = await paymentService.getCheckout('17976d0a-e4ff-44a6-a47e-c7e2bbab3db2')

Response

200

{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "created_at": "2025-05-17T12:50:57.807741+07:00",
    "updated_at": "2025-05-17T12:50:57.807741+07:00",
    "currency": "USD",
    "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
    "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
    "underpaid_cover_percent": 0,
    "description": "Access to premium features and exclusive content.",
    "price": "66",
    "supported_assets": [
      {
        "id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
        "created_at": "2024-09-21T17:48:12.718886+07:00",
        "updated_at": "2024-09-21T17:48:12.718886+07:00",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "logo_url": "https://assets-cdn.trustwallet.com/blockchains/ethereum/assets/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/logo.png",
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "asset_type": "erc20",
        "is_native": false,
        "address_type": "evm",
        "is_whitelisted": true,
        "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b"
      },
      {
        "id": "6f4b5818-967f-4132-a475-20fe766c6c0e",
        "created_at": "2024-12-05T20:32:42.14387+07:00",
        "updated_at": "2024-12-05T20:32:42.14387+07:00",
        "name": "Solana token",
        "symbol": "SOL",
        "decimals": 9,
        "logo_url": "https://upload.wikimedia.org/wikipedia/en/b/b9/Solana_logo.png",
        "is_native": true,
        "address_type": "sol",
        "is_whitelisted": true,
        "network_id": "8ae1f43f-d428-484d-8ad4-ee9ccc65a9ac"
      }
    ],
    "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "expiry_duration_seconds": 3600,
    "enable_localization": false,
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "status": "Pending",
    "outcome": null,
    "from_address": null,
    "checkout_url": "https://app.fystack.io/checkout/2912168a-6bb6-4b5c-88bb-723706718e4a"
  }
}

Tạo thanh toán cho checkout

POST

/checkouts/{id}/payment

Tạo một khoản thanh toán cho phiên checkout hiện có bằng cách chỉ định tài sản được hỗ trợ dùng để thanh toán.

Tham số

Name
pay_asset_id
Type
string
Required
required
Description
ID của tài sản dùng để thanh toán. Phải là một trong các tài sản được hỗ trợ trong phiên checkout.
Name
customer_email
Type
string
Description
Địa chỉ email của khách hàng thực hiện thanh toán.

Phản hồi

Name
id
Type
string
Description
Mã định danh duy nhất của khoản thanh toán.
Name
checkout_id
Type
string
Description
ID của phiên checkout liên quan.
Name
customer_email
Type
string|null
Description
Email của khách hàng, nếu được cung cấp.
Name
pay_asset_id
Type
string
Description
ID của tài sản đang được dùng để thanh toán.
Name
network_id
Type
string
Description
ID của mạng blockchain cho giao dịch.
Name
expired_at
Type
timestamp
Description
Thời điểm khoản thanh toán hết hạn.
Name
payer_address
Type
string|null
Description
Địa chỉ đã gửi khoản thanh toán, nếu có.
Name
tx_hash
Type
string|null
Description
Mã băm giao dịch, nếu có.
Name
converted_crypto_price
Type
string
Description
Số tiền thanh toán đã được quy đổi sang loại tiền mã hóa được chọn.
Name
deposit_address
Type
string
Description
Địa chỉ cần gửi khoản thanh toán đến.
Name
deposit_qr
Type
string
Description
URL đến mã QR chứa địa chỉ nạp tiền.
Name
created_at
Type
timestamp
Description
Thời điểm khoản thanh toán được tạo.
Name
updated_at
Type
timestamp
Description
Thời điểm khoản thanh toán được cập nhật gần nhất.

Request

POST

/checkouts/:id/payment

import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

// First get the checkout to see available assets
const checkout = await paymentService.getCheckout('2912168a-6bb6-4b5c-88bb-723706718e4a')

// Then create a payment using one of the supported assets
const payment = await paymentService.createCheckoutPayment(checkout.id, {
  pay_asset_id: checkout.supported_assets[0].id
})

Response

200

{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "06d92c50-e6f1-4637-8c20-72cf7e7d7b8a",
    "created_at": "2025-05-17T12:50:57.925269212+07:00",
    "updated_at": "2025-05-17T12:50:57.925269212+07:00",
    "checkout_id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "checkout": null,
    "customer_email": null,
    "pay_asset_id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
    "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
    "network": null,
    "expired_at": "2025-05-17T13:50:57.853990519+07:00",
    "payer_address": null,
    "tx_hash": null,
    "converted_crypto_price": "66",
    "deposit_address": "0xAbE72E79729e7463cd0822700255eD03bc6BD37C",
    "deposit_qr": "https://quickchart.io/qr?size=300&margin=2&text=0xAbE72E79729e7463cd0822700255eD03bc6BD37C"
  }
}

Lấy thông tin thanh toán checkout

GET

/checkouts/payment/{id}

Lấy thông tin chi tiết về một khoản thanh toán checkout theo ID.

Phản hồi

Name
id
Type
string
Description
Mã định danh duy nhất của khoản thanh toán.
Name
checkout_id
Type
string
Description
ID của phiên checkout liên quan.
Name
checkout
Type
object
Description
Toàn bộ đối tượng phiên checkout.
Name
customer_email
Type
string|null
Description
Email của khách hàng, nếu được cung cấp.
Name
pay_asset_id
Type
string
Description
ID của tài sản đang được dùng để thanh toán.
Name
pay_asset
Type
object
Description
Thông tin chi tiết của tài sản đang được dùng để thanh toán.
Name
network_id
Type
string
Description
ID của mạng blockchain cho giao dịch.
Name
network
Type
object
Description
Thông tin chi tiết của mạng blockchain.
Name
expired_at
Type
timestamp
Description
Thời điểm khoản thanh toán hết hạn.
Name
payer_address
Type
string|null
Description
Địa chỉ đã gửi khoản thanh toán, nếu có.
Name
tx_hash
Type
string|null
Description
Mã băm giao dịch, nếu có.
Name
converted_crypto_price
Type
string
Description
Số tiền thanh toán đã được quy đổi sang loại tiền mã hóa được chọn.
Name
deposit_address
Type
string
Description
Địa chỉ cần gửi khoản thanh toán đến.
Name
deposit_qr
Type
string
Description
URL đến mã QR chứa địa chỉ nạp tiền.
Name
created_at
Type
timestamp
Description
Thời điểm khoản thanh toán được tạo.
Name
updated_at
Type
timestamp
Description
Thời điểm khoản thanh toán được cập nhật gần nhất.

Request

GET

/checkouts/payment/:id

import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

const checkoutPayment = await paymentService.getCheckoutPayment('06d92c50-e6f1-4637-8c20-72cf7e7d7b8a')
console.log('checkout payment', checkoutPayment)

Response

200

{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "06d92c50-e6f1-4637-8c20-72cf7e7d7b8a",
    "created_at": "2025-05-17T12:50:57.925269+07:00",
    "updated_at": "2025-05-17T12:50:57.925269+07:00",
    "checkout_id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "checkout": {
      "id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
      "created_at": "2025-05-17T12:50:57.807741+07:00",
      "updated_at": "2025-05-17T12:50:57.807741+07:00",
      "currency": "USD",
      "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
      "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
      "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
      "underpaid_cover_percent": 0,
      "description": "Access to premium features and exclusive content.",
      "price": "66",
      "supported_assets": [],
      "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
      "expiry_duration_seconds": 3600,
      "enable_localization": false,
      "success_url": "https://example.com/payment/success",
      "cancel_url": "https://example.com/payment/cancel",
      "status": "Pending",
      "outcome": null,
      "from_address": null
    },
    "customer_email": null,
    "pay_asset_id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
    "pay_asset": {
      "id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
      "symbol": "USDC",
      "name": "USD Coin",
      "logo_url": "https://assets-cdn.trustwallet.com/blockchains/ethereum/assets/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/logo.png"
    },
    "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
    "network": {
      "id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
      "name": "Ethereum",
      "logo_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRyVyCtMa_rKwrl1y0hyWcqPda3eG0vssJBAX5xQznEPw&s"
    },
    "expired_at": "2025-05-17T13:50:57.85399+07:00",
    "payer_address": null,
    "tx_hash": null,
    "converted_crypto_price": "66",
    "deposit_address": "0xAbE72E79729e7463cd0822700255eD03bc6BD37C",
    "deposit_qr": "https://quickchart.io/qr?size=300&margin=2&text=0xAbE72E79729e7463cd0822700255eD03bc6BD37C"
  }
}

Checkout API của Fystack sử dụng webhook để thông báo cho ứng dụng của bạn khi có sự kiện quan trọng xảy ra, chẳng hạn khi một phiên checkout hoàn tất hoặc một khoản thanh toán thành công hay thất bại.

Các sự kiện webhook phổ biến

payment.received: Được kích hoạt khi nhận được khoản thanh toán.
payment.success: Được kích hoạt khi thanh toán thành công.

Xác minh sự kiện webhook

Vì lý do bảo mật, bạn nên luôn xác minh các sự kiện webhook để đảm bảo chúng thực sự được gửi từ Fystack. Mỗi request webhook đều có chữ ký trong header X-Webhook-Signature mà bạn có thể dùng để xác minh tính xác thực của payload webhook. Loại sự kiện cũng được gửi kèm trong header X-Webhook-Event.

Để xác minh một sự kiện webhook, bạn cần:

Payload của sự kiện webhook
Chữ ký từ header X-Webhook-Signature

Với phương thức verifyEvent của SDK, bạn có thể dễ dàng kiểm tra webhook có hợp lệ hay không trước khi xử lý.

Cấu trúc payload sự kiện

Name
webhook_id
Type
string
Description
Mã định danh duy nhất của cấu hình webhook.
Name
resource_id
Type
string
Description
Mã định danh của tài nguyên gắn với sự kiện.
Name
url
Type
string
Description
URL mà webhook đã được gửi đến.
Name
payload
Type
object
Description
Dữ liệu sự kiện thực tế, chứa thông tin chi tiết về checkout hoặc khoản thanh toán.
Name
event
Type
string
Description
Loại sự kiện (ví dụ: "payment.received", "payment.success").

Xác minh sự kiện webhook

import { APIService, Environment } from '@fystack/sdk'

// Express.js example
app.post('/webhook', express.raw({type: 'application/json'}), async (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const eventType = req.headers['x-webhook-event'] as string;
  const event = req.body;
  
  const apiService = new APIService(apiCredentials, Environment.Production);
  
  try {
    const isValid = await apiService.Webhook.verifyEvent(event, signature);
    
    if (isValid) {
      // Process the webhook event
      if (eventType === 'payment.received') {
        const { checkout_id, tx_hash, status } = event.payload;
        console.log(`Payment received for checkout ${checkout_id}: ${tx_hash}`);
        // Update your database, notify your user, etc.
      }
      
      res.status(200).send('Webhook received and verified');
    } else {
      console.warn('Invalid webhook signature');
      res.status(400).send('Invalid signature');
    }
  } catch (error) {
    console.error('Webhook verification failed', error);
    res.status(400).send('Webhook verification failed');
  }
});

Thanh toán (Checkout)

Tạo checkout

Tham số

Tham số tài sản

Phản hồi

Request

Response

Lấy thông tin checkout

Phản hồi

Request

Response

Tạo thanh toán cho checkout

Tham số

Phản hồi

Request

Response

Lấy thông tin thanh toán checkout

Phản hồi

Request

Response

Webhook của Checkout

Các sự kiện webhook phổ biến

Xác minh sự kiện webhook

Cấu trúc payload sự kiện

Xác minh sự kiện webhook

Ví dụ payload webhook