README

为 Przelewy24 提供的 PHP 封装。

如果你使用 Laravel，可以查看 mnastalski/przelewy24-laravel。

Przelewy24 的 API 文档可在 https://developers.przelewy24.pl/ 获取。

要求

PHP >=8.1

对于较低的 PHP 版本，请检查 0.x 版本。

安装

composer require mnastalski/przelewy24-php

使用方法

创建实例

use Przelewy24\Przelewy24;

$przelewy24 = new Przelewy24(
    merchantId: 12345,
    reportsKey: 'f0ae...',
    crc: 'aef0...',
    isLive: false,
);

将 isLive 设置为 false 将使用沙箱环境。将其设置为 true 以使用生产/实时模式。

测试连接

你可以使用以下方法来测试使用提供的凭据连接到 Przelewy24 API 是否正常工作

$test = $przelewy24->tests()->testAccess();

var_dump($test->data());

bool(true)

创建交易

$transaction = $przelewy24->transactions()->register(
    // Required parameters:
    sessionId: 'unique order identifier from your application',
    amount: 125,
    description: 'transaction description',
    email: 'buyer email address',
    urlReturn: 'url to return to after transaction',

    // Optional parameters:
    urlStatus: 'url to which the transaction status webhook will be sent',

    // client: 'Mateusz Nastalski',
    // currency: \Przelewy24\Enums\Currency::EUR,
    // language: Language::ENGLISH,
    // ...
);

请注意，amount 是以整数的形式传递的，因此如果实际金额是 1.25 PLN，你需要将值传递为 125。

有关可用参数的完整列表，请检查 TransactionRequests::register() 的签名。

返回交易的令牌

$transaction->token();

返回支付网关的 URL

$transaction->gatewayUrl();

监听交易注册状态 webhook

要解析 webhook 的有效负载，请将整个 POST 数据作为数组传递给 handleWebhook()

// $requestData = $request->request->all();
// $requestData = $request->post();
// $requestData = json_decode(file_get_contents('php://input'), true);

$webhook = $przelewy24->handleWebhook($requestData);

handleWebhook() 返回 TransactionStatusNotification::class，该类提供了一些有用的方法，你可以使用这些方法来检查交易数据，以及验证 webhook 的签名

$webhook->amount();
$webhook->currency();
$webhook->orderId();
...
$webhook->isSignValid(...);

如果你想要确保传入请求的 IP 地址属于 Przelewy24，那么有效的 IP 列表可在 \Przelewy24\Constants\IpAddresses::V4 常量中找到。还有一个辅助方法接受一个包含 IP 地址的字符串并返回布尔值：\Przelewy24\Constants\IpAddresses::isValid($ip)。

验证交易

$przelewy24->transactions()->verify(
    sessionId: 'unique order identifier from your application',
    orderId: $webhook->orderId(),
    amount: 125,
);

与注册交易类似，amount 也是以整数的形式传递的。

退款交易

$refund = $przelewy24->transactions()->refund(
    requestId: 'unique request identifier from your application',
    refundsId: 'unique refunds identifier from your application',
    refunds: [
        new RefundItem(
            orderId: $webhook->orderId(),
            sessionId: 'unique order identifier from your application',
            amount: 2100,
            description: 'item #1',
        ),
        new RefundItem(
            orderId: $webhook->orderId(),
            sessionId: 'unique order identifier from your application',
            amount: 125,
            description: 'item #2',
        ),
    ],
    urlStatus: 'url to which the refund status webhook will be sent',
);

返回退款项列表

$refund->refunds();

监听交易退款状态 webhook

要解析 webhook 的有效负载，请将整个 POST 数据作为数组传递给 handleRefundWebhook()

// $requestData = $request->request->all();
// $requestData = $request->post();
// $requestData = json_decode(file_get_contents('php://input'), true);

$webhook = $przelewy24->handleRefundWebhook($requestData);

错误处理

如果 Przelewy24 的 API 返回错误响应，将抛出 ApiResponseException::class（它扩展了 Przelewy24Exception::class）。因此，你可以使用 try/catch 块来处理任何错误。

use Przelewy24\Exceptions\Przelewy24Exception;

try {
    $przelewy24->transactions()->verify([
        // ...
    ]);
} catch (Przelewy24Exception $e) {
    // Handle the error...
}

mnastalski / przelewy24-php

维护者

详细信息