README

收单API PHP SDK。

此包提供了普联银行（PSB）收单API的软件开发工具包。

安装

您可以通过composer安装此包

composer require pashamesh/psb-acquiring-php-sdk

使用

设置客户端

设置Config实例

use Pashamesh\PsbAcquiringPhpSdk\Config;
use Pashamesh\PsbAcquiringPhpSdk\PsbClient;

$config = Config::fromArray([
    'component1' => '<COMPONENT1>',
    'component2' => '<COMPONENT2>',
    'merchantName' => 'Real Shop',
    'merchantNumber' => '<MERCHANT_NUMBER>',
    'terminalNumber' => '<TERMINAL_NUMBER>',
    'merchantEmail' => '<MERCHANT_EMAIL>',
    'notifyUrl' => 'https://some.domain/notify.php',
    'returnUrl' => 'https://some.domain/',
]);
$psb = new PsbClient($config);

其中component1、component2、merchantNumber和terminalNumber是银行提供的凭据。

测试环境

为了配置客户端在测试和开发目的使用测试环境，只需跳过component1和component2即可

use Pashamesh\PsbAcquiringPhpSdk\Config;
use Pashamesh\PsbAcquiringPhpSdk\PsbClient;

$testEnvironmentConfig = Config::fromArray([
    'merchantName' => 'Test Shop',
    'merchantNumber' => '000599979036777',
    'terminalNumber' => '79036777',
    'merchantEmail' => 'merchant@mail.test',
    'notifyUrl' => 'https://some.domain/notify.php',
    'returnUrl' => 'https://some.domain/',
]);
$psb = new PsbClient($testEnvironmentConfig);

如何使用

预授权

启动预授权

渲染并自动提交预授权表单，该表单将客户重定向到银行付款页面

$customerEmail = 'cardholder@mail.test';
$orderId = '620749153';
$amount = 300.;

$psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->preauthorize($amount)
    ->sendForm();

或者如果您需要更多控制，可以获取表单的HTML内容

$preauthorizeFormHtml = $psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->preauthorize($amount)
    ->getForm();

也可以获取预授权的支付链接，例如通过电子邮件发送给客户

$expiresAt = '01.04.2023 03:30:00';

$preauthorizeLink = $psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->additionalInfo('Additional information')
    ->preauthorize($amount)
    ->getLink($expiresAt);

要在预授权过程中保存卡，请使用preauthorizeAndSaveCard方法

$psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->preauthorizeAndSaveCard($amount)
    ->sendForm();

通知HTTP调用将包含TOKEN_ID以标识已保存的卡。

存在一个preauthorizeUsingCard来执行预授权并使用已保存的卡

$cardTokenId = '<CARD_TOKEN_UUID>';

$psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->preauthorizeUsingCard($amount, $cardTokenId)
    ->sendForm();

完成预授权

$rrn = '<PREAUTHORIZATION_RETRIEVAL_REFERENCE_NUMBER>';
$intRef = '<PREAUTHORIZATION_INTERNAL_REFERENCE>';

$finalAmount = 300.;

$syncResponse = $psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->transaction($rrn, $intRef, $amount)
    ->completePreauthorization($finalAmount)
    ->sendRequest();

取消预授权

$syncResponse = $psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->transaction($rrn, $intRef, $amount)
    ->cancelPreauthorization($finalAmount)
    ->sendRequest();

购买

购买使用与预授权类似的流程。渲染并自动提交预授权表单，该表单将客户重定向到银行付款页面

$psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->purchase($amount)
    ->sendForm();

或者获取表单的HTML内容

$preauthorizeFormHtml = $psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->purchase($amount)
    ->getForm();

或者获取购买支付链接

$expiresAt = '01.04.2023 03:30:00';

$purchaseLink = $psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->purchase($amount)
    ->getLink($expiresAt);

要在购买过程中保存卡，请使用purchaseAndSaveCard方法

$psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->purchaseAndSaveCard($amount)
    ->sendForm();

存在一个purchaseUsingCard来执行购买并使用已保存的卡

$cardTokenId = '<CARD_TOKEN_UUID>';

$psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->purchaseUsingCard($amount, $cardTokenId)
    ->sendForm();

周期性支付

注册

$frequency = 1;
$expirationDate = '20240101';

$psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->purchase($amount)
    ->registerRecurring($frequency, $expirationDate)
    ->sendForm();

付款

$recurringRrn = '<RECURRING_RETRIEVAL_REFERENCE_NUMBER>';
$recurringIntRef = '<RECURRING_INTERNAL_REFERENCE>';

$syncResponse = $psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->doRecurringPayment($amount, $recurringRrn, $recurringIntRef)
    ->sendRequest();

退款

$rrn = '<PURCHASE_RETRIEVAL_REFERENCE_NUMBER>';
$intRef = '<PURCHASE_INTERNAL_REFERENCE>';

$response = $psb
    ->customer($customerEmail)
    ->order($orderId, "Order #{$orderId}")
    ->transaction($rrn, $intRef, $amount)
    ->refund($finalAmount)
    ->sendRequest();

卡片

从现有交易保存卡

$rrn = '<RETRIEVAL_REFERENCE_NUMBER>';
$intRef = '<INTERNAL_REFERENCE>';

$syncResponse = $psb
    ->customer($customerEmail)
    ->order($orderId, "Test payment")
    ->transaction($rrn, $intRef)
    ->saveCard()
    ->sendRequest();

$syncResponse将包含标识已保存卡的TOKEN_ID。

忘记已保存的卡

$cardTokenId = '<CARD_TOKEN_UUID>';

$syncResponse = $psb
    ->forgetCard($cardTokenId)
    ->sendRequest();

if ($syncResponse->isOperationApproved()) {
    // The card token was forgotten.
}

处理回调HTTP调用

异步HTTP回调请求的有效签名必须进行验证。SDK提供方便的方法handleCallbackRequest。它验证签名并返回带有请求属性的Payload模型。

示例

try {
    $payload = $client->handleCallbackRequest($_POST);
    if ($payload->isOperationApproved()) {
        $orderId = $payload->order;
        $referenceReturnNumber = $payload->rrn;
        $internalReference = $payload->int_ref;

        // Process data here. For example store in database.
    }

    echo "OK";
} catch (Exception $exception) {
    echo $exception->getMessage();
}

开发

有一个Docker-compose设置和一些方便的make快捷方式用于开发目的。

安装依赖项

使用以下命令安装composer依赖项

make

代码风格

此包遵循PSR-12编码标准和PSR-4自动加载标准。

使用以下命令修复代码风格

make lint

运行测试

使用以下命令运行Unit和代码静态分析

make test

链接

原始文档（俄语）

pashamesh / psb-acquiring-php-sdk

维护者

详细信息