.NET Core SDK
Trang thanh toán payOS
Khám phá mã nguồn mẫu hoàn chỉnh được phát triển bằng Framework .NET Core. Mã nguồn server-side chuyển hướng đến trang thanh toán do payOS phát triển. Trước khi bắt đầu, hãy tạo một kênh thanh toán trên trang payOS.
GithubHoặc phiên bản dành cho .NET 5.0
GithubTài liệu
Xem tài liệu API payOS để biết thêm thông tin.
Cài đặt thư viện payOS cho dự án .NET Core
Cài đặt thư viện với dotnet:
dotnet add package payOS
Hoặc dành cho phiên bản .NET 5.0:
dotnet add package payOS.Net5
Khởi tạo đối tượng PayOS
Bạn cần khởi tạo đối tượng PayOS bằng clientId, apiKey và checksumKey của cổng thanh toán mà bạn đã tạo.
Xem hướng dẫn
using Net.PayOSHQ;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
Các phương thức có trong đối tượng PayOS
| Phương thức | Kiểu tham số đầu vào | Mô tả | Kiểu trả về |
|---|---|---|---|
| createPaymentLink | PaymentData | Tạo link thanh toán cho dữ liệu đơn hàng | CreatePaymentResult |
| getPaymentLinkInformation | long | Lấy thông tin thanh toán của đơn hàng đã tạo link thanh toán. | PaymentLinkInformation |
| cancelPaymentLink | long, String | Hủy link thanh toán của đơn hàng. | PaymentLinkInformation |
| confirmWebhook | String | Xác thực URL Webhook của kênh thanh toán và thêm hoặc cập nhật URL Webhook cho Kênh thanh toán đó nếu thành công | String |
| verifyPaymentWebhookData | WebhookType | Xác minh dữ liệu nhận được qua webhook sau khi thanh toán | WebhookData |
Phương thức createPaymentLink
Tạo link thanh toán cho dữ liệu đơn hàng với đầu vào là paymentData có kiểu PaymentData và trả về CreatePaymentResult.
Xem hướng dẫn
using Net.payOS.Types;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
ItemData item = new ItemData("Mì tôm hảo hảo ly", 1, 1000);
List<ItemData> items = new List<ItemData>();
items.Add(item);
PaymentData paymentData = new PaymentData(orderCode, 1000, "Thanh toan don hang",
items, cancelUrl="https://localhost:3002", returnUrl="https://localhost:3002");
CreatePaymentResult createPayment = await payOS.createPaymentLink(paymentData);
Phương thức getPaymentLinkInformation
Lấy thông tin thanh toán của đơn hàng đã tạo link thanh toán với đầu vào là orderId có kiểu long và trả về PaymentLinkInformation
Xem hướng dẫn
using Net.payOS.Types;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
PaymentLinkInformation paymentLinkInformation = await payOS.getPaymentLinkInformation(orderCode);
Phương thức cancelPaymentLink
Hủy link thanh toán của đơn hàng với đầu vào gồm 2 trường là orderId có kiểu long và cancellationReason,
ta có thể bỏ qua trường cancellationReason có kiểu String. Phương thức này sẽ trả về PaymentLinkInformation.
Xem hướng dẫn
using Net.payOS.Types;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
PaymentLinkInformation cancelledPaymentLinkInfo = payOS.cancelPaymentLink(orderCode, "Reason");
// If you want to cancel the payment link without reason:
PaymentLinkInformation cancelledPaymentLinkInfo = payOS.cancelPaymentLink(orderCode);
Phương thức confirmWebhook
Xác thực URL Webhook của kênh thanh toán và thêm hoặc cập nhật URL Webhook cho Kênh thanh toán. Có đầu vào là webhookUrl
có kiểu là String và trả về kiểu String.
Xem hướng dẫn
using Net.payOS.Types;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
payOS.confirmWebhook("https://your-webhook-url/")
Phương thức verifyPaymentWebhookData
Phương thức verifyPaymentWebhookData dùng để xác minh dữ liệu nhận được qua webhook sau khi thanh toán,
có đầu vào là webhookBody có kiểu là WebhookType và có kiểu trả về là WebhookData.
Xem hướng dẫn
using Net.payOS.Types;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
/*
webhookBody = {
"code": "00",
"desc": "success",
"success": true,
"data": {
"accountNumber": "0399609015",
"amount": 1000,
"description": "Ma giao dich thu nghiem",
"reference": "FT23325781308800",
"transactionDateTime": "2023-11-21 15:20:34",
"virtualAccountNumber": "",
"counterAccountBankId": "",
"counterAccountBankName": "",
"counterAccountName": "",
"counterAccountNumber": "",
"virtualAccountName": "",
"orderCode": 52422,
"currency": "VND",
"paymentLinkId": "b646a39ca8654d8fa03e0dc8bec7264c",
"code": "00",
"desc": "success"
},
"signature": "1f2eb76896a3a8e10e1f560bed4087f788c5d654af6d0a1d394351806a34d6dd"
}
*/
WebhookData webhookData = payOS.verifyPaymentWebhookData(webhookBody)
Các kiểu dữ liệu
Kiểu Dữ Liệu PaymentData
Sau khi đã khởi tạo đối tượng PayOS, để có thể tạo đường dẫn thanh toán, bạn cần phải khởi tạo PaymentData. Trong PaymentData, có 6 trường chính bắt buộc mà bạn phải khởi tạo:
| Tên trường | Mô tả | Kiểu dữ liệu |
|---|---|---|
| orderCode | Mã đơn hàng | long |
| amount | Số tiền thanh toán | int |
| description | Mô tả cho thanh toán, được dùng làm nội dung chuyển khoản | String |
| items | Danh sách các sản phẩm | List<ItemData> |
| cancelUrl | Đường dẫn sẽ được chuyển tiếp đến trang web hoặc ứng dụng của bạn khi người dùng bấm hủy đơn hàng | String |
| returnUrl | Đường dẫn sẽ được chuyển tiếp đến trang web hoặc ứng dụng của bạn khi người dùng đã thanh toán đơn hàng thành công | String |
Kiểu Dữ Liệu ItemData
Dữ liệu này lưu trữ thông tin sản phẩm của đơn hàng và được thêm vào items trong PaymentData. Có 3 trường chính bắt buộc mà bạn phải khởi tạo:
| Tên trường | Mô tả | Kiểu dữ liệu |
|---|---|---|
| name | Tên sản phẩm | String |
| quantity | Số lượng sản phẩm | int |
| price | Giá sản phẩm | int |
Kiểu Dữ Liệu CreatePaymentResult
Kiểu dữ liệu này được trả về khi gọi phương thức createPaymentLink. Trong CreatePaymentResult, có các thông tin sau:
| Tên trường | Mô tả | Kiểu dữ liệu |
|---|---|---|
| bin | Mã BIN ngân hàng | String |
| accountNumber | Số tài khoản kênh thanh toán | String |
| accountName | Tên chủ tài khoản của kênh thanh toán | String |
| amount | Số tiền thanh toán | int |
| description | Mô tả cho đơn hàng, được dùng làm nội dung chuyển khoản | String |
| orderCode | Mã đơn hàng | long |
| currency | Đơn vị tiền tệ | String |
| paymentLinkId | ID của link thanh toán | String |
| status | Trạng thái thanh toán | String |
| checkoutUrl | Đường dẫn đến trang thanh toán | String |
| qrCode | Dữ liệu cho mã QR Code cho việc quét mã thanh toán | String |
Kiểu Dữ Liệu PaymentLinkInformation
Kiểu dữ liệu này được trả về khi gọi phương thức cancelPaymentLink và getPaymentLinkInformation. Trong PaymentLinkInformation, có các thông tin sau:
| Tên trường | Mô tả | Kiểu dữ liệu |
|---|---|---|
| id | ID link thanh toán | String |
| orderCode | Mã đơn hàng | long |
| amount | Biểu thị tổng số tiền thanh toán | int |
| amountPaid | Biểu thị số tiền đã thanh toán | int |
| amountRemaining | Biểu thị số tiền còn lại phải thanh toán | int |
| status | Đại diện cho trạng thái của thanh toán | String |
| createdAt | Đại diện cho thời điểm tạo link thanh toán | String |
| transactions | Danh sách các giao dịch chuyển khoản của link thanh toán | List<Transaction> |
| cancellationReason | Đại diện cho lý do hủy thanh toán (nếu có) | String hoặc null |
| canceledAt | Đại diện cho thời điểm link thanh toán bị hủy (nếu có) | String hoặc null |
Kiểu Dữ Liệu Transaction
Kiểu dữ liệu này được sử dụng trong PaymentLinkInformation. Trong Transaction, có các thông tin sau:
| Tên trường | Mô tả | Kiểu dữ liệu |
|---|---|---|
| reference | Mã tham chiếu của giao dịch chuyển khoản | String |
| amount | Số tiền thanh toán | int |
| accountNumber | Số tài khoản của kênh thanh toán | String |
| description | Nội dung giao dịch chuyển khoản | String |
| transactionDateTime | Đại diện cho thời gian thực hiện giao dịch | String |
| virtualAccountName | Tên chủ tài khoản ảo (nếu có) | String hoặc null |
| virtualAccountNumber | Số tài khoản ảo (nếu có) | String hoặc null |
| counterAccountBankId | Mã ngân hàng đối ứng (nếu có) | String hoặc null |
| counterAccountBankName | Tên ngân hàng đối ứng (nếu có) | String hoặc null |
| counterAccountName | Tên chủ tài khoản đối ứng (nếu có) | String hoặc null |
| counterAccountNumber | Số tài khoản đối ứng (nếu có) | String hoặc null |
Kiểu Dữ Liệu WebhookType
Kiểu dữ liệu này là tham số của phương thức verifyPaymentWebhookData. Trong WebhookType, có các thông tin sau:
| Tên trường | Mô tả | Kiểu dữ liệu |
|---|---|---|
| code | Mã lỗi | int |
| desc | Mô tả lỗi | String |
| success | Trạng thái của giao dịch, true nếu thành công, false nếu thất bại | bool |
| data | Mô tả WebhookData | WebhookData |
| signature | Chữ ký dữ liệu Webhook, được sử dụng để kiểm tra tính toàn vẹn của dữ liệu | String |
Kiểu Dữ Liệu WebhookData
Kiểu dữ liệu này được trả về khi gọi verifyPaymentWebhookData. Trong WebhookData, có các thông tin sau:
| Tên trường | Mô tả | Kiểu dữ liệu |
|---|---|---|
| orderCode | Mã đơn hàng | long |
| amount | Biểu thị tổng số tiền thanh toán | int |
| description | Nội dung giao dịch chuyển khoản | String |
| accountNumber | Số tài khoản của kênh thanh toán | String |
| reference | Mã tham chiếu của giao dịch | String |
| transactionDateTime | Đại diện cho thời gian thực hiện giao dịch | String |
| currency | Đơn vị tiền tệ | String |
| paymentLinkId | ID của link thanh toán | String |
| code | Mã trạng thái thanh toán | String |
| desc | Mô tả về trạng thái thanh toán | String |
| counterAccountBankId | Mã ngân hàng đối ứng (nếu có) | String hoặc null |
| counterAccountBankName | Tên ngân hàng đối ứng (nếu có) | String hoặc null |
| counterAccountName | Tên chủ tài khoản đối ứng (nếu có) | String hoặc null |
| counterAccountNumber | Số tài khoản đối ứng (nếu có) | String hoặc null |
| virtualAccountName | Tên chủ tài khoản ảo (nếu có) | String hoặc null |
| virtualAccountNumber | Số tài khoản ảo (nếu có) | String hoặc null |