Tích hợp xác nhận thanh toán
Thực hành lập trình xử lý sự kiện webhook để xác nhận thanh toán

Giới thiệu

Hiện tại Casso đã hỗ trợ nhiều hình thức tích hợp xác nhận thanh toán thông qua các API Casso đã public. Để phần tích hợp thanh toán của bạn xịn hơn thì có thể dùng VietQR để tạo QR-Code cho phần thanh toán. VietQR là tiêu chuẩn quốc gia về mã QR ngân hàng. Mã này được chấp nhận bởi 50 ngân hàng Việt Nam. Có thể xem chi tiết tại đây

Trước khi bắt đầu

Hướng dẫn tích hợp

Để có thể sử dụng và hiểu được các API này thì dưới đây Casso demo một server basic được viết bằng NodeJS + Express basic về tích hợp thanh toán. Chi tiết source tại Github.
Dưới đây là demo các bước về việc tạo webhook để lắng nghe có các giao dịch mới của Casso gửi qua và yêu cầu đồng bộ giao dịch tức thì từ phía app. Quá trình code có thể chỉ mất vài giờ nếu bạn đã quen với việc viết API. Bạn có thể làm theo kịch bản sau:

Cấu trúc file sever

Bước 1: Tạo file index.js

Đầu tiên chúng ta sẽ tạo file index.js để xây dựng server lắng nghe các request. Server mình sẽ thiết lập với cổng 4300
1
require('dotenv').config({ path: '.env' });
2
let app = require('./app');
3
async function main() {
4
app
5
console.log(`Server on port ${process.env.PORT || 4300}`);
6
};
7
main();
Copied!

Bước 2: Tạo file app.js, config và xử lý lỗi

Các thứ cần thiết cho server như: cors, json, urlencodedExpress error handling
1
let express = require("express");
2
var cors = require('cors');
3
let app = express();
4
// Tạo cors
5
var corsOption = {
6
origin: true,
7
methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
8
credentials: true,
9
exposedHeaders: ['x-auth-token']
10
};
11
app.use(cors(corsOption));
12
app.use(express.json());
13
app.use(express.urlencoded({ extended: true }));
14
app.use('/', require('./routes'));
15
// Endpoint not found
16
app.use(function (req, res, next) {
17
res.status(404).json({
18
code: 404,
19
message: 'Endpoint not found'
20
});
21
})
22
// Xử lí khi lỗi ở phía server
23
app.use(function (err, req, res, next) {
24
res.status(500).json({
25
code: 500, error: 'Something went wrong, please try again!'
26
})
27
})
28
app.listen(process.env.PORT || 4300);
29
module.exports = app;
Copied!

Bước 3: Tạo các routes và test hello world

Ở đây mình sẽ tạo 3 route chính:
  • /webhook/handler-bank-transfer Webhook để nhận thông tin giao dịch từ Casso
  • /register-webhook Thực hiện đăng kí webhook và lấy token từ Casso
  • /users-paid Thực hiện tính năng đồng bộ giao dịch tức thì qua Casso
1
var express = require('express');
2
var router = express.Router();
3
//Router này sẽ là webhook nhận thông tin giao dịch từ casso gọi qua được bảo mật bằng secure_token trong header
4
router.route('/webhook/handler-bank-transfer')
5
.post(async (req, res, next) => {
6
res.status(200).json({message: "Hello world"})
7
})
8
// Router này sẽ thực hiện tính năng đồng bộ giao dịch tức thì.
9
// Ví dụ: Khi người dùng chuyển khoản cho bạn và họ ấn nút tôi đã thanh toán thì nên xử lí gọi qua casso đề đồng bộ giao dịch vừa chuyển khoản
10
router.route('/users-paid')
11
.post(async (req, res, next) => {
12
res.status(200).json({message: "Hello world"})
13
})
14
// Route này sẽ thực hiện đăng kí webhook dựa vào API KEY và lấy thông tin về business và banks
15
router.route('/register-webhook')
16
.post(async (req, res, next) => {
17
res.status(200).json({message: "Hello world"})
18
})
19
20
module.exports = router;
Copied!
Kiểm tra với postman

Bước 4: Xây dựng các hàm hỗ trợ

Để có thể giao tiếp với server Casso sẽ dùng 1 HTTP Client để gọi qua. Ở Demo này sẽ sử dụng AxiosQuery-string.
1
//utils/api.js
2
const axios = require("axios");
3
const queryString = require("query-string");
4
5
const axiosClient = axios.create({
6
baseURL: 'https://oauth.casso.vn/v2',
7
headers: {
8
"content-type": "application/json",
9
"Authorization": `Apikey ${api_key}`,
10
},
11
paramsSerializer: (params) => queryString.stringify(params),
12
});
13
axiosClient.interceptors.request.use(async (config) => {
14
return config;
15
});
16
axiosClient.interceptors.response.use(
17
(response) => {
18
if (response && response.data) return response.data;
19
return response;
20
},
21
(error) => {
22
throw error;
23
}
24
);
25
module.exports = axiosClient;
Copied!
Mẹo: Bạn có thể thay thế giá trị của Authorization với Bearer + access token nhận được từ xác thực Oauth 2.0 của Casso.
Bạn thể tham khảo tài liệu này, để lấy API Key của bạn trên Casso.
Sau khi code HTTP Client thì tiến hành dựng từng hàm tương ứng với từng API.
  • Get userInfo bao gồm thông tin về business và banks. Mô tả cụ thể về API tại đây
1
/*utils/get_user_info.util.js*/
2
getDetailUser: async () => {
3
let res = await api.get(`/userInfo`);
4
return res;
5
},
Copied!
  • Đồng bộ dữ liệu mới nhất. Mô tả cụ thể về API tại đây
1
/*utils/sync.util.js*/
2
syncTransaction: async (bankNumber, apiKey) => {
3
let res = await api.post('/sync', { bank_acc_id: bankNumber });
4
return res;
5
}
Copied!
  • Các hàm thêm, xóa, sửa và xóa webhook Mô tả chi tiết tại đây
1
/*webhook.util.js*/
2
create: async (data) => {
3
let res = await api.post('/webhooks', data);
4
return res;
5
},
6
getDetailWebhookById: async (webhookId) => {
7
let res = await api.get(`/webhooks/${webhookId}`);
8
return res;
9
},
10
updateWebhookById: async (webhookId, data) => {
11
let res = await api.put(`/webhooks/${webhookId}`, data);
12
return res;
13
},
14
deleteWebhookById: async (webhookId) => {
15
let res = await api.delete(`/webhooks/${webhookId}`);
16
return res;
17
},
18
deleteWebhookByUrl: async (urlWebhook) => {
19
// Thêm url vào query để delete https://oauth.casso.vn/v1/webhooks?webhook=https://website-cua-ban.com/api/webhook
20
let query = { params: { webhook: urlWebhook } };
21
let res = await api.delete(`/webhooks`, query);
22
return res;
23
},
Copied!
  • Parser orderId từ nội dung giao dịch và tiền tố giao dịch (DH1231=> 1231) và đồng thời cũng kiểm tra có phân biệt chữ hoa với thường trong nội dung giao dịch hay không?
1
/*webhook.util.js*/
2
parseOrderId: (caseInsensitive, transactionPrefix, description) => {
3
// Ở đây mình ở sử dụng regex để parse nội dung chuyển khoản có chứa orderId
4
// CASSO101 => orderId = 101
5
let re = new RegExp(transactionPrefix);
6
if (!caseInsensitive)
7
re = new RegExp(transactionPrefix, 'i');
8
let matchPrefix = description.match(re);
9
// Không tồn tại tiền tố giao dịch
10
if (!matchPrefix) return null;
11
let orderId = parseInt(description.substring(transactionPrefix.length, description.length));
12
return orderId;
13
}
Copied!

Bước 5: Xây dựng các Route

Mình cần định nghĩa một vài biến cần trong quá trình dựng
1
//routes/index.js
2
//Tiền tố giao dịch
3
const transaction_prefix = 'CASSO';
4
// Phân biệt chữ hoa/thường trong tiền tố giao dịch
5
const case_insensitive = false;
6
//Hạn của đơn hàng là 3 ngày. Quá 3 ngày thì không xử lý
7
const expiration_date = 3;
8
// API KEY lấy từ casso
9
const api_key = '45e40320-e0b7-11eb-a12c-35cc867f21a0';
10
// secure_token đăng kí khi tạo webhook
11
const secure_token = 'R5G4cbnN7uSAwfTd'
Copied!
  1. 1.
    Route tạo webhook bằng API_KEY và lấy thông tin user bao gồm Business và banks
1
//routes/index.js
2
router.route('/register-webhook')
3
.post(async (req, res, next) => {
4
try {
5
//Delete Toàn bộ webhook đã đăng kí trước đó với https://ten-mien-cua-ban.com/webhook/handler-bank-transfer
6
await webhookUtil.deleteWebhookByUrl('https://ten-mien-cua-ban.com/webhook/handler-bank-transfer');
7
//Tiến hành tạo webhook
8
let data = {
9
webhook: 'https://ten-mien-cua-ban.com/webhook/handler-bank-transfer',
10
secure_token: secure_token,
11
income_only: true
12
}
13
let newWebhook = await webhookUtil.create(data);
14
// Lấy thông tin về userInfo
15
let userInfo = await userUtil.getDetailUser();
16
return res.status(200).json({
17
code: 200,
18
message: 'success',
19
data: {
20
webhook: newWebhook.data,
21
userInfo: userInfo.data
22
}
23
})
24
} catch (error) {
25
next(error)
26
}
27
})
Copied!
1
curl --location --request POST 'http://localhost:4300/register-webhook' \
2
--header 'Content-Type: application/json'
Copied!
1
{
2
"code": 200,
3
"message": "success",
4
"data": {
5
"webhook": {
6
"id": 415,
7
"channel": "webhook",
8
"param1": "https://ten-mien-cua-ban.com/webhook/handler-bank-transfer",
9
"param2": "R5G4cbnN7uSAwfTd",
10
"sendOnlyIncome": 1
11
},
12
"userInfo": {
13
"user": {
14
"id": 1553,
15
"email": "[email protected]"
16
},
17
"business": {
18
"id": 1540,
19
"name": "Hữu Hảo"
20
},
21
"bankAccs": [
22
{
23
"id": 619,
24
"bank": {
25
"bin": 970416,
26
"codeName": "acb_digi"
27
},
28
"bankAccountName": null,
29
"bankSubAccId": "17271687",
30
"connectStatus": 1,
31
"planStatus": 1
32
},
33
{
34
"id": 623,
35
"bank": {
36
"bin": 970454,
37
"codeName": "timoplus"
38
},
39
"bankAccountName": null,
40
"bankSubAccId": "8007041023848",
41
"connectStatus": 1,
42
"planStatus": 0
43
}
44
]
45
}
46
}
47
}
Copied!
2. Route này sẽ thực hiện tính năng đồng bộ giao dịch qua Casso.
Ví dụ: Khi người dùng chuyển khoản cho bạn và họ ấn nút tôi đã thanh toán thì nên xử lí gọi qua Casso để đồng bộ giao dịch vừa được chuyển khoản. Có thể sử dụng cho tính năng Tôi đã thanh toán để xác nhận thanh toán ngay.
1
//routes/index.js
2
router.route('/users-paid')
3
.post(async (req, res, next) => {
4
try {
5
// Để thực hiện tính năng đồng bộ cần có Số tài khoản, Bạn có thể validate bằng schema ở middlewares
6
// Hoặc có thể kiểm tra trong đây luôn
7
if (!req.body.accountNumber) {
8
return res.status(404).json({
9
code: 404,
10
message: 'Not foung Account number'
11
})
12
}
13
// Tiến hành gọi hàm đồng bộ qua casso
14
await syncUtil.syncTransaction(req.body.accountNumber);
15
return res.status(200).json({
16
code: 200,
17
message: 'success',
18
data: null
19
})
20
} catch (error) {
21
next(error)
22
}
23
24
})
Copied!
3. Tạo một webhook để Casso có thể gửi giao dịch qua khi có giao dịch mới (quan trọng):
1
//routes/index.js
2
router.route('/webhook/handler-bank-transfer')
3
.post(async (req, res, next) => {
4
try {
5
// B1: Ở đây mình sẽ thực hiện check secure-token. Bình thường phần này sẽ nằm trong middlewares
6
// Mình sẽ code trực tiếp tại đây cho dễ hình dung luồng. Nếu không có secure-token hoặc sai đều trả về lỗi
7
if (!req.header('secure-token') || req.header('secure-token') != secure_token) {
8
return res.status(401).json({
9
code: 401,
10
message: 'Missing secure-token or wrong secure-token'
11
})
12
}
13
// B2: Thực hiện lấy thông tin giao dịch
14
for (let item of req.body.data) {
15
// Lấy thông orderId từ nội dung giao dịch
16
let orderId = webhookUtil.parseOrderId(case_insensitive, transaction_prefix, item.description);
17
// Nếu không có orderId phù hợp từ nội dung ra next giao dịch tiếp theo
18
if (!orderId) continue;
19
// Kiểm tra giao dịch còn hạn hay không? Nếu không qua giao dịch tiếp theo
20
if ((((new Date()).getTime() - (new Date(item.when)).getTime()) / 86400000) >= expiration_date) continue;
21
// Bước quan trọng đây.
22
// Sau khi có orderId Thì thực hiện thay đổi các trang thái giao dịch
23
// Ví dụ như kiểm tra orderId có tồn tại trong danh sách các đơn hàng của bạn?
24
// Sau đó cập nhật trạng thái theo orderId và amount nhận được: đủ hay thiếu tiền...
25
// Và một số chức năng khác có thể tùy biến
26
}
27
return res.status(200).json({
28
code: 200,
29
message: 'success',
30
data: null
31
})
32
} catch (error) {
33
next(error)
34
}
35
})
Copied!

Cảm ơn đã theo dõi

Last modified 4mo ago