Tích hợp Payment Gateway: Hướng dẫn từ đầu đến cuối cho developer

[Frontend]  →  POST /create-order  →  [Backend của bạn]
                                             │
                                   POST /openapi/v1/payment/create
                                             │
                                       [TConnect API]
                                             │
                               ┌─────────────┴──────────────┐
                          [Ngân hàng]                  [Ví điện tử]
                               │
                    redirect_url / deeplink trả về
                               │
                       [Khách thanh toán]
                               │
                    IPN Callback → [Backend của bạn]
                               │
                    Cập nhật trạng thái đơn hàng

function login(base_url, username, password, client_id, client_secret):
    payload = {
        username:      username,
        password:      password,
        client_id:     client_id,
        client_secret: client_secret,
        grant_type:    "password"
    }
    POST {base_url}/openapi/v1/auth/login
        body: payload
 
    return response.access_token, response.refresh_token

function encrypt_payload(data, aes_key):
    iv         = generate random 16 bytes
    plaintext  = json_encode(data) as UTF-8 bytes
    ciphertext = AES_256_CBC_encrypt(plaintext, key=aes_key, iv=iv)
    return hex_encode(iv + ciphertext)
 
function decrypt_response(hex_data, aes_key):
    raw        = hex_decode(hex_data)
    iv         = first 16 bytes of raw
    ciphertext = remaining bytes of raw
    plaintext  = AES_256_CBC_decrypt(ciphertext, key=aes_key, iv=iv)
    return json_decode(plaintext)

function create_payment(base_url, partner_code, access_token, aes_key, order_data):
    payload = {
        order_id:       order_data.id,
        amount:         order_data.amount,   // VND, không có số thập phân
        currency:       "VND",
        description:    order_data.description,
        return_url:     "https://yoursite.com/payment/return",
        cancel_url:     "https://yoursite.com/payment/cancel",
        ipn_url:        "https://yoursite.com/webhook/ipn",
        payment_method: "all",               // hoặc "card", "wallet", "qr"
        buyer_info: {
            name:  order_data.customer_name,
            email: order_data.customer_email,
            phone: order_data.customer_phone
        }
    }
 
    encrypted = encrypt_payload(payload, aes_key)
 
    POST {base_url}/openapi/v1/payment/create
        body: { data: encrypted }
        headers:
            Authorization:  "Bearer {access_token}"
            Partner-Code:   partner_code
            Content-Type:   "application/json"
 
    result = decrypt_response(response.data, aes_key)
    return result.payment_url   // redirect khách đến đây

// IPN endpoint: POST /webhook/ipn
function ipn_handler(request):
    body = parse_json(request)
 
    // 1. Decrypt
    txn = decrypt_response(body.data, AES_KEY)
 
    // 2. Idempotency — tránh xử lý 2 lần
    if cache.get("ipn:{txn.request_id}") exists:
        return { status: "ok" }
    cache.set("ipn:{txn.request_id}", ttl=86400)
 
    // 3. Xử lý theo trạng thái
    if txn.status == "SUCCESS":
        mark_order_paid(txn.order_id, txn.amount)
    else if txn.status == "FAILED":
        mark_order_failed(txn.order_id)
 
    // 4. Bắt buộc trả 200 — TConnect retry nếu không nhận được
    return { status: "ok" }

function check_payment_status(base_url, partner_code, access_token, aes_key, order_id):
    payload   = { order_id: order_id }
    encrypted = encrypt_payload(payload, aes_key)
 
    POST {base_url}/openapi/v1/payment/query
        body: { data: encrypted }
        headers:
            Authorization: "Bearer {access_token}"
            Partner-Code:  partner_code
 
    return decrypt_response(response.data, aes_key)