SePay OAuth2 Overview

Learn about OAuth2 authentication mechanism for integrating with SePay API.

Introduction

SePay has implemented OAuth2 authentication mechanism, enabling partners to integrate easily and securely with our system. This documentation provides detailed guidance on using OAuth2 to connect with SePay API endpoints.

What is OAuth2?

OAuth2 is a standard authorization protocol that allows third-party applications to access user resources without needing to know their login credentials.

OAuth2 provides the following benefits:

Secure: No need to share login credentials with third-party applications
Controlled: Users can limit the scope of access for applications
Flexible: Easy to revoke access without changing passwords
Standardized: Widely supported and adopted by many online services

Benefits of Using OAuth2 with SePay

Implementing OAuth2 provides significant benefits when integrating with SePay:

High Security

Secure authentication without sharing login credentials, minimizing security risks.

Granular Permissions

Detailed access control for each endpoint, helping you manage data and features being accessed.

Limited Access Scope

Restrict access scope for third-party applications, ensuring only necessary permissions are granted.

Refresh Token

Token refresh mechanism to maintain secure connections without re-authentication.

Scopes

SePay defines scopes to control access to each API:

Scope	Description
`bank-account:read`	Permission to read bank account information
`transaction:read`	Permission to read transaction information
`webhook:read`	Permission to read webhook information
`webhook:write`	Permission to write webhook information
`webhook:delete`	Permission to delete webhook information
`profile`	Permission to read user information
`company`	Permission to read company information

When registering an application, you can request one or more scopes. Users will be prompted to authorize when authenticating.

OAuth2 Flow Overview

The OAuth2 flow in SePay follows the standard authentication process with the following steps:

Obtain `client_id` and `client_secret` from SePay through the Developer Portal.

Request Authorization

Redirect users to SePay authentication screen to grant permissions.

Receive Authorization Code

SePay redirects users back to your application with an authorization code.

Exchange Code for Token

Send API request to SePay to exchange authorization code for access token.

Use Token

Include access token in API request headers for authentication.

Refresh Token

Use refresh token to obtain new access token when expired.

Details about each step in the OAuth2 flow are fully documented in the Authentication Flow section

API Base URL

All SePay OAuth2 APIs use a common base URL: https://my.sepay.vn/api/v1

When making API requests, you need to append the specific endpoint path after the base URL. For example:

Endpoint	Full URL	Description
`/bank-accounts`	https://my.sepay.vn/api/v1/bank-accounts	API to get list of bank accounts
`/transactions`	https://my.sepay.vn/api/v1/transactions	API to get list of transactions
`/webhooks`	https://my.sepay.vn/api/v1/webhooks	API to manage webhooks
`/me`	https://my.sepay.vn/api/v1/me	API to get current user information
`/companies`	https://my.sepay.vn/api/v1/companies	API to get company information

API Versioning

The "v1" part in the base URL represents the API version. SePay uses this versioning system to ensure compatibility when changes are made in the future.

Current version: v1 (https://my.sepay.vn/api/v1)

When a new API version is released, SePay will announce and update the documentation. We always ensure the old API version is maintained for a reasonable period to allow applications time to update.

Note

All API requests must include an Access Token in the Authorization header as described in the Access Token section.