Java 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 Spring Boot. 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.
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 Java
- Maven
- Gradle
<dependency>
<groupId>vn.payos</groupId>
<artifactId>payos-java</artifactId>
<version>{VERSION}</version>
</dependency>
implementation 'vn.payos:payos-java:{VERSION}'
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
import vn.payos.PayOS;
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 | CheckoutResponseData |
getPaymentLinkInformation | long | Lấy thông tin thanh toán của đơn hàng đã tạo link thanh toán. | PaymentLinkData |
cancelPaymentLink | long , String | Hủy link thanh toán của đơn hàng. | PaymentLinkData |
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 | Webhook | 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ề CheckoutResponseData
.
Xem hướng dẫn
import vn.payos.PayOS;
import vn.payos.type.CheckoutResponseData;
import vn.payos.type.PaymentData;
import vn.payos.type.ItemData;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
ItemData itemData = ItemData.builder().name("Mỳ tôm Hảo Hảo ly").quantity(1).price(2000).build();
PaymentData paymentData = PaymentData.builder().orderCode(orderCode).amount(2000)
.description("Thanh toán đơn hàng").returnUrl(webhookUrl + "/success").cancelUrl(webhookUrl + "/cancel")
.item(itemData).build();
CheckoutResponseData result = 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ề PaymentLinkData
Xem hướng dẫn
import vn.payos.PayOS;
import vn.payos.type.PaymentLinkData;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
PaymentLinkData paymentLinkData = 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ề PaymentLinkData
.
Xem hướng dẫn
import vn.payos.PayOS;
import vn.payos.type.PaymentLinkData;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
PaymentLinkData paymentLinkData = payOS.cancelPaymentLink(orderCode, "Hủy đơn hàng");
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
import vn.payos.PayOS;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
String verifiedWebhookUrl = payOS.confirmWebhook(webhookUrl);
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à Webhook
và có kiểu trả về là WebhookData
.
Xem hướng dẫn
import vn.payos.PayOS;
import vn.payos.type.Webhook;
import vn.payos.type.WebhookData;
PayOS payOS = new PayOS(clientId, apiKey, checksumKey);
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 CheckoutResponseData
Kiểu dữ liệu này được trả về khi gọi phương thức createPaymentLink
. Trong CheckoutResponseData
, 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 PaymentLinkData
Kiểu dữ liệu này được trả về khi gọi phương thức cancelPaymentLink
và getPaymentLinkInformation
. Trong PaymentLinkData
, 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 PaymentLinkData
. 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 Webhook
Kiểu dữ liệu này là tham số của phương thức verifyPaymentWebhookData
. Trong Webhook
, 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 xác thực dữ liệu nhận được qua webhook sau khi thanh toán | boolean |
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 |