🎯 Khởi tạo OneQR - Tạo QR động

✧ Mở bằng AI

Sao chép tài liệu, mở AI rồi dán vào cuộc trò chuyện.

📱 Tổng quan

Để tạo một mã QR động cho giao dịch, bạn gọi API Create QR Code của OneQR. Mỗi lần gọi sẽ sinh ra 1 QR mới với các thông tin giao dịch cụ thể.

🔌 Endpoint

POST http://api.pay2s.vn/api/{bank_code}/v1/qr/create

Tham số	Ví dụ	Mô tả
`{bank_code}`	`vcb`	Mã ngân hàng (vcb = Vietcombank, acb = ACB Bank, ...)

📤 Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

Lưu ý: <token> là Bearer token được cấp từ Pay2S

Body Parameters (JSON)

Tham số	Loại	Bắt buộc	Mô tả
`orderId`	String	✓	ID đơn hàng trong hệ thống của bạn
`amount`	Number	✓	Số tiền (VND) - ví dụ: 18000, 500000
`merchantName`	String	✓	Tên cửa hàng/thương nhân
`merchantId`	String	✓	Mã thương nhân do ngân hàng cấp
`terminalId`	String	✓	ID thiết bị/terminal
`description`	String	✓	Nội dung thanh toán
`template`	String	-	Kiểu template hiển thị (ví dụ: `frame`)
`maskAccount`	Boolean	-	Ẩn số tài khoản (default: false)
`frameId`	Number	-	ID khung hình để hiển thị QR

✅ Ví dụ Request (cURL)

curl --location 'http://api.pay2s.vn/api/vcb/v1/qr/create' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --data '{
    "orderId": "123456",
    "amount": 10000,
    "merchantName": "CONG TY CO PHAN FUTE",
    "merchantId": "091000000900000",
    "terminalId": "60000000",
    "description": "THANH TOAN DON HANG",
    "template": "frame",
    "maskAccount": true,
    "frameId": 1
  }'

📥 Response

✅ Thành công (200 OK)

{
  "code": "00",
  "desc": "Succeed",
  "data": {
    "qrDataURL": "<QRDATAURL_OMITTED>",
    "qrImageUrl": "<QRIMAGEURL_OMITTED>",
    "template": "frame",
    "decodedQrCode": "https://developer.example.com/payment/?qr=da58fde344a1e0c9280207e1143c6f40",
    "deeplink": "https://developer.example.com/payment/?qr=da58fde344a1e0c9280207e1143c6f40",
    "signature": "<SIGNATURE>",
    "timeStamp": "1791659974931",
    "orderId": "DEMO17916599748852455",
    "amount": 100000,
    "status": "processing",
    "traceNumber": "DEMOQR50269d422b61",
    "qrData": "https://developer.example.com/payment/?qr=da58fde344a1e0c9280207e1143c6f40",
    "transactionId": "da58fde344a1e0c9280207e1143c6f40",
    "requestID": "DEMO-6e40f8301889"
  }
}

Trường	Mô tả
`code`	Mã lỗi: `00` = Thành công
`desc`	Mô tả: `Succeed` = Thành công
`qrDataURL`	Chuỗi QR mã (EMV-QR format) - dùng để sinh hình ảnh QR
`traceNumber`	Mã định danh duy nhất của QR được tạo ra
`transactionId`	Mã kiểm tra trạng thái QR

💻 Code mẫu - Tạo QR cho từng đơn hàng

<?php
$bearerToken = "YOUR_BEARER_TOKEN";
$url = "http://api.pay2s.vn/api/vcb/v1/qr/create";

$data = [
    'orderId' => "123456",
    'amount' => 10000,
    'merchantName' => "CONG TY CO PHAN FUTE",
    'merchantId' => "091000000900000",
    'terminalId' => "60000000",
    'description' => "THANH TOAN DON HANG",
    'template' => "frame",
    'maskAccount' => true,
    'frameId' => 1
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $bearerToken,
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['code'] === '00') {
    $qrData = $result['data'];
    echo "QR Code: " . $qrData;
} else {
    echo "Error: " . $result['desc'];
}

curl_close($ch);
?>

const axios = require('axios');

const bearerToken = "YOUR_BEARER_TOKEN";

const payload = {
  orderId: "123456",
  amount: 10000,
  merchantName: "CONG TY CO PHAN FUTE",
  merchantId: "091000000900000",
  terminalId: "60000000",
  description: "THANH TOAN DON HANG",
  template: "frame",
  maskAccount: true,
  frameId: 1
};

axios.post("http://api.pay2s.vn/api/vcb/v1/qr/create", payload, {
  headers: {
    "Authorization": `Bearer ${bearerToken}`,
    "Content-Type": "application/json"
  }
})
  .then(response => {
    if (response.data.code === '00') {
      console.log("QR Code:", response.data.data);
    } else {
      console.error("Error:", response.data.desc);
    }
  })
  .catch(err => console.error(err));

import requests
import json

bearer_token = "YOUR_BEARER_TOKEN"

payload = {
    'orderId': "123456",
    'amount': 10000,
    'merchantName': "CONG TY CO PHAN FUTE",
    'merchantId': "091000000900000",
    'terminalId': "60000000",
    'description': "THANH TOAN DON HANG",
    'template': "frame",
    'maskAccount': True,
    'frameId': 1
}

headers = {
    "Authorization": f"Bearer {bearer_token}",
    "Content-Type": "application/json"
}

response = requests.post("http://api.pay2s.vn/api/vcb/v1/qr/create", 
                         data=json.dumps(payload), 
                         headers=headers)
result = response.json()

if result['code'] == '00':
    print("QR Code:", result['data'])
else:
    print("Error:", result['desc'])

⚡ Best Practices

Validate input: Kiểm tra amount > 0 trước khi request
Error handling: Kiểm tra code trước xử lý data
Lưu QR data: Lưu chuỗi QR vào database để regenerate ảnh nếu cần
Timeout QR: Đặt QR có hiệu lực 15-30 phút
MaskAccount: Sử dụng maskAccount: true để bảo mật thông tin
Template: Chọn template: "frame" để hiển thị với UI frame
TerminalId: Đảm bảo terminalId hợp lệ từ ngân hàng
Retry logic: Nếu request fail, retry sau 2-3 giây
Database record: Lưu orderId, amount, qr_status để tracking
Rate limit: Giới hạn số lượng request tạo QR mỗi phút

📌 Luồng tạo QR

1. Khách order → 2. Hệ thống tạo QR → 3. Hiển thị ảnh QR + frame → 
4. Khách scan QR → 5. Chọn ngân hàng → 6. Xác nhận → 
7. Thanh toán → 8. Webhook notify → 9. Cập nhật status = paid

Tiếp theo: Xem Webhook để nhận thông báo thanh toán tự động

Request và response đối chiếu ngày 11/10/2026

Các mẫu dưới đây giữ cấu trúc trường và kiểu dữ liệu. Khóa, chữ ký, URL phiên đã được thay bằng placeholder; danh sách chỉ giữ tối đa hai phần tử và dữ liệu ảnh/PDF/XML dài được rút gọn. Không sao chép placeholder để gọi API thật.

OneQR · Tạo QR động

Thử API trong Playground ↗

Mô phỏng; chưa xác minh với API nhà cung cấp. Giữ mô phỏng theo cấu hình demo. Chưa có API OneQR thật để xác minh lại hợp đồng nhà cung cấp.

POST /api/{bank_code}/v1/qr/create

Body:

{
  "orderId": "DEMO17916599748852455",
  "amount": 100000,
  "merchantName": "CUA HANG DEMO",
  "merchantId": "DEMO_MERCHANT",
  "terminalId": "DEMO_TERMINAL",
  "description": "THANHTOANDEMO",
  "template": "frame",
  "maskAccount": false,
  "frameId": 1
}

HTTP 200. Response:

{
  "code": "00",
  "desc": "Succeed",
  "data": {
    "qrDataURL": "<QRDATAURL_OMITTED>",
    "qrImageUrl": "<QRIMAGEURL_OMITTED>",
    "template": "frame",
    "decodedQrCode": "https://developer.example.com/payment/?qr=da58fde344a1e0c9280207e1143c6f40",
    "deeplink": "https://developer.example.com/payment/?qr=da58fde344a1e0c9280207e1143c6f40",
    "signature": "<SIGNATURE>",
    "timeStamp": "1791659974931",
    "orderId": "DEMO17916599748852455",
    "amount": 100000,
    "status": "processing",
    "traceNumber": "DEMOQR50269d422b61",
    "qrData": "https://developer.example.com/payment/?qr=da58fde344a1e0c9280207e1143c6f40",
    "transactionId": "da58fde344a1e0c9280207e1143c6f40",
    "requestID": "DEMO-6e40f8301889"
  }
}