javadle/qiwi

通用支付API SDK

维护者

详细信息

github.com/JavaDle/Qiwi

主页

源代码

问题

安装: 9

依赖: 0

建议者: 0

安全: 0

星标: 1

关注者: 0

分支: 19

0.2.2 2021-08-12 16:19 UTC

Requires

Requires (Dev)

MIT b9deaea7c916dc7282779f01b821a3082504529d

This package is auto-updated.

Last update: 2024-09-09 03:46:43 UTC

README

Build Status Latest Stable Version Total Downloads

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

安装和连接

使用 composer 安装

$ composer require javadle/qiwi

文档

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