Tạo link thanh toán

API này cho phép đối tác tạo một đường dẫn thanh toán (Checkout URL) để gửi cho khách hàng. Khách hàng truy cập đường dẫn này có thể thanh toán qua nhiều hình thức (VietQR, Thẻ, Pay-by-Bank...) được cấu hình sẵn cho Merchant.

POST

URLhttps://open-api.tingee.vn/v1/payment-gateway/create-link

Tạo một đường dẫn thanh toán (Checkout URL) để gửi cho khách hàng.

1. Request Headers

Header	Type	Bắt buộc	Mô tả
x-client-id	string	✓	Client ID của Merchant được cấp bởi Tingee.
x-request-timestamp	string	✓	Thời gian gửi request (định dạng UNIX timestamp milliseconds).
x-signature	string	✓	Chữ ký xác thực request để đảm bảo tính toàn vẹn dữ liệu.

2. Request Body (JSON)

Thuộc tính	Kiểu	Bắt buộc	Mô tả
requestId	string	✓	Mã request định danh. (Max: 36 char, chuẩn UUID v4)
orderId	string	✓	Mã đơn hàng trên hệ thống của bạn. (Max: 100 char, chỉ chứa chữ, số, -, _)
amount	number	✓	Số tiền cần thanh toán. (Min: 2,000, Max: 10,000,000,000)
merchantId	number	✕	Mã Merchant. (Bắt buộc nếu kết nối bằng tài khoản Master Merchant).
currency	string	✕	Đơn vị tiền tệ. Mặc định là VND. (Max: 10 char)
expireInMinute	number	✕	Thời gian hết hạn của link tính bằng phút. Mặc định là 30. (Min: 5, Max: 30)
description	string	✕	Mô tả ngắn gọn về giao dịch hiển thị trên cổng thanh toán. (Max: 200 char)
orderInfo	string	✕	Thông tin bổ sung nội bộ về đơn hàng. (Max: 1000 char)
customerEmail	string	✕	Email khách hàng.
vaAccountNumber	string	✕	Số tài khoản ảo (Virtual Account) nếu bạn muốn chỉ định nhận đích danh. (Max: 50 char)
returnUrl	string	✕	URL (hoặc App Scheme) điều hướng khách hàng về lại web/app của bạn sau khi thanh toán xong. (Max: 500 char, chuẩn URL)

Ví dụ Request:

{
  "requestId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "orderId": "INV-0012345",
  "amount": 500000,
  "description": "Thanh toán đơn hàng INV-0012345",
  "returnUrl": "https://your-shop.com/checkout/success"
}

3. Response

API sẽ trả về thông tin đường dẫn thanh toán (Checkout URL) bên trong đối tượng data.

Thuộc tính	Kiểu	Mô tả
code	string	Mã trạng thái kết quả. 00 là thành công.
message	string	Thông báo chi tiết trạng thái.
data	string	Đường dẫn thanh toán (Checkout URL) mà bạn cần chuyển hướng (redirect) khách hàng tới.

Ví dụ Response Thành công (HTTP 200 OK):

{
  "code": "00",
  "message": "Success",
  "data": "https://payment-gateway.tingee.vn/checkout?token=base64urlEncodedToken&s=hmacSha256Signature"
}

4. IPN (Webhook) Trả Về

Khi khách hàng thanh toán thành công hoặc đơn hàng có sự thay đổi trạng thái (hết hạn, bị hủy), Tingee sẽ tự động gửi một HTTP POST request (Webhook/IPN) chứa dữ liệu JSON về Đường dẫn IPN mà bạn đã cấu hình trên Tingee Merchant Portal.

Thuộc tính	Kiểu	Mô tả
requestId	string	Mã request của webhook (UUID).
orderId	string	Mã đơn hàng tương ứng trên hệ thống của bạn.
amount	number	Số tiền yêu cầu thanh toán ban đầu của đơn hàng.
paidAmount	number	Số tiền khách hàng đã thanh toán thực tế.
description	string	Mô tả giao dịch.
orderInfo	string	Thông tin bổ sung của đơn hàng (nếu có).
status	string	Trạng thái đơn hàng (ví dụ: success, expired, canceled).
statusCode	string	Mã trạng thái kết quả (ví dụ: 00 là thành công).
billId	string	Mã giao dịch phía Tingee (nếu có).
customerEmail	string	Email của khách hàng.
paymentMethod	string	Hình thức thanh toán khách hàng đã sử dụng (ví dụ: qr).
providerTransactionCode	string	Mã giao dịch ghi nhận từ đối tác/ngân hàng.
paidAt	string	Thời gian ghi nhận thanh toán (định dạng ISO 8601).
merchantId	number	Mã định danh Merchant trên Tingee.

Ví dụ Payload Webhook:

{
  "requestId": "e5700594-6c7f-4ce9-91d8-82d4e621ff78",
  "orderId": "SDK-1779119517852",
  "amount": 2000,
  "paidAmount": 2000,
  "description": "Thanh toan don hang test SDK",
  "orderInfo": null,
  "status": "success",
  "statusCode": "00",
  "billId": null,
  "customerEmail": null,
  "paymentMethod": "qr",
  "providerTransactionCode": "1927ee3a-7778-4500-9b4e-55363fa4a762",
  "paidAt": "2026-05-18T15:52:42.315Z",
  "merchantId": 29267
}