Quick Start

Integrate SePay OAuth2 in 10 minutes. From registering your app, authenticating users, to making your first API call.

This guide walks you through integrating SePay OAuth2: from getting client credentials, authenticating users, to making your first API call.

Prerequisites

A SePay account (register at my.sepay.vn)
Obtained client_id and client_secret (contact SePay for approval)
Configured redirect_uri when registering your application
A server-side application (PHP, Python, Node.js, ...)

Important URLs

URL	Purpose
`https://my.sepay.vn/oauth/authorize`	User authorization page
`https://my.sepay.vn/oauth/token`	Get/refresh access token
`https://my.sepay.vn/api/v1`	Base URL for all APIs

Step 1: Redirect User to Authorization Page

Build the authorization URL and redirect the user:

Code

https://my.sepay.vn/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=bank-account:read transaction:read&state=RANDOM_STATE_VALUE

Parameter	Required	Description
`response_type`	Yes	Always `code`
`client_id`	Yes	Your application's Client ID
`redirect_uri`	Yes	Callback URL, must match the registered URL
`scope`	Yes	Access permissions, space-separated
`state`	Yes	Random value for CSRF protection

The user will log in to SePay and approve the permissions. SePay then redirects back to your redirect_uri:

Code

https://your-app.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE

Note

The authorization code is valid for only 5 minutes and can only be used once. Exchange it for an access token immediately.

Step 2: Exchange Authorization Code for Access Token

Bash

curl -X POST "https://my.sepay.vn/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_STRING"
}

Note

Access token is valid for 1 hour (3600 seconds)
Refresh token is valid for 1 month
Store both tokens securely on the server side

Step 3: Call APIs with Access Token

Add the access token to the Authorization header for any API call:

Bash

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://my.sepay.vn/api/v1/bank-accounts

{
  "status": 200,
  "messages": [],
  "bankaccounts": [
    {
      "id": 12345,
      "bank_account_number": "1234567890",
      "bank_short_name": "ACB",
      "bank_full_name": "Asia Commercial Bank",
      "accumulated_balance": 5000000
    }
  ]
}

Step 4: Refresh Token When Expired

When the access token expires (API returns 401), use the refresh token to get a new one:

Bash

curl -X POST "https://my.sepay.vn/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NEW_REFRESH_TOKEN"
}

Note

Each refresh returns new access and refresh tokens. Save both for the next refresh cycle.

Supported Scopes

Scope	Description
`bank-account:read`	Read bank account information
`transaction:read`	Read transaction information
`webhook:read`	Read webhook information
`webhook:write`	Create/update webhooks
`webhook:delete`	Delete webhooks
`profile`	Read user profile
`company`	Read company information

Integration Flow Summary

Step	Action	URL/Endpoint
1	Redirect user for authorization	`GET /oauth/authorize`
2	Exchange authorization code for token	`POST /oauth/token` (grant_type=authorization_code)
3	Call APIs with Bearer token	`GET /api/v1/*`
4	Refresh token when expired	`POST /oauth/token` (grant_type=refresh_token)

Common Error Codes

Error	Meaning	Action
`invalid_client`	Wrong client_id or client_secret	Verify credentials
`invalid_grant`	Authorization code expired or already used	Re-authenticate the user
`invalid_scope`	Invalid scope	Check scope list
`access_denied`	User denied permission	Inform the user
401 Unauthorized	Access token expired or invalid	Refresh token or re-authenticate

Next Steps

See detailed documentation for each section with full parameters, error codes, and code samples:

Register Application - Get client_id and client_secret
Authentication Flow - Detailed OAuth2 steps
Access Token - Token management and storage
Bank Account API - View accounts, balances
Transaction API - View transaction history
Webhooks API - Manage webhooks
User API - User profile
Company API - Company information