Access Token

Giới thiệu về Access Token

Access Token là chuỗi ký tự được SePay cấp cho ứng dụng của bạn sau khi quá trình xác thực OAuth2 thành công. Token này đóng vai trò như một "chìa khóa" tạm thời để truy cập vào các API của SePay thay mặt cho người dùng.

Cấu trúc của Access Token

Access Token của SePay tuân theo chuẩn JWT (JSON Web Token) và bao gồm 3 phần, phân tách bởi dấu chấm (.):

header.payload.signature

• Header: Chứa thông tin về loại token và thuật toán mã hóa
• Payload: Chứa các claims (thông tin) như ID người dùng, phạm vi quyền, thời gian hết hạn
• Signature: Chữ ký để xác minh token không bị sửa đổi

Ví dụ về nội dung giải mã của một JWT Access Token:

{
    "iss": "https://my.sepay.vn",
    "sub": "12345",
    "aud": "client_67890",
    "exp": 1740541044,
    "iat": 1740537444,
    "scope": "profile bank-account:read transaction:read"
}

Trong đó:

• iss (issuer): SePay - đơn vị cấp token
• sub (subject): ID của người dùng đã cấp quyền
• aud (audience): Client ID của ứng dụng
• exp (expiration time): Thời gian hết hạn của token
• iat (issued at): Thời gian token được cấp
• scope: Phạm vi quyền được cấp

Sử dụng Access Token

Để sử dụng Access Token, bạn cần thêm nó vào header Authorization trong mỗi yêu cầu API với prefix "Bearer":

GET https://my.sepay.vn/api/v1/bank-accounts
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL215LnNlcGF5LnZuIiwic3ViIjoidXNlcl8xMjM0NSIsImF1ZCI6ImNsaWVudF82Nzg5MCIsImV4cCI6MTY3OTUzMTQwMiwiaWF0IjoxNjc5NTI3ODAyLCJzY29wZSI6ImJhbmtfYWNjb3VudDpyZWFkIHRyYW5zYWN0aW9uOnJlYWQifQ.signature

Dưới đây là ví dụ sử dụng Access Token với một số ngôn ngữ lập trình phổ biến:

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

<?php

$accessToken = 'YOUR_ACCESS_TOKEN';
$url = 'https://my.sepay.vn/api/v1/bank-accounts';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Error: " . $httpCode . " - " . $response;
}

use Illuminate\Support\Facades\Http;

$response = Http::withToken('ACCESS_TOKEN')->get('https://my.sepay.vn/api/v1/bank-accounts');

if ($response->ok()) {
    $data = $response->json();
    dd($data);
} else {
    dd($response->status(), $response->body());
}

async function getBankAccounts() {
    try {
        const response = await fetch('https://my.sepay.vn/api/v1/bank-accounts', {
            method: 'GET',
            headers: {
                'Authorization': `Bearer ${accessToken}`
            }
        });

        if (!response.ok) {
            throw new Error(`HTTP error! Status: ${response.status}`);
        }

        const data = await response.json();
        console.log(data);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

getBankAccounts();

Lưu trữ Access Token an toàn

Việc lưu trữ an toàn Access Token và Refresh Token là rất quan trọng để bảo vệ dữ liệu người dùng. Dưới đây là các thực hành tốt nhất:

Quản lý Token hết hạn

Access Token có thời hạn giới hạn (mặc định là 1 giờ). Khi token hết hạn, ứng dụng của bạn cần xử lý tình huống này để duy trì trải nghiệm người dùng liên tục.

Chiến lược xử lý token hết hạn:

1. Làm mới trước khi hết hạn: Theo dõi thời gian sắp hết hạn và chủ động làm mới token trước khi API trả về lỗi. Bạn có thể tính toán thời điểm làm mới dựa trên trường expires_in trong phản hồi token.
2. Xử lý lỗi 401: Khi API trả về mã lỗi 401 Unauthorized, thực hiện việc làm mới token và thử lại yêu cầu.

Dưới đây là mẫu code xử lý token hết hạn và tự động làm mới token:

function makeApiRequest($url, $accessToken) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $accessToken
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 401) {
        // Token hết hạn, làm mới token
        $newTokens = refreshAccessToken();
        $accessToken = $newTokens['access_token'];

        // Thử lại yêu cầu với token mới
        return makeApiRequest($url, $accessToken);
    }

    return json_decode($response, true);
}

function refreshAccessToken() {
    $url = 'https://my.sepay.vn/oauth/token';
    $data = [
        'grant_type' => 'refresh_token',
        'refresh_token' => 'YOUR_REFRESH_TOKEN',
        'client_id' => 'YOUR_CLIENT_ID',
        'client_secret' => 'YOUR_CLIENT_SECRET',
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

$bankAccounts = makeApiRequest('https://my.sepay.vn/api/v1/bank-accounts', 'YOUR_ACCESS_TOKEN');
print_r($bankAccounts);

Xử lý lỗi liên quan đến Token

Khi làm việc với Access Token, bạn có thể gặp phải các lỗi sau:

Bước tiếp theo

Sau khi hiểu rõ về cách sử dụng và quản lý Access Token, bạn đã sẵn sàng để tìm hiểu về các API resources của SePay.