pay2pay / php-sdk

1.0.0 2026-08-24 09:51 UTC

Requires

• php: >=7.0
• ext-curl: *
• ext-json: *
• ext-openssl: *

Requires (Dev)

• phpunit/phpunit: ^5.7 || ^6.5 || ^7.5

MIT

• payment
• gateway
• qr
• vietnam
• payout
• paypay
• napas
• pay2pay

Published on Packagist.org on 2026-08-24 09:53 UTC

README

Thư viện Composer cho Pay2Pay (PayPay) Payment Gateway, tương thích PHP >= 7.0.

Bao phủ đầy đủ ba tài liệu tích hợp chính thức:

Tài liệu	Phiên bản	Được hỗ trợ bởi
PP-COLLECTION-API	v1.2	$pay2pay->collection()
PP-COLLECTION-REDIRECT-API	v1.3	$pay2pay->checkout(), $pay2pay->returnUrl()
PP-PAYOUT-API	v1.4	$pay2pay->payout()

Bản PDF gốc được lưu trong docs/pdf/.

Vì sao cần thư viện này

Phần khó nhất khi tích hợp Pay2Pay không phải là gọi HTTP mà là ba loại chữ ký khác nhau, dễ nhầm lẫn:

1. p-signature — RSA-2048 (SHA256withRSA) trên header đã sắp xếp + body, cho mọi API.
2. Chữ ký link redirect — base64(sha256_raw(giá trị tham số sort a-z + merchant_key)).
3. Chữ ký IPN / URL callback — base64(sha256_raw(raw body + secretKey)).

Cộng thêm việc mật khẩu lại băm theo kiểu thứ tư — base64(sha256_hex(...)) — nên copy nhầm một hàm là hỏng cả luồng. SDK gói toàn bộ chuyện đó vào một chỗ, có test đối chiếu trực tiếp với ví dụ in trong tài liệu.

Cài đặt

Yêu cầu: PHP >= 7.0 (đã kiểm thử tới PHP 8.5), ext-curl, ext-json, ext-openssl.

Gói này chưa có trên Packagist. composer require pay2pay/php-sdk sẽ báo Could not find a matching version of package — hãy chọn một trong ba cách dưới.

Cách 1 — Composer với repository dạng path (khuyến nghị khi cùng máy)

Trong composer.json của dự án đang dùng:

{
    "repositories": [
        { "type": "path", "url": "/duong/dan/toi/pay2pay-php-sdk", "options": { "symlink": true } }
    ],
    "require": {
        "pay2pay/php-sdk": "*"
    }
}

composer update pay2pay/php-sdk

Với symlink: true, sửa code trong thư mục SDK là dự án thấy ngay.

Gói này khai sẵn "version": "1.0.0" trong composer.json — nếu bỏ dòng đó đi, Composer sẽ suy ra version từ Git; repo chưa có tag thì thành dev-main và bạn gặp:

Could not find a version of package pay2pay/php-sdk matching your
minimum-stability (stable).

Ba cách chữa, chọn một:

Cách	Làm gì
Giữ "version" trong composer.json của SDK	Không phải làm gì thêm — mặc định hiện tại
Gắn tag cho repo SDK	git tag v1.0.0 (không cần push nếu dùng repo dạng path)
Cho phép bản dev ở dự án tiêu thụ	Đổi constraint thành "pay2pay/php-sdk": "@dev"

Nếu sau này bạn publish lên Packagist, hãy xoá dòng "version" — khi đó Packagist lấy version từ Git tag, và để lại field này sẽ gây xung đột.

Cách 2 — Composer qua Git

Đẩy thư mục này lên một repository Git (GitHub, GitLab, Bitbucket hoặc Git nội bộ), gắn tag phiên bản, rồi khai báo:

{
    "repositories": [
        { "type": "vcs", "url": "[e-mail]:cong-ty-cua-ban/pay2pay-php-sdk.git" }
    ],
    "require": {
        "pay2pay/php-sdk": "^1.0"
    }
}

git init && git add . && git commit -m "Pay2Pay PHP SDK"
git tag v1.0.0 && git push origin main --tags

Cách 3 — Không dùng Composer

require '/duong/dan/toi/pay2pay-php-sdk/autoload.php';

$pay2pay = Pay2Pay\Pay2Pay::make([...]);

autoload.php ở gốc thư mục là một PSR-4 autoloader độc lập, không phụ thuộc gì cả.

Nếu Composer in đầy cảnh báo Deprecated

Đó là Composer cũ chạy trên PHP 8.x, không liên quan tới thư viện này:

composer self-update            # cập nhật Composer 2.x mới nhất
composer --version              # nên >= 2.7

Và đừng chạy Composer bằng root — nó sẽ cảnh báo và có thể tạo file sai quyền.

Dùng nhanh

use Pay2Pay\Pay2Pay;

$pay2pay = Pay2Pay::make([
    'environment' => 'uat',              // uat | production
    'tenant'      => 'MERCHANT-WEB',
    'username'    => '0982569888',
    'password'    => 'mat-khau-goc',     // mật khẩu GỐC, SDK tự băm
    'private_key' => file_get_contents('/etc/pay2pay/private.pem'),
    'merchant_id' => 'PP0000024',
    'merchant_key'=> 'm3arCAFqqRQuSh1tQwsJJg==',
    'secret_key'  => 'MySecretKey',
]);

// Thu hộ: tạo QR động cho một đơn hàng
$qr = $pay2pay->collection()->initializeDynamicQr('DH001', 500000, 'Thanh toan don hang');
echo $qr->getData('qrInfo');

// Thu hộ: chuyển hướng sang trang thanh toán Pay2Pay
header('Location: ' . $pay2pay->checkout()->build([
    'order_code'   => 'DH001',
    'total_amount' => 108000,
    'content'      => 'Thanh toan don hang',
]));

// Chi hộ: chuyển tiền 24/7
$pay2pay->payout()->transfer247([
    'amount'        => 200000,
    'bankId'        => 'BIDV',
    'bankCode'      => '970418',
    'bankRefNumber' => '1023020330000',
    'bankRefName'   => 'NGUYEN VAN A',
    'content'       => 'Hoan tien DH001',
]);

SDK tự lo access token (login, cache, refresh) và tự xin verifiedKey trước lệnh chi.

Tài liệu

Trang	Nội dung
01 — Cài đặt & cấu hình	Tham số cấu hình, sinh khoá RSA, lưu token
02 — Chữ ký & xác thực	Bốn thuật toán chữ ký, cách gỡ khi lệch
03 — Thu hộ qua API	QR tĩnh/động, inquiry, hoàn tiền
04 — Thu hộ qua Redirect	Tạo link thanh toán, xử lý URL trả về
05 — Chi hộ	Số dư, danh sách bank, chuyển tiền 24/7
06 — IPN	Xác thực và xử lý callback an toàn
07 — Mã lỗi & trạng thái	Bảng mã, cách phản ứng với từng nhóm
08 — Tham chiếu API	Danh sách đầy đủ lớp và phương thức

Ví dụ chạy được nằm trong examples/.

Ba điều dễ sai nhất

1. Đừng bao giờ tin URL trả về. Tham số trên url_redirect do trình duyệt của người dùng mang về. Chỉ dùng nó để hiển thị; ghi nhận đơn hàng phải dựa vào IPN hoặc inquiryV2().

2. IPN phải băm đúng raw body. $pay2pay->ipn()->handle() đọc thẳng php://input. Nếu bạn json_decode rồi json_encode lại để tính chữ ký thì chỉ cần lệch một dấu cách là sai.

3. Timeout khi chi hộ không có nghĩa là thất bại. Với ERR_BANK_TIMEOUT, ERR_MERCHANT_CORE_TIMEOUT, ERR_MERCHANT_BANK_TIMEOUT hoặc timeout tầng mạng, tiền có thể đã đi. Phải gọi inquiry() theo auditNumber — dùng transfer247Safe() để SDK làm việc đó thay bạn.

Chạy test

composer install && vendor/bin/phpunit

# hoặc không cần composer:
php tests/run.php

Bộ test đối chiếu trực tiếp với các ví dụ chữ ký in trong tài liệu Pay2Pay.

Giấy phép

MIT.