Bắt đầu nhanh với Cổng thanh toán HiTechCloud Pay
Bắt đầu với Cổng thanh toán HiTechCloud Pay trong năm bước: đăng ký tài khoản, tạo form checkout, cấu hình IPN, kiểm thử trên sandbox và go-live.
Hướng dẫn từng bước tích hợp cổng thanh toán HiTechCloud Pay vào ứng dụng của bạn trong 5 phút với phương thức quét mã QR chuyển khoản ngân hàng tự động.
Bước 1: Đăng ký tài khoản và Lấy API Key
- Truy cập
https://my.hitechcloud.vnvà đăng ký hoặc đăng nhập tài khoản. - Vào mục Cổng thanh toán → chọn Phương thức thanh toán.
- Chọn Bắt đầu ngay với môi trường Sandbox để nhận thông tin tích hợp thử nghiệm.
- Hệ thống sẽ cấp cho bạn:
MERCHANT ID(ví dụ:HTC_MCH_123456) vàSECRET KEY(chuỗi bí mật dùng để ký HMAC). Lưu lại hai giá trị này.
Bước 2: Tạo form thanh toán trên website của bạn
Bạn có thể sử dụng SDK chính thức hoặc tạo form POST HTML trực tiếp với chữ ký số HMAC-SHA256.
<?php
// Cấu hình thông tin tích hợp
$merchant_id = "YOUR_MERCHANT_ID";
$secret_key = "YOUR_SECRET_KEY";
// Môi trường: Sandbox hoặc Production
$checkout_url = "https://pay-sandbox.hitechcloud.vn/v1/checkout/init";
// Khi go-live đổi sang: "https://pay-gateways.hitechcloud.vn/v1/checkout/init"
$data = [
'merchant_id' => $merchant_id,
'operation' => 'PURCHASE',
'order_invoice_number' => 'INV-' . time(),
'order_amount' => 100000,
'order_currency' => 'VND',
'order_description' => 'Thanh toan don hang test',
'success_url' => 'https://example.com/payment/success',
'error_url' => 'https://example.com/payment/error',
'cancel_url' => 'https://example.com/payment/cancel',
];
// Tạo chữ ký HMAC-SHA256 từ các tham số sắp xếp theo key
ksort($data);
$sign_string = urldecode(http_build_query($data));
$signature = hash_hmac('sha256', $sign_string, $secret_key);
$data['signature'] = $signature;
?>
<!-- Render Form POST tự động gửi sang Cổng thanh toán HiTechCloud Pay -->
<form id="hitechcloud_checkout_form" action="<?= htmlspecialchars($checkout_url) ?>" method="POST">
<?php foreach ($data as $key => $val): ?>
<input type="hidden" name="<?= htmlspecialchars($key) ?>" value="<?= htmlspecialchars($val) ?>" />
<?php endforeach; ?>
<button type="submit" class="btn btn-primary">Thanh toán qua HiTechCloud Pay</button>
</form>const crypto = require('crypto');
function createCheckoutPayload(order) {
const merchantId = process.env.HITECHCLOUD_PAY_MERCHANT_ID;
const secretKey = process.env.HITECHCLOUD_PAY_SECRET_KEY;
const isProd = process.env.NODE_ENV === 'production';
const checkoutUrl = isProd
? 'https://pay-gateways.hitechcloud.vn/v1/checkout/init'
: 'https://pay-sandbox.hitechcloud.vn/v1/checkout/init';
const params = {
merchant_id: merchantId,
operation: 'PURCHASE',
order_invoice_number: order.invoiceNumber,
order_amount: order.amount,
order_currency: 'VND',
order_description: order.description,
success_url: 'https://example.com/payment/success',
error_url: 'https://example.com/payment/error',
cancel_url: 'https://example.com/payment/cancel',
};
// Sắp xếp key theo alphabet và tạo chuỗi ký
const sortedKeys = Object.keys(params).sort();
const signString = sortedKeys.map(k => `${k}=` + params[k]).join('&');
const signature = crypto.createHmac('sha256', secretKey).update(signString).digest('hex');
return { checkoutUrl, fields: { ...params, signature } };
}import hmac
import hashlib
import urllib.parse
import time
def generate_checkout_payload(order_invoice: str, amount: int, description: str):
merchant_id = "YOUR_MERCHANT_ID"
secret_key = "YOUR_SECRET_KEY"
checkout_url = "https://pay-sandbox.hitechcloud.vn/v1/checkout/init"
params = {
"merchant_id": merchant_id,
"operation": "PURCHASE",
"order_invoice_number": order_invoice,
"order_amount": str(amount),
"order_currency": "VND",
"order_description": description,
"success_url": "https://example.com/payment/success",
"error_url": "https://example.com/payment/error",
"cancel_url": "https://example.com/payment/cancel",
}
# Sắp xếp theo key A-Z
sorted_pairs = sorted(params.items(), key=lambda x: x[0])
sign_string = "&".join(f"{k}={v}" for k, v in sorted_pairs)
signature = hmac.new(
secret_key.encode('utf-8'),
sign_string.encode('utf-8'),
hashlib.sha256
).hexdigest()
params["signature"] = signature
return {"checkout_url": checkout_url, "params": params}package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
"sort"
"strings"
)
func GenerateCheckoutSignature(params map[string]string, secretKey string) string {
keys := make([]string, 0, len(params))
for k := range params {
if k != "signature" {
keys = append(keys, k)
}
}
sort.Strings(keys)
var parts []string
for _, k := range keys {
parts = append(parts, fmt.Sprintf("%s=%s", k, params[k]))
}
signString := strings.Join(parts, "&")
mac := hmac.New(sha256.New, []byte(secretKey))
mac.Write([]byte(signString))
return hex.EncodeToString(mac.Sum(nil))
}using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
public class HiTechCloudCheckout
{
public static string CreateSignature(Dictionary<string, string> parameters, string secretKey)
{
var sortedParams = parameters
.Where(p => p.Key != "signature")
.OrderBy(p => p.Key, StringComparer.Ordinal)
.Select(p => $"{p.Key}={p.Value}");
string rawData = string.Join("&", sortedParams);
using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey)))
{
byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawData));
return BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant();
}
}
}Bước 3: Cấu hình và Xử lý IPN (Instant Payment Notification)
IPN là cơ chế thông báo Server-to-Server. Khi khách chuyển khoản thành công, máy chủ HiTechCloud Pay sẽ gửi một HTTP POST request chứa dữ liệu giao dịch đến URL IPN của bạn.
{
"timestamp": 1759134682,
"notification_type": "ORDER_PAID",
"order": {
"id": "e2c195be-c721-47eb-b323-99ab24e52d85",
"order_id": "HTC-68DA43D73C1A5",
"order_status": "CAPTURED",
"order_currency": "VND",
"order_amount": "100000.00",
"order_invoice_number": "INV-1759134677",
"order_description": "Thanh toan don hang test"
},
"transaction": {
"id": "384c66dd-41e6-4316-a544-b4141682595c",
"payment_method": "BANK_TRANSFER",
"transaction_id": "68da43da2d9de",
"transaction_type": "PAYMENT",
"transaction_date": "2025-09-29 15:31:22",
"transaction_status": "APPROVED",
"transaction_amount": "100000",
"transaction_currency": "VND"
}
}<?php
// Endpoint nhận IPN: https://example.com/payment/ipn
$raw_input = file_get_contents('php://input');
$data = json_decode($raw_input, true);
if (!$data || !isset($data['notification_type'])) {
http_response_code(400);
echo json_encode(['success' => false, 'message' => 'Invalid payload']);
exit;
}
if ($data['notification_type'] === 'ORDER_PAID') {
$invoice_number = $data['order']['order_invoice_number'];
$amount = $data['transaction']['transaction_amount'];
$trans_id = $data['transaction']['transaction_id'];
// 1. Kiểm tra đơn hàng trong CSDL nội bộ
// 2. Chống xử lý trùng lặp bằng transaction_id
// 3. Đánh dấu đơn hàng ĐÃ THANH TOÁN (Paid) và cấp phát dịch vụ
}
// Bắt buộc phản hồi HTTP 200 kèm {"success": true}
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['success' => true]);Bước 4: Kiểm thử trên Sandbox
Tạo đơn hàng trên form của bạn. Trình duyệt chuyển hướng đến trang thanh toán giả lập của HiTechCloud Pay. Tại đây bạn bấm nút 'Mô phỏng thanh toán thành công' để hệ thống tự động bắn IPN và chuyển hướng về success_url của bạn.
Bước 5: Chuyển sang Production (Go-Live)
- Đăng nhập
https://my.hitechcloud.vn→ Cổng thanh toán → Chọn Chuyển sang Production. - Liên kết tài khoản ngân hàng nhận tiền thật của doanh nghiệp hoặc cá nhân.
- Lấy
MERCHANT IDvàSECRET KEYcủa Production. - Thay đổi endpoint checkout thành
https://pay-gateways.hitechcloud.vn/v1/checkout/init. - Thay đổi endpoint REST API tra cứu thành
https://pgapi.hitechcloud.vn. - Cập nhật URL IPN và các Callback URL sang máy chủ Production của bạn.