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

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:

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