PHP SDK

SDK PHP chính thức cho Cổng thanh toán SePay. Tích hợp dễ dàng thanh toán, chuyển khoản ngân hàng, VietQR và thanh toán định kỳ.

Yêu cầu

PHP 7.4 trở lên, ext-json, ext-curl, Guzzle HTTP client

Cài đặt

JSCài đặt
1
composer require sepay/sepay-pg

Khởi tạo Client

PHPKhởi tạo
1
2
3
4
5
6
7
8
9
10
use SePay\SePayClient;
use SePay\Builders\CheckoutBuilder;
 
// Initialize client
$sepay = new SePayClient(
  'SP-TEST-XXXXXXX',
  'spsk_live_xxxxxxxxxxxo99PoE7RsBpss3EFH5nV',
  SePayClient::ENVIRONMENT_SANDBOX, // or ENVIRONMENT_PRODUCTION
 []
);

Giải thích tham số

SP-TEST-XXXXXXXstringrequired
Mã đơn vị merchant
spsk_live_x...stringrequired
Khóa bảo mật merchant
SePayClient::ENVIRONMENT_...stringrequired
Biến môi trường (ENVIRONMENT_SANDBOX hoặc ENVIRONMENT_PRODUCTION)
[]array
Mảng các giá trị cấu hình khác

Ví dụ các cấu hình khác:

PHPPHP
1
2
3
4
5
6
7
8
[
  'timeout' => 60,           // Thời gian chờ của request (tính bằng giây)
  'retry_attempts' => 5,     // Số lần thử lại khi request thất bại
  'retry_delay' => 2000,     // Thời gian trễ giữa các lần thử lại (tính bằng mili giây)
  'debug' => true,           // Bật chế độ debug (ghi log chi tiết)
  'user_agent' => 'MyApp/1.0 SePay-PHP-SDK/1.0.0', // Chuỗi định danh ứng dụng gửi đi trong request
  'logger' => $customLogger, // Logger tương thích chuẩn PSR-3
];

Khởi tạo đối tượng cho biểu mẫu thanh toán (Đơn hàng thanh toán 1 lần)

PHPKhởi tạo thanh toán một lần
1
2
3
4
5
6
7
8
9
10
11
$checkoutData = CheckoutBuilder::make()
  ->currency('VND')
  ->orderAmount(100000) // 100,000 VND
  ->operation('PURCHASE')
  ->orderDescription('Test payment')
  ->orderInvoiceNumber('INV_001')
  ->successUrl('https://yoursite.com/success')
  ->build();
 
// Create form fields with signature
$formFields = $sepay->checkout()->generateFormFields($checkoutData);

Giải thích thuộc tính

operationstringrequired
Loại giao dịch, hiện chỉ hỗ trợ: PURCHASE
orderInvoiceNumberstringrequired
Mã đơn hàng/hoá đơn (duy nhất)
orderAmountstringrequired
Số tiền giao dịch
currencystringrequired
Đơn vị tiền tệ (VD: VND, USD)
paymentMethodstring
Phương thức thanh toán: CARD, BANK_TRANSFER
orderDescriptionstring
Mô tả đơn hàng
customerIdstring
Mã khách hàng (nếu có)
successUrlstring
URL callback khi thanh toán thành công
errorUrlstring
URL callback khi xảy ra lỗi
cancelUrlstring
URL callback khi người dùng hủy thanh toán

Tạo form xử lý thanh toán

Lưu ý quan trọng về tạo form HTML và chữ ký

Nếu bạn tự dựng form HTML và xây dựng hàm tạo chữ ký không theo code mẫu thì cần phải đảm bảo thứ tự các trường giống như danh sách tham số ở trên để quá trình ký khớp tuyệt đối phía SePay; Nếu bạn hoán đổi vị trí các trường thì có thể dẫn đến chữ ký bị sai và SePay sẽ xem yêu cầu này là không hợp lệ

JSForm thanh toán
1
2
3
4
5
6
7
<form method="POST" action="https://pay-sandbox.sepay.vn/checkout/init">
  <?php foreach ($formFields as $name => $value): ?>
      <input type="hidden" name="<?= htmlspecialchars($name) ?>" value="<?= htmlspecialchars($value) ?>">
  <?php endforeach; ?>
 
  <button type="submit">Thanh toán ngay</button>
</form>
Ghi chú

Bật chế độ debug: $sepay->enableDebugMode(); - Cấu hình hành vi thử lại: $sepay->setRetryAttempts(3)->setRetryDelay(1000);

API

SDK cung cấp các phương thức để gọi Open API cho cổng thanh toán SePay.

PHPTra cứu danh sách đơn hàng
1
2
3
4
5
6
$orders = $sepay->orders()->list([
  'per_page' => 10,
  'order_status' => 'CAPTURED',
  'from_created_at' => '2025-01-01',
  'to_created_at' => '2025-12-31',
]);
PHPXem chi tiết đơn hàng
1
$order = $sepay->orders()->retrieve('ORDER_INVOICE_NUMBER');
JSHủy giao dịch đơn hàng
1
$result = $sepay->orders()->voidTransaction('ORDER_INVOICE_NUMBER');
Ghi chú

Đơn hàng được tạo khi khách hàng hoàn tất thanh toán, không phải trực tiếp thông qua API.

Xử lý lỗi

The SDK has different exception types for different errors

PHPPHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
use SePay\Exceptions\AuthenticationException;
use SePay\Exceptions\ValidationException;
use SePay\Exceptions\NotFoundException;
use SePay\Exceptions\RateLimitException;
use SePay\Exceptions\ServerException;
 
try {
  $order = $sepay->orders()->retrieve('ORDER_INVOICE_NUMBER');
} catch (AuthenticationException $e) {
  // Invalid credentials or signature
  echo "Authentication failed: " . $e->getMessage();
} catch (ValidationException $e) {
  // Invalid request data
  echo "Validation error: " . $e->getMessage();
 
  // Get field-specific errors
  if ($e->hasFieldError('amount')) {
      $errors = $e->getFieldErrors('amount');
      echo "Amount errors: " . implode(', ', $errors);
  }
} catch (NotFoundException $e) {
  // Resource not found
  echo "Not found: " . $e->getMessage();
} catch (RateLimitException $e) {
  // Rate limit exceeded
  echo "Rate limited. Retry after: " . $e->getRetryAfter() . " seconds";
} catch (ServerException $e) {
  // Server error (5xx)
  echo "Server error: " . $e->getMessage();
}

Kiểm thử

Lệnh kiểm tra
# Chạy toàn bộ test
composer test

# Chạy test kèm báo cáo độ bao phủ mã (coverage)
composer test-coverage

# Phân tích tĩnh mã nguồn (static analysis)
composer phpstan

# Sửa định dạng mã nguồn (code style)
composer cs-fix

Xem chi tiết hướng dẫn cài đặt và sử dụng tại GitHub Repository

Trước
—
Tiếp theo
—