english/.opencode/skills/payment-integration/references/sepay/sdk.md

SePay SDK Integration

Official SDKs for Node.js, PHP, and Laravel.

Node.js SDK (sepay-pg-node)

Installation:

npm install github:sepay/sepay-pg-node

Requirements: Node.js 16+

Configuration:

import { SePayPgClient } from 'sepay-pg-node';

const client = new SePayPgClient({
  env: 'sandbox',  // or 'production'
  merchant_id: 'SP-TEST-XXXXXXX',
  secret_key: 'spsk_test_xxxxxxxxxxxxx',
});

Create Payment:

const fields = client.checkout.initOneTimePaymentFields({
  operation: 'PURCHASE',
  order_invoice_number: 'DH0001',
  order_amount: 10000,
  currency: 'VND',
  success_url: 'https://example.com/success',
  error_url: 'https://example.com/error',
  cancel_url: 'https://example.com/cancel',
  order_description: 'Payment for order DH0001',
});

Render Payment Form:

<form action={client.checkout.initCheckoutUrl()} method="POST">
  {Object.keys(fields).map(field =>
    <input type="hidden" name={field} value={fields[field]} key={field} />
  )}
  <button type="submit">Pay Now</button>
</form>

API Methods:

// List all orders
await client.order.all({
  per_page: 50,
  q: 'search_term',
  order_status: 'completed',
  from_created_at: '2025-01-01',
  to_created_at: '2025-01-31'
});

// Get order details
await client.order.retrieve('DH0001');

// Void transaction (cards only)
await client.order.voidTransaction('DH0001');

// Cancel order (QR payments)
await client.order.cancel('DH0001');

Endpoints:

• Sandbox: https://sandbox.pay.sepay.vn/v1/init
• Production: https://pay.sepay.vn/v1/init

PHP SDK (sepay/sepay-pg)

Installation:

composer require sepay/sepay-pg

Requirements: PHP 7.4+, ext-json, ext-curl, Guzzle

Quick Start:

use SePay\SePayClient;
use SePay\Builders\CheckoutBuilder;

$sepay = new SePayClient(
    'SP-TEST-XXXXXXX',
    'spsk_live_xxxxxxxxxxxxx',
    SePayClient::ENVIRONMENT_SANDBOX
);

$checkoutData = CheckoutBuilder::make()
    ->currency('VND')
    ->orderAmount(100000)
    ->operation('PURCHASE')
    ->orderDescription('Test payment')
    ->orderInvoiceNumber('INV_001')
    ->successUrl('https://yoursite.com/success')
    ->errorUrl('https://yoursite.com/error')
    ->cancelUrl('https://yoursite.com/cancel')
    ->build();

echo $sepay->checkout()->generateFormHtml($checkoutData);

Error Handling:

try {
    $order = $sepay->orders()->retrieve('INV_001');
} catch (AuthenticationException $e) {
    // Invalid credentials
} catch (ValidationException $e) {
    // Invalid request data
    $errors = $e->getErrors();
} catch (NotFoundException $e) {
    // Resource not found
} catch (RateLimitException $e) {
    // Rate limit exceeded
    $retryAfter = $e->getRetryAfter();
} catch (ServerException $e) {
    // Server error (5xx)
}

Configuration:

$sepay->setConfig([
    'timeout' => 30,
    'retry_attempts' => 3,
    'retry_delay' => 1000,
    'debug' => true,
    'user_agent' => 'MyApp/1.0',
    'logger' => $psrLogger
]);

Laravel Package (laravel-sepay)

Installation:

composer require sepayvn/laravel-sepay

# For Laravel 7-8 with PHP 7.4+
composer require "sepayvn/laravel-sepay:dev-lite"

Setup:

php artisan vendor:publish --tag="sepay-migrations"
php artisan migrate
php artisan vendor:publish --tag="sepay-config"
php artisan vendor:publish --tag="sepay-views"  # optional

Configuration (.env):

SEPAY_WEBHOOK_TOKEN=your_secret_key
SEPAY_MATCH_PATTERN=SE

Create Event Listener:

php artisan make:listener SePayWebhookListener

Listener Implementation:

<?php

namespace App\Listeners;

use SePayWebhookEvent;

class SePayWebhookListener
{
    public function handle(SePayWebhookEvent $event)
    {
        $transaction = $event->transaction;

        if ($transaction->transfer_type === 'in') {
            // Handle incoming payment
            Order::where('code', $transaction->content)
                ->update(['status' => 'paid']);

            // Send confirmation email
            Mail::to($order->customer->email)
                ->send(new PaymentConfirmation($order));
        }
    }
}

Register Listener:

// app/Providers/EventServiceProvider.php
protected $listen = [
    SePayWebhookEvent::class => [
        SePayWebhookListener::class,
    ],
];

Best Practices

1. Environment Variables: Store credentials securely
2. Error Handling: Catch and log all exceptions
3. Retry Logic: Implement for transient failures
4. Logging: Log all API calls and responses
5. Testing: Use sandbox extensively before production
6. Validation: Validate data before API calls
7. Monitoring: Track success/failure rates