Quick Start

Get started with SePay API v2 - query transactions and bank accounts in just 5 minutes with standardized responses, UUID identifiers, and pagination.

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...

What can you do with SePay API v2?

  • Bank Accounts: List and get details of all linked bank accounts
  • Transactions: Query transaction history with filters, sorting, and cursor-based polling
  • VA Orders (BIDV): Create and manage Virtual Account orders for BIDV enterprise accounts
  • Virtual Accounts: List and get details of Virtual Accounts across all banks

Quick Start

Step 1: Create API Token

Access API Settings

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

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:

Bash
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/bank-accounts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
$apiToken = getenv('SEPAY_API_TOKEN');
 
$opts = [
    'http' => [
        'method' => 'GET',
        'header' => "Content-Type: application/json\r\nAuthorization: Bearer $apiToken"
    ]
];
$context = stream_context_create($opts);
$response = file_get_contents('https://userapi.sepay.vn/v2/bank-accounts', false, $context);
$data = json_decode($response, true);
 
print_r($data);
 

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:

Bash
1
2
3
curl -X GET "https://userapi.sepay.vn/v2/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
$apiToken = getenv('SEPAY_API_TOKEN');
 
$opts = [
    'http' => [
        'method' => 'GET',
        'header' => "Content-Type: application/json\r\nAuthorization: Bearer $apiToken"
    ]
];
$context = stream_context_create($opts);
$response = file_get_contents('https://userapi.sepay.vn/v2/transactions', false, $context);
$data = json_decode($response, true);
 
print_r($data);
 

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:

Bash
1
2
3
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. API v2 Overview: Response format, pagination, and common query parameters
  2. Authentication & Rate Limiting: Bearer token authentication and rate limit handling
  3. Transactions API: Query and filter transactions with advanced parameters
  4. Bank Accounts API: Query bank account information
  5. Virtual Accounts API: Query Virtual Accounts across all banks
  6. VA Orders API (BIDV, Sacombank): Create and manage VA orders for BIDV enterprise and Sacombank accounts
  7. SePay Webhooks: Receive real-time transaction notifications via webhooks
Previous page
—
Next page
—