@hienlh/ppm 0.9.79 → 0.9.81

package/.opencode/skills/payment-integration/references/sepay/overview.md

@@ -0,0 +1,138 @@
+# SePay Overview
+
+Vietnamese payment automation platform serving as intermediary between applications and banks.
+
+## Core Capabilities
+
+**Payment Methods:**
+- VietQR - QR code bank transfers (NAPAS standard)
+- NAPAS QR - National payment gateway QR
+- Bank Cards - Visa/Mastercard/JCB
+- Bank Transfers - Direct bank-to-bank
+- Virtual Accounts - Order-specific VAs with exact matching
+
+**Supported Banks:** 44+ banks via NAPAS, 37+ with VietQR (Vietcombank, VPBank, BIDV, etc.)
+
+**Use Cases:**
+- Payment gateway for online payments
+- Bank API direct connection
+- Transaction verification automation
+- Real-time balance monitoring
+
+## Authentication
+
+### API Token (Simple)
+
+**Create:**
+1. Company Configuration → API Access → "+ Add API"
+2. Provide name, set status "Active"
+3. Copy token from list
+
+**Usage:**
+```
+Authorization: Bearer {API_TOKEN}
+Content-Type: application/json
+```
+
+**Note:** All tokens have full access (no permission levels currently)
+
+### OAuth2 (Advanced)
+
+**Scopes:**
+- `bank-account:read` - View accounts, balances
+- `transaction:read` - Transaction history
+- `webhook:read/write/delete` - Webhook management
+- `profile` - User information
+- `company` - Company details
+
+**Authorization Code Flow:**
+
+1. **Authorization Request:**
+```
+GET https://my.sepay.vn/oauth/authorize?
+  response_type=code&
+  client_id={CLIENT_ID}&
+  redirect_uri={REDIRECT_URI}&
+  scope={SCOPES}&
+  state={CSRF_TOKEN}
+```
+
+2. **Token Exchange (server-side only):**
+```
+POST https://my.sepay.vn/oauth/token
+{
+  "grant_type": "authorization_code",
+  "client_id": "{CLIENT_ID}",
+  "client_secret": "{CLIENT_SECRET}",
+  "code": "{AUTHORIZATION_CODE}"
+}
+```
+
+3. **Token Refresh:**
+```
+POST https://my.sepay.vn/oauth/token
+{
+  "grant_type": "refresh_token",
+  "refresh_token": "{REFRESH_TOKEN}",
+  "client_id": "{CLIENT_ID}",
+  "client_secret": "{CLIENT_SECRET}"
+}
+```
+
+**Security:** Access tokens expire ~1 hour, never expose client_secret, use state for CSRF protection
+
+## Payment Gateway Flow (13 Steps)
+
+1. Customer selects products, initiates payment
+2. Merchant creates order record
+3. Generate checkout form with HMAC-SHA256 signature
+4. Send request to `/v1/checkout/init`
+5. SePay validates signature
+6. Redirect customer to SePay gateway
+7. Customer selects payment method
+8. SePay communicates with banks/card networks
+9. Financial institution returns result
+10. Callback notification sent to merchant
+11. IPN (Instant Payment Notification) transmitted
+12. Customer redirected to merchant result page
+13. Final outcome displayed
+
+## Environments
+
+**Sandbox:**
+- Dashboard: https://my.sepay.vn (free tier)
+- Endpoint: https://sandbox.pay.sepay.vn/v1/init
+- Credentials: `SP-TEST-XXXXXXX`, `spsk_test_xxxxxxxxxxxxx`
+
+**Production:**
+- Endpoint: https://pay.sepay.vn/v1/init
+- Requirements: Personal/business bank account, completed testing
+- Approval: 3-7 days for NAPAS QR/cards (requires documentation)
+
+## Rate Limits
+
+**Limit:** 2 calls/second
+**Response:** HTTP 429 with `x-sepay-userapi-retry-after` header (seconds to wait)
+
+**Handling:**
+```javascript
+if (response.status === 429) {
+  const retryAfter = response.headers.get('x-sepay-userapi-retry-after');
+  await sleep(retryAfter * 1000);
+  return retry();
+}
+```
+
+## Support
+
+- Email: info@sepay.vn
+- Hotline: 02873059589 (24/7)
+- Docs: https://developer.sepay.vn/en
+- GitHub: https://github.com/sepayvn
+
+## Next Steps
+
+- **For API integration:** Load `api.md`
+- **For SDK integration:** Load `sdk.md`
+- **For webhook setup:** Load `webhooks.md`
+- **For QR generation:** Load `qr-codes.md`

package/.opencode/skills/payment-integration/references/sepay/qr-codes.md

@@ -0,0 +1,228 @@
+# SePay VietQR Generation
+
+Dynamic QR code generation service compatible with VietQR standard (NAPAS).
+
+## API Endpoint
+
+```
+https://qr.sepay.vn/img?acc={ACCOUNT}&bank={BANK}&amount={AMOUNT}&des={DESCRIPTION}
+```
+
+## Parameters
+
+**Required:**
+- `acc` - Bank account number
+- `bank` - Bank code or short name
+
+**Optional:**
+- `amount` - Transfer amount (omit for flexible amount)
+- `des` - Transfer description/content (URL encoded)
+- `template` - QR image template (empty/compact/qronly)
+- `download` - Set to "true" to download image
+
+## Examples
+
+### Complete QR (Fixed Amount)
+```
+https://qr.sepay.vn/img?
+  acc=0010000000355&
+  bank=Vietcombank&
+  amount=100000&
+  des=ung%20ho%20quy%20bao%20tro%20tre%20em
+```
+
+### Flexible QR (Customer Enters Amount)
+```
+https://qr.sepay.vn/img?acc=0010000000355&bank=Vietcombank
+```
+
+### QR Only Template
+```
+https://qr.sepay.vn/img?
+  acc=0010000000355&
+  bank=Vietcombank&
+  amount=100000&
+  template=qronly
+```
+
+## Integration
+
+### HTML
+```html
+<img src="https://qr.sepay.vn/img?acc=0010000000355&bank=Vietcombank&amount=100000"
+     alt="Payment QR Code" />
+```
+
+### JavaScript (Dynamic)
+```javascript
+function generatePaymentQR(account, bank, amount, description) {
+  const params = new URLSearchParams({
+    acc: account,
+    bank: bank,
+    amount: amount,
+    des: description
+  });
+  return `https://qr.sepay.vn/img?${params}`;
+}
+
+// Usage
+const qrUrl = generatePaymentQR(
+  '0010000000355',
+  'Vietcombank',
+  100000,
+  'Order #12345'
+);
+
+document.getElementById('qr-code').src = qrUrl;
+```
+
+### PHP (Dynamic)
+```php
+<?php
+function generatePaymentQR($account, $bank, $amount, $description) {
+    return 'https://qr.sepay.vn/img?' . http_build_query([
+        'acc' => $account,
+        'bank' => $bank,
+        'amount' => $amount,
+        'des' => $description
+    ]);
+}
+
+// Usage
+$qrUrl = generatePaymentQR(
+    '0010000000355',
+    'Vietcombank',
+    100000,
+    'Order #' . $orderId
+);
+
+echo "<img src='{$qrUrl}' alt='Payment QR' />";
+?>
+```
+
+### Node.js (Express)
+```javascript
+app.get('/payment/:orderId/qr', async (req, res) => {
+  const order = await Order.findById(req.params.orderId);
+
+  const qrUrl = new URL('https://qr.sepay.vn/img');
+  qrUrl.searchParams.set('acc', process.env.SEPAY_ACCOUNT);
+  qrUrl.searchParams.set('bank', process.env.SEPAY_BANK);
+  qrUrl.searchParams.set('amount', order.total);
+  qrUrl.searchParams.set('des', `Order ${order.id}`);
+
+  res.render('payment', { qrUrl: qrUrl.toString() });
+});
+```
+
+### React Component
+```jsx
+function PaymentQR({ account, bank, amount, description }) {
+  const qrUrl = useMemo(() => {
+    const params = new URLSearchParams({
+      acc: account,
+      bank: bank,
+      amount: amount,
+      des: description
+    });
+    return `https://qr.sepay.vn/img?${params}`;
+  }, [account, bank, amount, description]);
+
+  return (
+    <div className="payment-qr">
+      <img src={qrUrl} alt="Payment QR Code" />
+      <p>Scan to pay {amount.toLocaleString('vi-VN')} VND</p>
+    </div>
+  );
+}
+```
+
+## Templates
+
+**Default:**
+- Full QR with bank logo
+- Account information displayed
+- Branded with bank colors
+
+**Compact:**
+- Smaller version
+- Minimal branding
+- More space-efficient
+
+**QR Only:**
+- Pure QR code
+- No decorations
+- For custom layouts
+
+## Bank Codes
+
+**Get Bank List:**
+```
+GET https://qr.sepay.vn/banks.json
+```
+
+**Common Banks:**
+- Vietcombank (VCB)
+- VPBank
+- BIDV
+- Techcombank (TCB)
+- ACB
+- MB Bank
+- Sacombank
+- VietinBank
+- And 40+ others
+
+**Cache Bank List:**
+```javascript
+// Fetch once and cache
+const banks = await fetch('https://qr.sepay.vn/banks.json')
+  .then(res => res.json());
+
+// Store in memory or Redis
+cache.set('sepay_banks', banks, 86400); // 24 hours
+```
+
+## Best Practices
+
+1. **Cache Bank List:** Avoid repeated API calls
+2. **URL Encode Descriptions:** Use `encodeURIComponent()` or `http_build_query()`
+3. **Error Handling:** Provide fallback for QR generation failures
+4. **Amount Validation:** Ensure amount is positive integer
+5. **Flexible vs Fixed:** Use flexible QR for varying amounts
+6. **Template Selection:** Choose based on UI design
+7. **Responsive Design:** Scale QR code for mobile devices
+8. **Alt Text:** Always provide descriptive alt text
+9. **Loading State:** Show placeholder while QR loads
+10. **Print Support:** Ensure QR codes are print-friendly
+
+## Integration Patterns
+
+### Checkout Page
+```html
+<div class="payment-methods">
+  <h3>Pay via Bank Transfer</h3>
+  <img src="[QR_URL]" alt="Payment QR Code" class="qr-code" />
+  <p>Scan this QR code with your banking app</p>
+  <div class="payment-details">
+    <p><strong>Account:</strong> 0010000000355</p>
+    <p><strong>Bank:</strong> Vietcombank</p>
+    <p><strong>Amount:</strong> 100,000 VND</p>
+    <p><strong>Content:</strong> Order #12345</p>
+  </div>
+</div>
+```
+
+### Email Receipt
+```html
+<table>
+  <tr>
+    <td align="center">
+      <img src="[QR_URL]" alt="Payment QR Code" width="200" />
+      <p>Scan to pay for your order</p>
+    </td>
+  </tr>
+</table>
+```
+
+### PDF Invoice
+Use QR URL in PDF generation libraries (wkhtmltopdf, Puppeteer, etc.)

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

@@ -0,0 +1,213 @@
+# SePay SDK Integration
+
+Official SDKs for Node.js, PHP, and Laravel.
+
+## Node.js SDK (sepay-pg-node)
+
+**Installation:**
+```bash
+npm install github:sepay/sepay-pg-node
+```
+
+**Requirements:** Node.js 16+
+
+**Configuration:**
+```javascript
+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:**
+```javascript
+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:**
+```jsx
+<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:**
+```javascript
+// 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:**
+```bash
+composer require sepay/sepay-pg
+```
+
+**Requirements:** PHP 7.4+, ext-json, ext-curl, Guzzle
+
+**Quick Start:**
+```php
+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:**
+```php
+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:**
+```php
+$sepay->setConfig([
+    'timeout' => 30,
+    'retry_attempts' => 3,
+    'retry_delay' => 1000,
+    'debug' => true,
+    'user_agent' => 'MyApp/1.0',
+    'logger' => $psrLogger
+]);
+```
+
+## Laravel Package (laravel-sepay)
+
+**Installation:**
+```bash
+composer require sepayvn/laravel-sepay
+
+# For Laravel 7-8 with PHP 7.4+
+composer require "sepayvn/laravel-sepay:dev-lite"
+```
+
+**Setup:**
+```bash
+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:**
+```bash
+php artisan make:listener SePayWebhookListener
+```
+
+**Listener Implementation:**
+```php
+<?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:**
+```php
+// 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