Tạo form thanh toán

Luồng xử lý tạo đơn hàng

1. Khách hàng chọn thanh toán: Người dùng click nút thanh toán trên website
2. Website tạo form HTML: Server tạo form HTML với các tham số cần thiết
3. Thu thập thông tin đơn hàng: Lấy thông tin từ database hoặc session
4. Chuẩn bị dữ liệu form: Sắp xếp các tham số theo đúng format
5. Tạo signature: Sử dụng thuật toán HMAC-SHA256 để tạo chữ ký
6. Thêm signature vào form: Đưa chữ ký vào form như một hidden field
7. Submit form: Gửi POST request đến endpoint checkout/init
8. Xác thực signature: SePay kiểm tra tính hợp lệ của chữ ký
9. Chuyển hướng: Nếu hợp lệ, chuyển hướng đến trang thanh toán
10. Thanh toán: Khách hàng thực hiện thanh toán trên trang SePay
11. Callback: SePay gọi về URL IPN với kết quả

Endpoint

Danh sách tham số

Ví dụ tạo đơn hàng cơ bản

• Tạo form HTML

<form method="POST" action="https://pay-sandbox.sepay.vn/v1/checkout/init">
    <input type="hidden" name="merchant" value="MERCHANT_123">
    <input type="hidden" name="currency" value="VND">
    <input type="hidden" name="order_amount" value="100000">
    <input type="hidden" name="operation" value="PURCHASE">
    <input type="hidden" name="order_description" value="Thanh toán đơn hàng #12345">
    <input type="hidden" name="order_invoice_number" value="INV_20231201_001">
    <input type="hidden" name="customer_id" value="CUST_001">
    <input type="hidden" name="success_url" value="https://yoursite.com/payment/success">
    <input type="hidden" name="error_url" value="https://yoursite.com/payment/error">
    <input type="hidden" name="cancel_url" value="https://yoursite.com/payment/cancel">
    <input type="hidden" name="signature" value="a1b2c3d4e5f6...">
</form>

• Response:

Sau khi submit form, hệ thống sẽ chuyển hướng người dùng đến trang thanh toán của SePay:

Xác thực chữ ký

• Signature được tạo từ các tham số form theo quy tắc sau:

1. Lọc các trường cần ký: Chỉ ký các trường được phép trong danh sách: merchant, operation, payment_method, order_amount, currency, order_invoice_number, order_description, customer_id, success_url, error_url, cancel_url
2. Tạo chuỗi ký: field1=value1,field2=value2,field3=value3...
3. Mã hóa: base64_encode(hash_hmac('sha256', $signedString, $secretKey, true))

• Ví dụ tạo chữ ký:

function signFields(array $fields, string $secretKey): string {
    $signed = [];
    $signedFields = array_values(array_filter(array_keys($fields), fn ($field) => in_array($field, [
        'merchant','operation','payment_method','order_amount','currency',
        'order_invoice_number','order_description','customer_id',
        'success_url','error_url','cancel_url'
    ])));

    foreach ($signedFields as $field) {
        if (! isset($fields[$field])) continue;
        $signed[] = $field . '=' . ($fields[$field] ?? '');
    }

    return base64_encode(hash_hmac('sha256', implode(',', $signed), $secretKey, true));
}

• Ví dụ chuỗi chữ ký: merchant=MERCHANT_123,operation=PURCHASE,order_amount=100000,currency=VND,order_invoice_number=INV_20231201_001,order_description=Thanh toán đơn hàng #12345,customer_id=CUST_001,success_url=https://yoursite.com/success,error_url=https://yoursite.com/error,cancel_url=https://yoursite.com/cancel