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.

Xem Markdown

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

  1. Truy cập https://my.hitechcloud.vn và đăng ký hoặc đăng nhập tài khoản.
  2. Vào mục Cổng thanh toán → chọn Phương thức thanh toán.
  3. 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.
  4. 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.

Ví dụ khởi tạo Checkout bằng PHP
<?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>
Ví dụ khởi tạo Checkout bằng Node.js (Express)
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 } };
}
Ví dụ khởi tạo Checkout bằng Python (Flask / Django / FastAPI)
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}
Ví dụ khởi tạo Checkout bằng Golang
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))
}
Ví dụ khởi tạo Checkout bằng C# .NET
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.

Cấu trúc dữ liệu JSON do HiTechCloud Pay gửi về IPN
{
  "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"
  }
}
Mã nguồn xử lý IPN endpoint (PHP)
<?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)

  1. Đăng nhập https://my.hitechcloud.vn → Cổng thanh toán → Chọn Chuyển sang Production.
  2. 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.
  3. Lấy MERCHANT ID và SECRET KEY của Production.
  4. Thay đổi endpoint checkout thành https://pay-gateways.hitechcloud.vn/v1/checkout/init.
  5. Thay đổi endpoint REST API tra cứu thành https://pgapi.hitechcloud.vn.
  6. Cập nhật URL IPN và các Callback URL sang máy chủ Production của bạn.