# API Overview

- Anchor: `bankhub-en-api-tong-quan-api`
- URL: https://developer.sepay.vn/en/bankhub/api/tong-quan-api.md
- Description: An overview of SePay Bank Hub APIs, including environments, authentication, HTTP status codes, error formats, and the list of endpoints.

### Introduction

In addition to Hosted Link, Bank Hub provides a **full set of RESTful APIs** to:

- Create and manage link tokens
- Create and manage companies
- Manage linked bank accounts
- Query transaction history
- Configure merchant settings
- Configure webhooks for event notifications

---

### API Environments & Versioning

Bank Hub supports two environments:

#### Production
- Base URL: `https://bankhub-api.sepay.vn`
- API Version: `/v1`
- Used for production (real environment)

#### Sandbox
- Base URL: `https://bankhub-api-sandbox.sepay.vn`
- API Version: `/v1`
- Used for development and testing

> **Note** (warning)
>
> All endpoints are prefixed with `/v1/` and are routed based on the hostname.
>

---

### API Authentication

#### Create Access Token

The token endpoint uses **Basic Authentication** with `client_id` and `client_secret` provided by SePay.

**POST** `/v1/token`
```http
Authorization: Basic {base64(client_id:client_secret)}
```



> **Security** (warning)
>
> **DO NOT** use this API from the client side (browser, mobile app).
> The token API requires `client_secret`, which must be strictly protected on the server.
> Only call this API from your backend server.
>

See details here: **[Create Token API](/bankhub/api/tao-token)**

### Calling Business APIs

All other business APIs require authentication using a **Bearer Token**:



> **Token Management** (info)
>
>
> * Tokens have a limited lifetime (TTL)
> * When a token expires, the API returns `401 Unauthorized`
> * Call `/v1/token` again to obtain a new token
> * Recommendation: Implement an automatic token refresh mechanism before expiration
>

---

### HTTP Status Codes

Bank Hub uses standard HTTP status codes:

* `200 OK` – Request succeeded
* `201 Created` – Resource created successfully
* `400 Bad Request` – Validation error or invalid request
* `401 Unauthorized` – Missing or invalid authentication
* `404 Not Found` – Resource not found
* `405 Method Not Allowed` – Incorrect HTTP method
* `500 Internal Server Error` – Server-side error
* `503 Service Unavailable` – Service temporarily unavailable

---

### Error Response Format

All API errors follow a consistent structure:

**RESPONSE 400 - Validation Error**


```json
{
  "code": 400,
  "message": "Bad request",
  "errors": {
    "field_name": "Detailed error message"
  }
}
```



**RESPONSE 401 - Authentication Error**


```json
{
  "code": 401,
  "message": "Unauthenticated"
}
```



**RESPONSE 404 - Not Found**


```json
{
  "code": 404,
  "message": "Resource not found"
}
```



---

### API Endpoints List

* **Link Token APIs:**

**POST** `/v1/link-token/create`
Create a link token for linking or unlinking a bank account (can be embedded in an iframe or used with the SDK). **[API details →](/bankhub/api/link-token/tao-link-token)**

**POST** `/v1/link-token/get`
Retrieve detailed information about a created link token. **[API details →](/bankhub/api/link-token/thong-tin-link-token)**

**POST** `/v1/link-token/revoke`
Revoke a created link token and deactivate the link. **[API details →](/bankhub/api/link-token/thu-hoi-link-token)**


* **Company APIs:**

**GET** `/v1/company`
Get the list of companies belonging to the merchant. **[API details →](/bankhub/api/cong-ty/danh-sach-cong-ty)**

**GET** `/v1/company/{xid}`
Get details of a company by xid. **[API details →](/bankhub/api/cong-ty/chi-tiet-cong-ty)**

**POST** `/v1/company/create`
Create a new company for the merchant. **[API details →](/bankhub/api/cong-ty/tao-cong-ty)**

**POST** `/v1/company/edit/{xid}`
Update a company’s information by xid. **[API details →](/bankhub/api/cong-ty/chinh-sua-cong-ty)**

**GET** `/v1/company/counter/{xid}`
Count transactions for a company. **[API details →](/bankhub/api/cong-ty/bo-dem-cong-ty)**


* **Bank Account APIs:**

**GET** `/v1/bank-account`
Get the list of linked bank accounts. **[API details →](/bankhub/api/tai-khoan-ngan-hang/danh-sach-tai-khoan)**

**GET** `/v1/bank-account/{xid}`
Get details of a bank account by xid. **[API details →](/bankhub/api/tai-khoan-ngan-hang/chi-tiet-tai-khoan)**


* **Transaction APIs:**

**GET** `/v1/transaction`
Query transaction history with flexible filters. **[API details →](/bankhub/api/api-giao-dich/danh-sach-giao-dich)**

**GET** `/v1/transaction/{transaction_id}`
Get details of a transaction by transaction_id. **[API details →](/bankhub/api/api-giao-dich/chi-tiet-giao-dich)**


* **Merchant Config APIs:**

**GET** `/v1/merchant-config`
Get merchant display configuration (logo, name, colors). **[API details →](/bankhub/api/api-merchant/thong-tin-cau-hinh)**

**POST** `/v1/merchant-config`
Update merchant display configuration. **[API details →](/bankhub/api/api-merchant/chinh-sua-thong-tin-cau-hinh)**

**POST** `/v1/merchant-config/logo`
Upload a merchant logo. **[API details →](/bankhub/api/api-merchant/upload-logo-merchant)**


* **Webhook APIs:**

**GET** `/v1/webhook`
Get the current webhook configuration. **[API details →](/bankhub/api/api-webhook/thong-tin-webhook)**

**POST** `/v1/webhook`
Configure webhook URL and secret key for receiving events. **[API details →](/bankhub/api/api-webhook/cap-nhat-webhook)**


---

### Best Practices

#### 1. Token Management

* Store tokens securely and never expose them on the client side
* Implement automatic token refresh before expiration
* Handle 401 errors by fetching a new token automatically and retrying the request

#### 2. Error Handling

* Always check HTTP status codes
* Parse and display error messages from the response
* Implement retry logic for temporary (5xx) errors

#### 3. Rate Limiting

* Follow the API rate limits
* Implement exponential backoff when encountering 429 errors
* Cache data when possible to reduce the number of API calls

#### 4. Idempotency

* Use an idempotency key for important requests
* Store and validate responses based on the idempotency key
* Safely handle duplicate requests

---