README

PHP Payconiq API客户端（非官方）

支持的API版本：v3

由Optios赞助开发

API文档：https://developer.payconiq.com/online-payments-dock/#payment-api-version-3-v3-

支持的API功能

此库提供了以下Payconiq API（v3）功能的支持

• Payconiq Instore（V3）- 终端 & 显示
• Payconiq Instore（V3）- 静态QR码贴纸
• Payconiq Instore（V3）- 收据
• Payconiq Invoice（V3）- 发票
• Payconiq Online（V3）- 自定义在线
• Payconiq Online（V3）- 在线结账流程
• Payconiq Online（V3）- App2App链接
• Payconiq Online（V3）- 充值

尚未支持

• 忠诚度集成
• 支付对账API

安装

要求: PHP版本 >=7.2

composer require optiosteam/payconiq-client-php

描述

此库提供了3个主要类

• PayconiqApiClient
• PayconiqCallbackSignatureVerifier
• PayconiqQrCodeGenerator

PayconiqApiClient

这是执行对Payconiq API的REST调用的主要类，例如创建支付、取消支付、搜索支付和退款支付。

在构造函数中，您必须传递您的Payconiq API密钥，您还可以可选地注入自己的Guzzle客户端并指定是否要使用Payconiq API的生产环境或测试（Ext）环境。

public function __construct(string $apiKey, ClientInterface $httpClient = null, bool $useProd = true)

PayconiqCallbackSignatureVerifier

此类用于支持TLS双向TLS加密（TLS双向认证）。它验证回调体、JSON Web Signature（JWS）和JOSE头中的头字段。

在构造函数中，您必须传递您的Payconiq支付配置文件ID，您还可以可选地注入自己的Guzzle客户端和Symfony缓存适配器并指定是否要使用Payconiq API的生产环境或测试（Ext）环境。

public function __construct(string $paymentProfileId, ClientInterface $httpClient = null, AdapterInterface $cache = null, bool $useProd = true)

缓存适配器用于缓存Payconiq的JWKS（JSON Web Key Set）。默认情况下，此库将使用FilesystemAdapter，它将使用文件系统进行缓存。如果您想使用其他缓存系统，例如Redis，您可以注入自己的（例如RedisAdapter）。

Symfony的缓存适配器列表：https://symfony.com.cn/doc/current/components/cache.html#available-cache-adapters

注意：在使用PayconiqCallbackSignatureVerifier时，请确保您的服务器时间正确，因为验证器会检查issued-at头字段的时间戳。

PayconiqQrCodeGenerator

此类提供以下静态函数

• 自定义（颜色、大小、格式）QR码链接（用于Terminal & Display & Custom Online）
• 生成静态QR码贴纸链接（用于Static QR Sticker）
• 生成带有元数据的QR码链接，例如：描述、金额和参考（用于Receipt、Invoice & Top-up）

一些示例

请求支付

use Optios\Payconiq\PayconiqApiClient;
use Optios\Payconiq\Request\RequestPayment;

$apiKey = 'MY_PAYCONIQ_API_KEY';
$client = new PayconiqApiClient($apiKey, null, false);

$requestPayment = new RequestPayment(
    100 // = € 1
);
$requestPayment->setCallbackUrl('https://mywebsite.com/api/payconiq-webhook');
$requestPayment->setReference('ref123456');
$requestPayment->setPosId('POS00001');

$payment = $client->requestPayment($requestPayment);
var_dump($payment);

获取支付

use Optios\Payconiq\PayconiqApiClient;

$apiKey = 'MY_PAYCONIQ_API_KEY';
$client = new PayconiqApiClient($apiKey, null, false);

$payment = $client->getPayment('5bdb1685b93d1c000bde96f2');
var_dump($payment);

取消支付

use Optios\Payconiq\PayconiqApiClient;

$apiKey = 'MY_PAYCONIQ_API_KEY';
$client = new PayconiqApiClient($apiKey, null, false);

$client->cancelPayment('5bdb1685b93d1c000bde96f2');

搜索支付

use Carbon\Carbon;
use Optios\Payconiq\PayconiqApiClient;
use Optios\Payconiq\Request\SearchPayments;

$apiKey = 'MY_PAYCONIQ_API_KEY';
$client = new PayconiqApiClient($apiKey, null, false);

$search = new SearchPayments(new Carbon('2020-12-01 00:00:00'));
$searchResult = $client->searchPayments($search);
var_dump($searchResult);

退款支付

use Optios\Payconiq\PayconiqApiClient;

$apiKey = 'MY_PAYCONIQ_API_KEY';
$client = new PayconiqApiClient($apiKey, null, false);

$client->refundPayment('5bdb1685b93d1c000bde96f2');

验证回调（JWS）

use Optios\Payconiq\PayconiqCallbackSignatureVerifier;

$paymentProfileId = '5fxxxxxxxxxxxf581'; //your payconiq payment profile id

// When Payconiq sends a POST to your webhook endpoint (callbackUrl), take the signature from the request header
// e.g. Symfony: Symfony\Component\HttpFoundation\Request $request->headers->get('signature');
$signature = 'eyJ0eXAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxbg8xg';

//POST body (payload)
$payload = '{"paymentId":"5bdb1685b93d1c000bde96f2","transferAmount":0,"tippingAmount":0,"amount":100,"totalAmount":0,"createdAt":"2020-12-01T10:22:40.487Z","expireAt":"2020-12-01T10:42:40.487Z","status":"EXPIRED","currency":"EUR"}';

$payconiqCallbackSignatureVerifier = new PayconiqCallbackSignatureVerifier($paymentProfileId, null, null, false);

echo $payconiqCallbackSignatureVerifier->isValid($signature, $payload) ? 'valid' : 'invalid';

var_dump($payconiqCallbackSignatureVerifier->loadAndVerifyJWS($signature, $payload));

生成QR链接

use Optios\Payconiq\PayconiqQrCodeGenerator;

//Example 1: customized QR code (defaults are PNG, SMALL, MAGENTO)
//e.g. coming from Optios\Payconiq\Resource\Payment\Payment->getQrLink()
$qrLink = 'https://portal.payconiq.com/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F73a222xxxxxxxxx00964';
$customizedQRLink  = PayconiqQrCodeGenerator::customizePaymentQrLink(
    $qrLink,
    PayconiqQrCodeGenerator::FORMAT_PNG,
    PayconiqQrCodeGenerator::SIZE_EXTRA_LARGE,
    PayconiqQrCodeGenerator::COLOR_BLACK
);
var_dump($customizedQRLink);

//Example 2: static QR code
$staticQRLink = PayconiqQrCodeGenerator::generateStaticQRCodeLink('abc123', 'POS00001');
var_dump($staticQRLink);

贡献

请随意提交改进和错误修复的pull请求。

请确保您的pull请求遵守以下指南

• 输入有意义的pull请求描述。
• 在您的pull请求票据中放入每个库的链接，以便更容易审查。
• 请使用以下格式为库添加描述：库 - 描述。
• 请确保您的文本编辑器设置为删除尾随空格。

MIT许可证