SePay API v2 quick start

Get started with SePay API v2 in 5 minutes. Query transactions and bank accounts using the standardized REST API with unified JSON envelope responses.

||

Integration Overview

The diagram below illustrates the SePay API v2 integration flow, from creating an API token to querying bank accounts and transactions.

SePay API v2 Integration Flow
Rendering diagram...

Key features

  • Bank Accounts: List and get details of all linked bank accounts
  • Transactions: Query transaction history with filters, sorting, and cursor-based polling
  • Order VAs (BIDV, Sacombank, Vietcombank): Create and manage order-based Virtual Accounts for BIDV enterprise, Sacombank personal/household business, and Vietcombank enterprise/household business accounts
  • Virtual Accounts: List and get details of Virtual Accounts across all banks

Hands-on steps

Step 1: Create API Token

Access API Settings

Log in to my.sepay.vn → go to Company Settings → API Access.

Create a Test mode token

For integration testing without affecting Live data, toggle Test mode in the my.sepay.vn sidebar then open API Access while in Test mode. Tokens created there only authenticate against the userapi-sandbox.sepay.vn endpoint and are fully isolated from Production. Full guide: API Access in Test mode.

Add a New API Key

Click the + Add API button, fill in the required information, then click Add.

Copy Your Token

Copy the generated API token. You will use this token in the Authorization: Bearer YOUR_API_TOKEN header for all API calls.

Keep Your API Token Secure
  • Never commit API tokens to source code. Use environment variables instead
  • Your API Token has full access to all bank account and transaction data
  • Only call the API from server-side code. Never expose your token in frontend JavaScript or mobile apps
  • If you suspect a token has been compromised, delete and create a new one immediately at API Access

Full guide: Create API Token

Step 2: Your First API Call - List Bank Accounts

>
>
>
curl -X GET "https://userapi.sepay.vn/v2/bank-accounts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Sample response:

200 OK
{
  "status": "success",
  "data": [
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "account_holder_name": "NGUYEN VAN A",
      "account_number": "0123456789",
      "accumulated": 15000000,
      "last_transaction": "2025-01-15 09:30:00",
      "label": "Tai khoan chinh",
      "active": 1,
      "bank_short_name": "ACB",
      "bank_full_name": "Ngan hang TMCP A Chau",
      "bank_code": "ACB"
    }
  ],
  "meta": {
    "pagination": {
      "total": 5,
      "per_page": 20,
      "current_page": 1,
      "last_page": 1,
      "has_more": false
    }
  }
}

Step 3: List Transactions

>
>
>
curl -X GET "https://userapi.sepay.vn/v2/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Sample response:

200 OK
{
  "status": "success",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "transaction_date": "2025-02-20 14:15:00",
      "account_number": "0123456789",
      "va": "VA001",
      "transfer_type": "in",
      "amount_in": 500000,
      "amount_out": 0,
      "accumulated": 1500000,
      "transaction_content": "CONG TY CP TECH SOLUTIONS thanh toan",
      "reference_number": "FT25051ABC",
      "code": null,
      "bank_brand_name": "ACB",
      "bank_account_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "va_id": "a2b3c4d5-e6f7-8901-bcde-f12345678901",
      "webhook_success": 1
    }
  ],
  "meta": {
    "pagination": {
      "total": 150,
      "per_page": 20,
      "current_page": 1,
      "last_page": 8,
      "has_more": true
    }
  }
}

Step 4: Get Transaction Details

Retrieve details for a specific transaction using its UUID:

>
>
>
curl -X GET "https://userapi.sepay.vn/v2/transactions/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
200 OK
{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_date": "2025-03-05 16:45:00",
    "account_number": "0123456789",
    "va": "VA001",
    "transfer_type": "in",
    "amount_in": 500000,
    "amount_out": 0,
    "accumulated": 1500000,
    "transaction_content": "CONG TY CP TECH SOLUTIONS thanh toan",
    "reference_number": "FT25064DEF",
    "code": null,
    "bank_brand_name": "ACB",
    "bank_account_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
    "va_id": "a2b3c4d5-e6f7-8901-bcde-f12345678901",
    "webhook_success": 1
  }
}

Useful Filters

Common filters when querying transactions:

Filter by bank and amount:

cURL
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/transactions?bank_brand_name=ACB&amount_in_min=500000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Filter by date range:

cURL
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/transactions?transaction_date_from=2026-03-01&transaction_date_to=2026-03-31" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Search by transaction content:

cURL
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/transactions?q=order+123" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Poll for new transactions with since_id:

cURL
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/transactions?since_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

API Rate Limits

Rate Limiting
  • Maximum 3 requests per second per IP address
  • When the limit is exceeded, the API returns HTTP 429 Too Many Requests
  • The Retry-After header indicates the number of seconds to wait before retrying
  • Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset are included in every response

Next Steps

  1. Authentication & Rate Limiting: Bearer token authentication and rate limit handling
  2. Transactions API: Query and filter transactions with advanced parameters
  3. Bank Accounts API: Query bank account information
  4. Virtual Accounts API: Query Virtual Accounts across all banks
  5. Order VAs API (BIDV, Sacombank, Vietcombank): Create and manage order VAs for BIDV enterprise, Sacombank personal/household business, and Vietcombank enterprise/household business accounts
  6. SePay Webhooks: Receive real-time transaction notifications via webhooks
Previous page
—
Next page
—