Bank Hub API overview & auth

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

API Authentication

Create Access Token

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

Authorization: Basic {base64(client_id:client_secret)}

See details here: Create Token API

Calling Business APIs

All other business APIs require authentication using a Bearer Token:

Authorization: Bearer YOUR_ACCESS_TOKEN

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:

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

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

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

API Endpoints List

• Link Token APIs:

• Company APIs:

• Bank Account APIs:

• Transaction APIs:

• Merchant Config APIs:

• Webhook APIs:

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

Next Steps

To get started with Bank Hub API, follow these steps:

1. Create Access Token - Get a Bearer token to authenticate subsequent APIs
2. Create Company - Create a company to manage bank accounts
3. Create Link Token - Create a link for users to connect their bank