Nhảy tới nội dung

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.

Example bannerGithub

Tà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

Thêm đoạn code sau vào POM và thay VERSION bằng phiên bản bạn muốn sử dụng.
<dependency>
<groupId>vn.payos</groupId>
<artifactId>payos-java</artifactId>
<version>{VERSION}</version>
</dependency>

Khởi tạo đối tượng PayOS

Bạn cần khởi tạo đối tượng PayOS bằng clientId, apiKeychecksumKey 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ứcKiểu tham số đầu vàoMô tảKiểu trả về
createPaymentLinkPaymentDataTạo link thanh toán cho dữ liệu đơn hàngCheckoutResponseData
getPaymentLinkInformationlongLấy thông tin thanh toán của đơn hàng đã tạo link thanh toán.PaymentLinkData
cancelPaymentLinklong, StringHủy link thanh toán của đơn hàng.PaymentLinkData
confirmWebhookStringXá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ôngString
verifyPaymentWebhookDataWebhookXác minh dữ liệu nhận được qua webhook sau khi thanh toánWebhookData

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);

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 longcancellationReason, 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ườngMô tảKiểu dữ liệu
orderCodeMã đơn hànglong
amountSố tiền thanh toánint
descriptionMô tả cho thanh toán, được dùng làm nội dung chuyển khoảnString
itemsDanh sách các sản phẩmList<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àngString
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ôngString

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ườngMô tảKiểu dữ liệu
nameTên sản phẩmString
quantitySố lượng sản phẩmint
priceGiá sản phẩmint

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ườngMô tảKiểu dữ liệu
binMã BIN ngân hàngString
accountNumberSố tài khoản kênh thanh toánString
accountNameTên chủ tài khoản của kênh thanh toánString
amountSố tiền thanh toánint
descriptionMô tả cho đơn hàng, được dùng làm nội dung chuyển khoảnString
orderCodeMã đơn hànglong
currencyĐơn vị tiền tệString
paymentLinkIdID của link thanh toánString
statusTrạng thái thanh toánString
checkoutUrlĐường dẫn đến trang thanh toánString
qrCodeDữ liệu cho mã QR Code cho việc quét mã thanh toánString

Kiểu Dữ Liệu PaymentLinkData

Kiểu dữ liệu này được trả về khi gọi phương thức cancelPaymentLinkgetPaymentLinkInformation. Trong PaymentLinkData, có các thông tin sau:

Tên trườngMô tảKiểu dữ liệu
idID link thanh toánString
orderCodeMã đơn hànglong
amountBiểu thị tổng số tiền thanh toánint
amountPaidBiểu thị số tiền đã thanh toánint
amountRemainingBiểu thị số tiền còn lại phải thanh toánint
statusĐại diện cho trạng thái của thanh toánString
createdAtĐại diện cho thời điểm tạo link thanh toánString
transactionsDanh sách các giao dịch chuyển khoản của link thanh toánList<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ườngMô tảKiểu dữ liệu
referenceMã tham chiếu của giao dịch chuyển khoảnString
amountSố tiền thanh toánint
accountNumberSố tài khoản của kênh thanh toánString
descriptionNội dung giao dịch chuyển khoảnString
transactionDateTimeĐại diện cho thời gian thực hiện giao dịchString
virtualAccountNameTên chủ tài khoản ảo (nếu có)String hoặc null
virtualAccountNumberSố tài khoản ảo (nếu có)String hoặc null
counterAccountBankIdMã ngân hàng đối ứng (nếu có)String hoặc null
counterAccountBankNameTên ngân hàng đối ứng (nếu có)String hoặc null
counterAccountNameTên chủ tài khoản đối ứng (nếu có)String hoặc null
counterAccountNumberSố 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ườngMô tảKiểu dữ liệu
codeMã lỗiint
descMô tả lỗiString
successTrạng thái xác thực dữ liệu nhận được qua webhook sau khi thanh toánboolean
dataMô tả WebhookDataWebhookData
signatureChữ ký dữ liệu Webhook, được sử dụng để kiểm tra tính toàn vẹn của dữ liệuString

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ườngMô tảKiểu dữ liệu
orderCodeMã đơn hànglong
amountBiểu thị tổng số tiền thanh toánint
descriptionNội dung giao dịch chuyển khoảnString
accountNumberSố tài khoản của kênh thanh toánString
referenceMã tham chiếu của giao dịchString
transactionDateTimeĐại diện cho thời gian thực hiện giao dịchString
currencyĐơn vị tiền tệString
paymentLinkIdID của link thanh toánString
codeMã trạng thái thanh toánString
descMô tả về trạng thái thanh toánString
counterAccountBankIdMã ngân hàng đối ứng (nếu có)String hoặc null
counterAccountBankNameTên ngân hàng đối ứng (nếu có)String hoặc null
counterAccountNameTên chủ tài khoản đối ứng (nếu có)String hoặc null
counterAccountNumberSố tài khoản đối ứng (nếu có)String hoặc null
virtualAccountNameTên chủ tài khoản ảo (nếu có)String hoặc null
virtualAccountNumberSố tài khoản ảo (nếu có)String hoặc null