qiwi/bill-payments-php-sdk

通用支付API SDK

维护者

详细信息

github.com/QIWI-API/bill-payments-php-sdk

主页

源代码

问题

安装数: 109,243

依赖: 2

建议者: 0

安全性: 0

星标: 56

关注者: 8

分支: 19

开放问题: 8

0.2.2 2021-08-12 16:19 UTC

Requires

Requires (Dev)

MIT b9deaea7c916dc7282779f01b821a3082504529d

This package is auto-updated.

Last update: 2024-09-12 22:36:20 UTC

README

Build Status Latest Stable Version Total Downloads

PHP SDK模块，用于实施统一的支付协议和QIWI钱包。

安装和连接

使用composer安装

$ composer require qiwi/bill-payments-php-sdk

文档

SDK使用指南（针对个人用户）: https://developer.qiwi.com/ru/p2p-sdk-guide/#integration-sdk
P2P账户API（针对个人用户）: https://developer.qiwi.com/ru/p2p-payments
QIWI收银台API（针对企业用户）: https://developer.qiwi.com/ru/bill-payments

生成自动文档 composer run docs.

认证

使用SDK需要SECRET_KEY，详细说明请参阅文档 — 针对个人用户，针对企业用户。

<?php

const SECRET_KEY = 'eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************';

$billPayments = new Qiwi\Api\BillPayments(SECRET_KEY);

?>

更改SECRET_KEY为新的

<?php

const NEW_SECRET_KEY = 'kokoOKPzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTk5NmIbhchhbbHBHIBDBI**********************';

/** @var \Qiwi\Api\BillPayments $billPayments */
$billPayments->key = NEW_SECRET_KEY;

?>

示例

默认情况下，用户有多种支付方式可供选择。在支付表单中，账户参数以明文形式通过链接传递。然后向用户显示支付表单，让用户选择支付方式。与通过API开具发票相比，这种方式不能保证所有发票都是由商家开具的。

支付表单

一种简单的集成方式。当打开表单时，会自动向客户开具发票。账户参数以明文形式通过链接传递。然后向用户显示支付表单，让用户选择支付方式。与通过API开具发票相比，这种方式不能保证所有发票都是由商家开具的。

方法createPaymentForm创建支付表单。在参数中需要指定：在QIWI个人账户中获得的提供商标识符publicKey，您系统内的账户标识符billId和金额amount。这将得到一个支付表单的链接，可以将其传递给客户。有关可用参数的详细信息，请参阅文档 — 针对个人用户，针对企业用户。

<?php

$publicKey = '2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypdXCbQJqHEJW5RJmKfj8nvgc';
$params = [
  'publicKey' => $publicKey,
  'amount' => 200,
  'billId' => 'cc961e8d-d4d6-4f02-b737-2297e51fb48e',
  'successUrl' => 'http://test.ru/',
];

/** @var \Qiwi\Api\BillPayments $billPayments */
$link = $billPayments->createPaymentForm($params);

echo $link;

?>

输出

https://oplata.qiwi.com/create?publicKey=2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypdXCbQJqHEJW5RJmKfj8nvgc&amount=200&billId=cc961e8d-d4d6-4f02-b737-2297e51fb48e&successUrl=http%3A%2F%2Ftest.ru%2F

开票

一种可靠的集成方式。参数使用授权通过server2server传递。此方法可以开具发票，如果请求成功，则响应中会返回参数payUrl — 用于将用户重定向到支付表单的链接。

方法createBill开具新的发票。在参数中需要指定：您系统内的账户标识符billId和额外的参数fields。这将返回有关开具的发票的数据。

详细描述账单参数的设置请参见SDK使用指南，以及个人用户文档和企业用户文档。

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';
$fields = [
  'amount' => 1.00,
  'currency' => 'RUB',
  'comment' => 'test',
  'expirationDateTime' => '2018-03-02T08:44:07+03:00',
  'email' => 'example@mail.org',
  'account' => 'client4563',
  ];

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->createBill($billId, $fields);

print_r($response);

?>

输出

Array
(
    [siteId] => 270305
    [billId] => cc961e8d-d4d6-4f02-b737-2297e51fb48e
    [amount] => Array
        (
            [currency] => RUB
            [value] => 200.34
        )

    [status] => Array
        (
            [value] => WAITING
            [changedDateTime] => 2018-07-12T10:28:38.855+03:00
        )

    [comment] => test
    [creationDateTime] => 2018-07-12T10:28:38.855+03:00
    [expirationDateTime] => 2018-08-26T10:28:38.855+03:00
    [payUrl] => https://oplata.qiwi.com/form/?invoice_uid=cc961e8d-d4d6-4f02-b737-2297e51fb48e&successUrl=http%3A%2F%2Ftest.ru%2F
)

账单信息

方法getBillInfo返回账单信息。在参数中需要指定您系统内的账单标识符billId，将获得账单状态的响应。更多详情请参考文档 — 个人用户，企业用户。

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->getBillInfo($billId);

print_r($response);

?>

输出

Array
(
    [siteId] => 270305
    [billId] => cc961e8d-d4d6-4f02-b737-2297e51fb48e
    [amount] => Array
        (
            [currency] => RUB
            [value] => 200.34
        )

    [status] => Array
        (
            [value] => WAITING
            [changedDateTime] => 2018-07-12T10:31:06.846+03:00
        )

    [comment] => test
    [creationDateTime] => 2018-07-12T10:31:06.846+03:00
    [expirationDateTime] => 2018-08-26T10:31:06.846+03:00
    [payUrl] => https://oplata.qiwi.com/form/?invoice_uid=cc961e8d-d4d6-4f02-b737-2297e51fb48e
)

取消未支付的账单

方法cancelBill用于取消未支付的账单。在参数中需要指定您系统内的账单标识符billId，将获得账单信息的响应。更多详情请参考文档 — 个人用户，企业用户。

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->cancelBill($billId);

print_r($response);

?>

输出

Array
(
    [siteId] => 270305
    [billId] => cc961e8d-d4d6-4f02-b737-2297e51fb48e
    [amount] => Array
        (
            [currency] => RUB
            [value] => 200.34
        )

    [status] => Array
        (
            [value] => REJECTED
            [changedDateTime] => 2018-07-12T10:32:17.595+03:00
        )

    [comment] => test
    [creationDateTime] => 2018-07-12T10:32:17.481+03:00
    [expirationDateTime] => 2018-08-26T10:32:17.481+03:00
    [payUrl] => https://oplata.qiwi.com/form/?invoice_uid=cc961e8d-d4d6-4f02-b737-2297e51fb48e
)

退款

! 此方法不适用于个人用户

通过方法refund执行退款操作。在参数中需要指定账单标识符billId、您系统内的退款标识符refundId、退款金额amount以及退款货币currency。更多详情请参考文档。

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';
$refundId = '899343443';
$amount = 12;
$currency = 'RUB';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->refund($billId, $refundId, $amount, $currency);

print_r($response);
?>

将输出退款信息和账单信息

Array
(
    [amount] => Array
        (
            [currency] => RUB
            [value] => 0.01
        )

    [dateTime] => 2018-07-12T10:34:02.191+03:00
    [refundId] => 1531380841742
    [status] => PARTIAL
)

退款信息

! 此方法不适用于个人用户

方法getRefundInfo请求退款状态，在参数中需要指定账单标识符billId和您系统内的退款标识符refundId。更多详情请参考文档。

<?php

$billId = 'cc961e8d-d4d6-4f02-b737-2297e51fb48e';
$refundId = '899343443';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->getRefundInfo($billId, $refundId);

print_r($response);

?>

将输出退款信息

Array
(
    [amount] => Array
        (
            [currency] => RUB
            [value] => 1.00
        )

    [dateTime] => 2018-07-11T15:06:55.987+03:00
    [refundId] => 1520425084283
    [status] => PARTIAL
)

辅助方法

  • 方法generateId返回格式为UUID v4的字符串，方便生成billId、refundId。
<?php

/** @var \Qiwi\Api\BillPayments $billPayments */
$billId = $billPayments->generateId();
//e9b47ee9-b2f9-4b45-9438-52370670e2a6

?>
  • 方法getLifetimeByDay生成账单的有效期，即账单可以支付的截止日期 — lifetime。输入参数为账单可支付的天数，默认为45天。方法返回ISO 8601 UTC±0:00格式的字符串。
<?php

//now: 2018-02-04T17:16:58.033Z
/** @var \Qiwi\Api\BillPayments $billPayments */
$lifetime = $billPayments->getLifetimeByDay(1);
//2018-02-05T17:16:58.033Z

?>
<?php

//now: 2018-02-04T17:16:58.033Z
/** @var \Qiwi\Api\BillPayments $billPayments */
$lifetime = $billPayments->getLifetimeByDay(0.5);
//2018-02-05T05:16:58.033Z

?>
  • 方法checkNotificationSignature用于验证来自QIWI通知服务器的账单通知签名。接受输入请求中的签名、请求体对象和用于签名的secret密钥。
<?php

$validSignatureFromNotificationServer = '07e0ebb10916d97760c196034105d010607a6c6b7d72bfa1c3451448ac484a3b';
$notificationData = [
  'bill' => [
    'siteId' => 'test',
    'billId' => 'cc961e8d-d4d6-4f02-b737-2297e51fb48e',
    'amount' => ['value' => 1, 'currency' => 'RUB'],
    'status' => ['value' => 'PAID']
  ],
  'version' => '3'
];
$secretKey = 'eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************';

/** @var \Qiwi\Api\BillPayments $billPayments */
$billPayments->checkNotificationSignature(
  $validSignatureFromNotificationServer, $notificationData, $secretKey
); // true

?>
  • 方法getPayUrl返回按账单支付的URL。
<?php

/** @var array $bill */
/** @var \Qiwi\Api\BillPayments $billPayments */
$payUrl = $billPayments->getPayUrl($bill, 'http://test.ru/');
// https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77&successUrl=http%3A%2F%2Ftest.ru%2F

?>

测试

使用真实API进行测试需要存在一个名为tests/config.php的文件，该文件按照tests/config.sample.php文件中的示例进行填充。为此，您需要一个商店的秘密密钥。

cd bill-payments-php-sdk
composer install --dev
composer run test

不使用真实API进行测试

cd bill-payments-php-sdk
composer install --dev
composer run util

要求

  • PHP v5.6.0或更高版本
  • PHP的json扩展
  • PHP的curl扩展

许可证

MIT