Chuyển tới nội dung chính

PHP 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 PHP Laravel hoặc PHP Code Igniter. 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.

Laravel:

Example bannerGithub

Code Igniter:

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 PHP​

composer require payos/payos

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.

use PayOS\PayOS;

$payOS = new PayOS(CLIENT_ID, API_KEY, CHECKSUM_KEY);

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ề
createPaymentLinkarrayTạo link thanh toán cho dữ liệu đơn hàngarray
getPaymentLinkInformationint|stringLấy thông tin thanh toán của đơn hàng đã tạo link thanh toán.array
cancelPaymentLinkint|string, stringHủy link thanh toán của đơn hàng.array
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
verifyPaymentWebhookDataarrayXác minh dữ liệu nhận được qua webhook sau khi thanh toánarray

Tạo link thanh toán cho dữ liệu đơn hàng với đầu vào là array dữ liệu đơn hàng và trả về array dữ liệu link thanh toán.

Xem hướng dẫn
$data = [
    "orderCode" => intval(substr(strval(microtime(true) * 10000), -6)),
    "amount" => 2000,
    "description" => "Create payment link",
    "items" => [
        [
            "name" => "Mỳ tôm Hảo Hảo ly",
            "quantity" => 1,
            "price" => 2000
        ]
    ],
    "returnUrl" => $YOUR_DOMAIN . "/success.html",
    "cancelUrl" => $YOUR_DOMAIN . "/cancel.html"
];

try {
    $response = $payOS->createPaymentLink($data);
    return redirect($response['checkoutUrl']);
} catch (\Throwable $th) {
    return $th->getMessage();
}

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à int hoặc string là mã đơn hàng và trả về array dữ liệu thông tin thanh toán.

Xem hướng dẫn
$orderCode = 123456;
try {
    $response = $payOS->getPaymentLinkInformation($orderCode);
    return $response;
} catch (\Throwable $th) {
    return $th->getMessage();
}

Hủy link thanh toán của đơn hàng với đầu vào là int hoặc string là mã đơn hàng và string là lý do hủy đơn hàng và trả về array dữ liệu thông tin hủy đơn hàng.

Xem hướng dẫn
$orderCode = 123456;
$reason = "Hủy đơn hàng";
try {
    $response = $payOS->cancelPaymentLink($orderCode, $reason);
    return $response;
} catch (\Throwable $th) {
    return $th->getMessage();
}

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 đó nếu thành công với đầu vào là string là URL Webhook và trả về string là thông báo thành công.

Xem hướng dẫn
$webhookUrl = "https://your-webhook-url/";

try {
    $payOS->confirmWebhook($webhookUrl);
    return "Webhook confirmed";
} catch (\Throwable $th) {
    return $th->getMessage();
}

Phương thức verifyPaymentWebhookData​

Xác minh dữ liệu nhận được qua webhook sau khi thanh toán với đầu vào là array dữ liệu nhận được qua webhook và trả về array dữ liệu thông tin thanh toán.

Xem hướng dẫn
$webhookData = $request->body();

try {
    $response = $payOS->verifyWebhookData($webhookData);
    return $response;
} catch (\Throwable $th) {
    return $th->getMessage();
}

Các kiểu dữ liệu​

Kiểu dữ liệu array dữ liệu đơn hàng​

$data = [
    "orderCode" => "string",            // Mã đơn hàng
    "amount" => "integer",              // Tổng tiền đơn hàng
    "description" => "string",          // Mô tả đơn hàng, được sử dụng làm nội dung chuyển khoản
    "returnUrl" => "string",            // URL của trang web hoặc ứng dụng sẽ được chuyển hướng tới khi khách hàng thanh toán thành công
    "cancelUrl" => "string",            // URL của trang web hoặc ứng dụng sẽ được chuyển hướng tới khi khách hàng hủy thanh toán
    "signature" => "string|null",       // Chữ ký cho dữ liệu của đơn hàng, có chức năng kiểm tra tính toàn vẹn của dữ liệu
    "items" => "array|null",            // Danh sách các sản phẩm của đơn hàng
    "buyerName" => "string|null",       // Tên người mua
    "buyerEmail" => "string|null",      // Email người mua
    "buyerPhone" => "string|null",      // Số điện thoại người mua
    "buyerAddress" => "string|null",    // Địa chỉ người mua
    "expiredAt" => "integer|null",      // Thời gian hết hạn của link thanh toán
];

$items = [
    [
        "name" => "string",             // Tên sản phẩm
        "quantity" => "integer",        // Số lượng sản phẩm
        "price" => "integer",           // Giá sản phẩm
    ]
];

$response = [
    "bin" => "string",              // Mã BIN ngân hàng
    "accountNumber" => "string",    // Số tài khoản của kênh thanh toán
    "accountName" => "string",      // Tên chủ tài khoản của kênh thanh toán
    "amount" => "integer",          // Số tiền của đơn hàng
    "description" => "string",      // Mô tả đơn hàng, được sử dụng làm nội dung chuyển khoản
    "orderCode" => "integer",       // Mã đơn hàng
    "currency" => "string",         // Đơn vị tiền tệ
    "paymentLinkId" => "string",    // Mã link thanh toán
    "status" => "string",           // Trạng thái của link thanh toán
    "checkoutUrl" => "string",      // Đường dẫn trang thanh toán
    "qrCode" => "string",           // Mã QR thanh toán
];
$response = [
    "id" => "string",                       // Mã link thanh toán
    "orderCode" => "integer",               // Mã đơn hàng
    "amount" => "integer",                  // Số tiền của đơn hàng
    "amountPaid" => "integer",              // Số tiền đã thanh toán
    "amountRemaining" => "integer",         // Số tiền cần thanh toán còn lại
    "status" => "string",                   // Trạng thái của link thanh toán
    "createAt" => "string",                 // Thời gian tạo link thanh toán
    "transactions" => "array",              // Danh sách các giao dịch của link thanh toán
    "cancellationReason" => "string|null",  // Lý do hủy link thanh toán nếu liên kết đã bị hủy
    "canceledAt" => "string|null",          // Thời gian hủy link thanh toán
];

$transactions = [
    [
        "reference" => "string",                    // Mã tham chiếu của giao dịch
        "amount" => "integer",                      // Số tiền chuyển khoản của giao dịch
        "accountNumber" => "string",                // Số tài khoản nhận tiền (là số tài khoản của kênh thanh toán)
        "description" => "string",                  // Nội dung chuyển khoản của giao dịch
        "transactionDateTime" => "string",          // Thời gian giao dịch
        "virtualAccountName" => "string|null",      // Tên chủ tài khoản ảo
        "virtualAccountNumber" => "string|null",    // Số tài khoản ảo
        "counterAccountBankId" => "string|null",    // Mã ngân hàng đối ứng
        "counterAccountBankName" => "string|null",  // Tên ngân hàng đối ứng
        "counterAccountName" => "string|null",      // Tên chủ tài khoản đối ứng
        "counterAccountNumber" => "string|null",    // Số tài khoản đối ứng
    ]
];

Kiểu dữ liệu array dữ liệu nhận được qua webhook​

$webhook = [
    "code" => "string",             // Mã lỗi
    "desc" => "string",             // Mô tả lỗi
    "data" => "array",              // Dữ liệu của webhook
    "signature" => "string",        // Chữ ký của webhook
]

$data = [
    "orderCode" => "integer",               // Mã đơn hàng
    "amount" => "integer",                  // Số tiền của giao dịch chuyển khoản
    "description" => "string",              // Nội dung chuyển khoản
    "accountNumber" => "string",            // Số tài khoản của kênh thanh toán
    "reference" => "string",                // Mã tham chiếu của giao dịch
    "transactionDateTime" => "string",      // Thời gian giao dịch
    "currency" => "string",                 // Đơn vị tiền tệ
    "paymentLinkId" => "string",            // Mã link thanh toán
    "code" => "string",                     // Mã lỗi
    "desc" => "string",                     // Mô tả lỗi
    "counterAccountBankId" => "string",     // Mã ngân hàng đối ứng
    "counterAccountBankName" => "string",   // Tên ngân hàng đối ứng
    "counterAccountName" => "string",       // Tên chủ tài khoản đối ứng
    "counterAccountNumber" => "string",     // Số tài khoản đối ứng
    "virtualAccountName" => "string",       // Tên chủ tài khoản ảo
    "virtualAccountNumber" => "string",     // Số tài khoản ảo
];

$response = [
    "orderCode" => "integer",               // Mã đơn hàng
    "amount" => "integer",                  // Số tiền của giao dịch chuyển khoản
    "description" => "string",              // Nội dung chuyển khoản
    "accountNumber" => "string",            // Số tài khoản của kênh thanh toán
    "reference" => "string",                // Mã tham chiếu của giao dịch
    "transactionDateTime" => "string",      // Thời gian giao dịch
    "currency" => "string",                 // Đơn vị tiền tệ
    "paymentLinkId" => "string",            // Mã link thanh toán
    "code" => "string",                     // Mã lỗi
    "desc" => "string",                     // Mô tả lỗi
    "counterAccountBankId" => "string",     // Mã ngân hàng đối ứng
    "counterAccountBankName" => "string",   // Tên ngân hàng đối ứng
    "counterAccountName" => "string",       // Tên chủ tài khoản đối ứng
    "counterAccountNumber" => "string",     // Số tài khoản đối ứng
    "virtualAccountName" => "string",       // Tên chủ tài khoản ảo
    "virtualAccountNumber" => "string",     // Số tài khoản ảo
];