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

composer require sepay/sepay-pg

Khởi tạo Client

Khởi tạo

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ố

Tên	Loại	Bắt buộc	Mô tả
`SP-TEST-XXXXXXX`	string	Bắt buộc	Mã đơn vị merchant
`spsk_live_x...`	string	Bắt buộc	Khóa bảo mật merchant
`SePayClient::ENVIRONMENT_...`	string	Bắt buộc	Biến môi trường (ENVIRONMENT_SANDBOX hoặc ENVIRONMENT_PRODUCTION)
`[]`	array	Không bắt buộc	Mảng các giá trị cấu hình khác

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

PHP

[
    '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)

Khởi tạo thanh toán một lần

$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

Tên	Loại	Bắt buộc	Mô tả
`operation`	string	Bắt buộc	Loại giao dịch, hiện chỉ hỗ trợ: PURCHASE
`orderInvoiceNumber`	string	Bắt buộc	Mã đơn hàng/hoá đơn (duy nhất)
`orderAmount`	string	Bắt buộc	Số tiền giao dịch
`currency`	string	Bắt buộc	Đơn vị tiền tệ (VD: VND, USD)
`paymentMethod`	string	Không bắt buộc	Phương thức thanh toán: CARD, BANK_TRANSFER
`orderDescription`	string	Không bắt buộc	Mô tả đơn hàng
`customerId`	string	Không bắt buộc	Mã khách hàng (nếu có)
`successUrl`	string	Không bắt buộc	URL callback khi thanh toán thành công
`errorUrl`	string	Không bắt buộc	URL callback khi xảy ra lỗi
`cancelUrl`	string	Không bắt buộc	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ệ

Form thanh toán

<form method="POST" action="https://pay.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); // milliseconds

API

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

Tra cứu danh sách đơn hàng

$orders = $sepay->orders()->list([
    'per_page' => 10,
    'order_status' => 'CAPTURED',
    'from_created_at' => '2025-01-01',
    'to_created_at' => '2025-12-31',
]);

Xem chi tiết đơn hàng

$order = $sepay->orders()->retrieve('ORDER_INVOICE_NUMBER');

Hủy giao dịch đơn hàng

$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

PHP

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