init

2026-04-12 01:06:31 +07:00
commit 10d660cbcb
1066 changed files with 228596 additions and 0 deletions
--- a/.opencode/skills/payment-integration/references/sepay/api.md
+++ b/.opencode/skills/payment-integration/references/sepay/api.md
@@ -0,0 +1,140 @@
+# SePay API Reference
+
+Base URL: `https://my.sepay.vn/userapi/`
+Rate Limit: 2 calls/second
+
+## Transaction API
+
+### List Transactions
+```
+GET /userapi/transactions/list
+```
+
+**Parameters:**
+- `account_number` (string) - Bank account ID
+- `transaction_date_min/max` (yyyy-mm-dd) - Date range
+- `since_id` (integer) - Start from ID
+- `limit` (integer) - Max 5000 per request
+- `reference_number` (string) - Transaction reference
+- `amount_in` (number) - Incoming amount
+- `amount_out` (number) - Outgoing amount
+
+**Response:**
+```json
+{
+  "status": 200,
+  "transactions": [{
+    "id": 92704,
+    "gateway": "Vietcombank",
+    "transaction_date": "2023-03-25 14:02:37",
+    "account_number": "0123499999",
+    "content": "payment content",
+    "transfer_type": "in",
+    "transfer_amount": 2277000,
+    "accumulated": 19077000,
+    "reference_number": "MBVCB.3278907687",
+    "bank_account_id": 123
+  }]
+}
+```
+
+### Transaction Details
+```
+GET /userapi/transactions/details/{transaction_id}
+```
+
+### Count Transactions
+```
+GET /userapi/transactions/count
+```
+
+## Bank Account API
+
+### List Bank Accounts
+```
+GET /userapi/bankaccounts/list
+```
+
+**Parameters:**
+- `short_name` - Bank identifier
+- `last_transaction_date_min/max` - Date range
+- `since_id` - Starting account ID
+- `limit` - Results per page (default 100)
+- `accumulated_min/max` - Balance range
+
+**Response:**
+```json
+{
+  "id": 123,
+  "account_holder_name": "NGUYEN VAN A",
+  "account_number": "0123456789",
+  "accumulated": 50000000,
+  "last_transaction": "2025-01-13 10:30:00",
+  "bank_short_name": "VCB",
+  "active": 1
+}
+```
+
+### Account Details
+```
+GET /userapi/bankaccounts/details/{bank_account_id}
+```
+
+### Count Accounts
+```
+GET /userapi/bankaccounts/count
+```
+
+## Order-Based Virtual Account API
+
+**Concept:** Each order gets unique VA with exact amount matching for automated confirmation.
+
+**Flow:**
+1. Create order → API generates unique VA
+2. Display VA + QR to customer
+3. Customer transfers to VA
+4. Bank notifies SePay on success
+5. SePay triggers webhook
+6. Update order status
+
+**Advantages:**
+- Precision: VA accepts only exact amounts
+- Independence: Each order has own VA (no content parsing)
+- Security: VAs auto-cancel after success/expiration
+- Integration: RESTful API
+
+**Supported Banks:** BIDV and others (check docs for full list)
+
+## Error Handling
+
+**HTTP Status Codes:**
+- 200 OK - Successful
+- 201 Created - Resource created
+- 400 Bad Request - Invalid parameters
+- 401 Unauthorized - Invalid/missing auth
+- 403 Forbidden - Insufficient permissions
+- 404 Not Found - Resource not found
+- 429 Too Many Requests - Rate limit exceeded
+- 500 Internal Server Error - Server error
+- 503 Service Unavailable - Temporarily unavailable
+
+**Rate Limit Response:**
+```json
+{
+  "status": 429,
+  "error": "rate_limit_exceeded",
+  "message": "Too many requests"
+}
+```
+
+Check `x-sepay-userapi-retry-after` header for retry timing.
+
+## Best Practices
+
+1. **Pagination:** Use `limit` and `since_id` for large datasets
+2. **Date Ranges:** Query specific periods to reduce response size
+3. **Rate Limiting:** Implement exponential backoff
+4. **Error Handling:** Log all errors with context
+5. **Caching:** Cache bank account lists
+6. **Monitoring:** Track API response times and error rates
+7. **Reconciliation:** Regular transaction matching