Bắt đầu nhanh

Chức năng chính

• Xử lý thanh toán: Tiếp nhận thông tin thanh toán từ khách hàng
• Bảo mật giao dịch: Mã hóa và bảo vệ dữ liệu thanh toán
• Kết nối ngân hàng: Giao tiếp với các ngân hàng và tổ chức thẻ
• Thông báo kết quả: Gửi thông tin giao dịch về hệ thống của bạn

Luồng hoạt động tổng quan

Bắt đầu với Quét mã QR chuyển khoản ngân hàng

Bước 1: Đăng ký tài khoản

Truy cập https://my.sepay.vn/register và đăng ký tài khoản SePay. Chọn gói dịch vụ phù hợp sau khi đăng ký.

Nếu đã có tài khoản, truy cập https://my.sepay.vn/pg/payment-methods để kích hoạt Cổng thanh toán.

Kích hoạt Cổng thanh toán:

Tại mục "CỔNG THANH TOÁN" vào "Đăng ký". Tại màn hình "Phương thức thanh toán" chọn "Bắt đầu ngay":

Nhấn để phóng to

Bạn có thể chọn bắt đầu với Sandbox và bấm vào "Bắt đầu hướng dẫn tích hợp":

Nhấn để phóng to

SePay hỗ trợ phương thức tích hợp bằng API với SDK PHP và SDK NodeJS. Bấm tiếp tục:

Nhấn để phóng to

Bạn sẽ nhận được thông tin tích hợp (sao chép lại thông tin MERCHANT ID và SECRET KEY để sử dụng cho các bước sau), giữ lại màn hình này và thực hiện tiếp các bước sau:

Nhấn để phóng to

Bước 2: Tạo form thanh toán trên hệ thống của bạn

Cài đặt SDK (tùy chọn PHP hoặc NodeJS)

composer require sepay/sepay-pg

Khởi tạo form thanh toán với các thông tin đơn hàng và chữ ký bảo mật:

• YOUR_MERCHANT_ID: MERCHANT ID bạn đã sao chép trên thông tin tích hợp ở bước 1
• YOUR_MERCHANT_SECRET_KEY: SECRET KEY bạn đã sao chép trên thông tin tích hợp ở bước 1

<?php
 
require_once 'vendor/autoload.php';
 
use SePay\SePayClient;
use SePay\Builders\CheckoutBuilder;
 
// Initialize client
$sepay = new SePayClient('YOUR_MERCHANT_ID', 'YOUR_MERCHANT_SECRET_KEY', 'sandbox');
 
// Create checkout data
$checkoutData = CheckoutBuilder::make()
    ->currency('VND')
    ->orderInvoiceNumber('INV-' . time())
    ->orderAmount(100000)
    ->operation('PURCHASE')
    ->orderDescription('Test payment')
    ->successUrl('https://example.com/order/DH123?payment=success')
    ->errorUrl('https://example.com/order/DH123?payment=error')
    ->cancelUrl('https://example.com/order/DH123?payment=cancel')
    ->build();
 
// Render checkout form to UI
echo $sepay->checkout()->generateFormHtml($checkoutData);
 

Kết quả nhận được form thanh toán (Tùy chỉnh giao diện phù hợp với hệ thống của bạn):

Nhấn để phóng to

Khi submit form thanh toán sẽ chuyển sang cổng thanh toán của SePay:

Nhấn để phóng to

Tạo các endpoint để nhận các callback từ SePay:

// success_url - Handle successful payment
Route::get('/payment/success', function() {
  // Show success page to customer
  return view('payment.success');
});
 
// error_url - Handle failed payment
Route::get('/payment/error', function() {
  // Show error page to customer
  return view('payment.error');
});
 
// cancel_url - Handle canceled payment
Route::get('/payment/cancel', function() {
  // Show cancel page to customer
  return view('payment.cancel');
});

Đưa các endpoint bạn đã tạo vào success_url, error_url, cancel_url lúc tạo form thanh toán.

Bước 3: Cấu hình IPN

Tại màn hình thông tin tích hợp đang giữ ở bước 1, điền vào endpoint IPN của bạn:

Nhấn để phóng to

Lưu cấu hình IPN.

{
  "timestamp": 1759134682,
  "notification_type": "ORDER_PAID",
  "order": {
      "id": "e2c195be-c721-47eb-b323-99ab24e52d85",
      "order_id": "NQD-68DA43D73C1A5",
      "order_status": "CAPTURED",
      "order_currency": "VND",
      "order_amount": "100000.00",
      "order_invoice_number": "INV-1759134677",
      "custom_data": [],
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
      "ip_address": "14.186.39.212",
      "order_description": "Test payment"
  },
  "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",
      "authentication_status": "AUTHENTICATION_SUCCESSFUL",
      "card_number": null,
      "card_holder_name": null,
      "card_expiry": null,
      "card_funding_method": null,
      "card_brand": null
  },
  "customer": null,
  "agreement": null
}

Tạo endpoint IPN để nhận JSON data từ SePay

Endpoint là endpoint bạn đã cấu hình trên IPN:

Route::post('/payment/ipn', function(Request $request) {
  $data = $request->json()->all();
 
  if ($data['notification_type'] === 'ORDER_PAID') {
      $order = Order::where('invoice_number', $data['order']['order_invoice_number'])->first();
      $order->status = 'paid';
      $order->save();
  }
 
  // Return 200 to acknowledge receipt
  return response()->json(['success' => true], 200);
});

Bước 4: Kiểm thử

Bây giờ bạn có thể kiểm thử bằng cách tạo một đơn hàng trên form vừa tích hợp ở bước 2.

Sau đó quay lại màn hình thông tin tích hợp và bấm tiếp tục để kiểm tra kết quả:

Nhấn để phóng to

Kịch bản:

• Khi người dùng gửi form thanh toán trên website của bạn, hệ thống sẽ chuyển hướng đến trang thanh toán của SePay.
• Khi thanh toán thành công: SePay chuyển hướng về endpoint /payment/success của bạn và gửi dữ liệu cho endpoint IPN bạn đã cấu hình
• Khi thanh toán thất bại: SePay chuyển hướng về endpoint /payment/error
• Khi hủy thanh toán: SePay chuyển hướng về endpoint /payment/cancel

Bước 5: Go live

Các bước cần thực hiện:

1. Liên kết tài khoản ngân hàng thật
2. Từ https://my.sepay.vn/ vào mục Cổng thanh toán chọn Đăng ký → Tại mục "Quét mã QR chuyển khoản ngân hàng" chọn "Bắt đầu ngay" và tiếp tục cho đến màn hình như ảnh bên dưới và chọn "Chuyển sang Production"

Nhấn để phóng to

3. Sau khi Chuyển sang Production sẽ nhận được "MERCHANT ID" và "SECRET KEY" chính thức

Nhấn để phóng to

4. Cập nhật endpoint sang Production: https://pay.sepay.vn/v1/checkout/init
5. Đối với trường hợp dùng SDK: cập nhật các biến môi trường từ Sandbox sang Production (khi khởi tạo client)
6. Cập nhật "MERCHANT ID" và "SECRET KEY" của Sandbox thành "MERCHANT ID" và "SECRET KEY" chính thức
7. Cập nhật IPN URL sang Production
8. Cập nhật các Callback URL sang Production