045 API C894057d

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:

{
  "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:

{
  "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:

{
  "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