PHP SDK

Official PHP SDK for SePay Payment Gateway. Easily integrate payments, bank transfers, VietQR and recurring payments.

Requirements

PHP 7.4 or higher, ext-json, ext-curl, Guzzle HTTP client

Installation

JSInstallation
1
composer require sepay/sepay-pg

Initialize Client

PHPInitialization
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
 []
);

Parameter explanation

SP-TEST-XXXXXXXstringrequired
Merchant unit code
spsk_live_x...stringrequired
Merchant secret key
SePayClient::ENVIRONMENT_...stringrequired
Environment variable (ENVIRONMENT_SANDBOX or ENVIRONMENT_PRODUCTION)
[]array
Array of other configuration values

Example of other configurations:

PHPPHP
1
2
3
4
5
6
7
8
[
  'timeout' => 60,           // Request timeout (in seconds)
  'retry_attempts' => 5,     // Number of retries when request fails
  'retry_delay' => 2000,     // Delay between retries (in milliseconds)
  'debug' => true,           // Enable debug mode (detailed logging)
  'user_agent' => 'MyApp/1.0 SePay-PHP-SDK/1.0.0', // Application identifier string sent in request
  'logger' => $customLogger, // PSR-3 compatible logger
];

Initialize Payment Form Object (One-time Payment Order)

PHPInitialize one-time payment
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);

Attribute explanation

operationstringrequired
Transaction type, currently only supports: PURCHASE
orderInvoiceNumberstringrequired
Order/invoice number (unique)
orderAmountstringrequired
Transaction amount
currencystringrequired
Currency unit (e.g.: VND, USD)
paymentMethodstring
Payment method: CARD, BANK_TRANSFER
orderDescriptionstring
Order description
customerIdstring
Customer ID (if available)
successUrlstring
Callback URL on successful payment
errorUrlstring
Callback URL on error
cancelUrlstring
Callback URL when user cancels payment

Create payment processing form

Important note about creating HTML form and signature

If you build your own HTML form and signature generation function not following the sample code, you must ensure the field order matches the parameter list above so the signing process matches exactly with SePay; swapping field positions may cause invalid signature and SePay will consider the request invalid

JSPayment form
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">Pay now</button>
</form>
Note

Enable debug mode: $sepay->enableDebugMode(); - Configure retry behavior: $sepay->setRetryAttempts(3)->setRetryDelay(1000);

API

SDK provides methods to call Open API for SePay payment gateway.

PHPQuery order list
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',
]);
PHPView order details
1
$order = $sepay->orders()->retrieve('ORDER_INVOICE_NUMBER');
JSVoid order transaction
1
$result = $sepay->orders()->voidTransaction('ORDER_INVOICE_NUMBER');
Note

Orders are created when customers complete payment, not directly through API.

Error Handling

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();
}

Testing

Test commands
# Run all tests
composer test

# Run tests with coverage report
composer test-coverage

# Static code analysis
composer phpstan

# Fix code style
composer cs-fix

See detailed installation and usage guide at GitHub Repository

Previous page
—
Next page
—