Liên kết thanh toán: hướng dẫn

Liên kết là gì

Liên kết thanh toán là lớp bao bọc quanh các thanh toán. Mỗi khách hàng thanh toán qua liên kết sẽ có một thanh toán riêng, trên cùng trang hosted như mọi thanh toán Qvard khác.

Một thanh toán là một hóa đơn với tỷ giá cố định. Liên kết là điểm vào dùng nhiều lần để tạo các thanh toán đó. Một liên kết có thể tạo nhiều thanh toán, nhưng không thay thế thanh toán.

Liên kết có đơn vị tiền tệ riêng: đơn vị khách hàng nhìn thấy và thanh toán. Mỗi thanh toán cố định tỷ giá khi được tạo. Tỷ giá hiện tại xem tại trang «Tỷ giá tiền tệ».

Tạo liên kết trong dashboard

Trong dashboard, mở mục «Liên kết thanh toán» và thiết lập liên kết. Các tùy chọn gồm:

• Số tiền: cố định, hoặc do khách hàng nhập với mức tối thiểu và tối đa.
• Giới hạn thanh toán: không giới hạn, một lần thanh toán, hoặc N lần thanh toán.
• Thời hạn: 1, 7 hoặc 30 ngày, hoặc không thời hạn.
• Email khách hàng: không hỏi, không bắt buộc, hoặc bắt buộc.

Mỗi liên kết có địa chỉ riêng: https://qvard.com/l/<slug>. Khách hàng mở liên kết, chọn token và mạng, rồi thấy trang thanh toán thông thường.

Bạn có thể tải liên kết dưới dạng mã QR PNG, dùng cho hóa đơn in, biên lai và áp phích. Nút «Chia sẻ» đưa liên kết để bạn gửi qua bất kỳ kênh nào.

Một liên kết cho mỗi khách hàng qua API

Để biết chính xác ai đã thanh toán, hãy tạo thanh toán cho từng khách hàng qua API từ máy chủ của bạn, rồi gửi redirectUrl trong phản hồi cho khách hàng. Khóa bí mật (qvard_sk_…) chỉ được lưu trên máy chủ của bạn.

Ví dụ yêu cầu

# Create a payment for one customer
curl -X POST https://api.qvard.com/api/v1/payment \
  -H 'x-api-key: qvard_sk_YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"price":12499.00,"currency":"INR","id":"order-123"}'

# The response contains "data": { "redirectUrl": "https://my.qvard.com/pay/..." }
# Send that redirectUrl to the customer.

// Run on your server only: the secret key must not reach the browser
async function createPaymentLink(orderId, amount) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ price: amount, currency: 'INR', id: orderId })
  });
  if (!res.ok) throw new Error('Qvard API error: ' + res.status);
  const payment = await res.json();
  return payment.data.redirectUrl; // send this link to the customer
}

// Usage inside an async handler: const link = await createPaymentLink('order-123', 10);

Phản hồi gồm id thanh toán và redirectUrl, ví dụ https://my.qvard.com/pay/<uuid>. Hãy gửi redirectUrl cho khách hàng. Giá trị id trong yêu cầu là số đơn hàng của bạn.

Không đưa khóa bí mật (qvard_sk_…) vào mã chạy trên trình duyệt hay kho mã công khai. Chỉ tạo thanh toán từ máy chủ.

Bán hàng có giới hạn và liên kết một lần

Liên kết một lần nhận một thanh toán, phù hợp với hóa đơn. Liên kết giới hạn N lần thanh toán nhận N lần rồi dừng, phù hợp với ưu đãi có số lượng như 100 suất.

Trạng thái liên kết

• Đang hoạt động: liên kết nhận thanh toán.
• Đã tắt: bạn đã tắt liên kết trong dashboard. Liên kết không nhận thanh toán cho đến khi bật lại.
• Hết hạn: đã qua thời hạn (1, 7 hoặc 30 ngày).
• Đã dùng hết: đã đạt giới hạn thanh toán.

Webhook cho thanh toán từ liên kết

Thanh toán tạo từ liên kết gửi cùng webhook và cùng header X-Qvard-Signature. Nội dung của chúng có hai trường tùy chọn bổ sung: paymentLink là slug của liên kết, và customerEmail là email khách hàng đã nhập, nếu liên kết có yêu cầu. Các thanh toán khác không có các trường này.

Cách xác minh chữ ký webhook

Liên kết không cho biết điều gì

Liên kết dùng nhiều lần không cho biết ai đã thanh toán. Webhook báo về thanh toán, không báo về người mua.

Trường customerEmail không bắt buộc và không được xác minh: khách hàng tự nhập và không ai kiểm tra. Nếu cần biết chính xác người mua, hãy tạo thanh toán qua API cho từng người mua.

Tài liệu tham khảo API