README

此存储库中的代码允许执行Autopay S.A.提供的交易以及其他服务。

在实现自定义支付模块时，建议使用SDK。

注意：在1.0.0版本中，支付和ITN可能只能使用有限参数集。

存储库

启动测试

docker-compose up
docker exec -it php_bm_sdk composer install
docker exec -it php_bm_sdk ./vendor/bin/phpunit tests

要求

PHP版本7.2或更高。
PHP扩展
- xmlwriter,
- xmlreader,
- iconv,
- mbstring,
- hash

安装

$ composer require bluepayment-plugin/bm-sdk

如果你不使用任何框架（例如Symfony），那么在安装后可能需要根据网站上的示例手动加载类https://getcomposer.org.cn/doc/01-basic-usage.md#autoloading:

require_once 'vendor/autoload.php';

// ..

$client = new BlueMedia\Client('ID SERWISU', 'KLUCZ WSPÓŁDZIELONY');

如果未正确加载类，将会出现“找不到类”的错误。

客户端配置

为了创建通信层，需要创建一个带有服务id和共享密钥（由Autopay分配）的 BlueMedia\Client 类对象。

$client = new BlueMedia\Client('ID SERWISU', 'KLUCZ WSPÓŁDZIELONY');

在创建客户端对象时，可以在服务数据参数中添加使用的加密模式和数据分隔符（如果指定了非默认值）。

$client = new BlueMedia\Client(
    'ID SERWISU', 
    'KLUCZ WSPÓŁDZIELONY',
    'sha256', // tryb hashowania, domyślnie sha256, można użyć stałej z BlueMedia\Common\Enum\ClientEnum
    '|' // separator danych, domyślnie |
);

通过支付墙重定向进行交易

执行交易的最简单类型是重定向到Autopay服务，并带有交易数据。在这种情况下，支付处理完全由Autopay服务端处理。

要执行交易，需要调用 getTransactionRedirect 方法，正确执行该方法将返回一个执行重定向到Autopay服务的表单。

$result = $client->getTransactionRedirect([
   'gatewayUrl' => 'https://testpay.autopay.eu', // Adres bramki Autopay
   'transaction' => [
       'orderID' => '123', // Id transakcji, wymagany
       'amount' => '1.20', // Kwota transakcji, wymagany
       'description' => 'Transakcja 123-123', // Tytuł transakcji, opcjonalny
       'currency' => 'PLN', // Waluta transakcji, opcjonalny, domyślnie PLN
       'customerEmail' => 'test@hostname.domain' // Email klienta, opcjonalny, zalecany ze względu na automatyczne uzupełnienie pola po stronie serwisu BM
   ]
]);

echo $result->getData();

支付后，Autopay服务将重定向到之前配置的支付返回地址。重定向是通过带有三个参数的HTTPS（GET）请求完成的

ServiceID - 服务标识符
OrderID - 交易标识符
Hash - 基于ServiceID和OrderID计算出的校验和。

支付返回页面需要验证Hash的正确性，这可以通过 doConfirmationCheck 方法实现。需要将GET请求中传递的数据传递给该方法。

$data = [
    'ServiceID' => '123456',
    'OrderID' => '123',
    'Hash' => 'df5f737f48bcef93361f590b460cc633b28f91710a60415527221f9cb90da52a'
];

$result = $client->doConfirmationCheck($data); // true | false

交易前

doTransactionInit 方法扩展了标准交易开始模型，以处理特定的需求

基于发送的参数创建支付链接
向客户收费（如果不需要客户进行额外授权）
在客户被重定向到系统之前验证支付链接的正确性 - 调用将导致参数和系统配置的验证
缩短支付链接 - 而不是几个/十几个参数，链接被缩短到两个标识符
隐藏敏感参数链接中的数据 - 交易前在后台进行，继续交易链接不包含敏感数据，只包含继续标识符
在完整（安全）模式下使用SDK

该方法接受与支付墙重定向交易相同的参数，但发送了不同的标题，因此Autopay服务以不同的方式处理请求。响应中会收到继续交易或通知无法继续及支付状态的链接。

交易前，继续支付链接

$result = $client->doTransactionInit([
    'gatewayUrl' => 'https://testpay.autopay.eu',
    'transaction' => [
        'orderID' => '123',
        'amount' => '1.20',
        'description' => 'Transakcja 123-123',
        'currency' => 'PLN',
        'customerEmail' => 'test@hostname.domain'
    ]
]);

$transactionContinue = $result->getData();

$transactionContinue->getRedirectUrl(); // https://testpay.autopay.eu/payment/continue/9IA2UISN/718GTV5E
$transactionContinue->getStatus(); // PENDING
$transactionContinue->getOrderId(); // 123
$transactionContinue->toArray(); // [...]
// ...

交易前，不继续

$result = $client->doTransactionInit([
    'gatewayUrl' => 'https://testpay.autopay.eu',
    'transaction' => [
        'orderID' => '123',
        'amount' => '1.20',
        'description' => 'Transakcja 123-123',
        'gatewayID' => '1500',
        'currency' => 'PLN',
        'customerEmail' => 'test@hostname.domain',
        'customerIP' => '127.0.0.1',
        'title' => 'Test',
    ]
]);

$transactionInit = $result->getData();

$transactionInit->getConfirmation(); // NOTCONFIRMED
$transactionInit->getReason(); // MULTIPLY_PAID_TRANSACTION
$transactionInit->getOrderId(); // 123
$transactionInit->toArray(); // [...]
// ...

快速转账

快速转账是一种支付方式，它要求客户自行输入系统提供的转账数据。可以通过doTransactionBackground方法获取转账数据。

根据交易上下文中选择的支付渠道，该方法将返回转账数据或已准备好的支付表单。

调用示例（交易数据）

$result = $client->doTransactionBackground([
    'gatewayUrl' => 'https://testpay.autopay.eu',
    'transaction' => [
       'orderID' => '12345',
       'amount' => '5.12',
       'description' => 'Test transaction 12345',
       'gatewayID' => '21',
       'currency' => 'PLN',
       'customerEmail' => 'test@test.test',
       'customerIP' => '127.0.0.1',
       'title' => 'Test',
       'validityTime' => date('Y-m-d H:i:s', strtotime('now +5 hour')),
       'linkValidityTime' => date('Y-m-d H:i:s', strtotime('now +5 hour'))
    ]
]);

$transactionBackground = $result->getData();

$transactionBackground->getReceiverNRB(); // 47 1050 1764 1000 0023 2741 0516
$transactionBackground->getReceiverName(); // Autopay
$transactionBackground->getBankHref(); // https://ssl.bsk.com.pl/bskonl/login.html
$transactionBackground->toArray(); // [...]
// ...

调用示例（支付表单）

$result = $client->doTransactionBackground([
    'gatewayUrl' => 'https://testpay.autopay.eu',
    'transaction' => [
       'orderID' => '12345',
       'amount' => '5.12',
       'description' => 'Test transaction 12345',
       'gatewayID' => '1500',
       'currency' => 'PLN',
       'customerEmail' => 'test@test.test',
       'customerIP' => '127.0.0.1',
       'title' => 'Test',
       'validityTime' => date('Y-m-d H:i:s', strtotime('now +5 hour')),
       'linkValidityTime' => date('Y-m-d H:i:s', strtotime('now +5 hour'))
    ]
]);

$transactionBackground = $result->getData();

echo $transactionBackground; // <form action="https://pg-accept.blue.pl/gateway/test/index.jsp" name="formGoPBL" method="POST"><input type="hidden" name="transaction" value="758519"> (...)

ITN（即时交易通知）处理

支付后，Autopay服务会将支付状态的消息发送到预先配置的ITN地址。数据以XML格式发送，并额外进行了base64编码。SDK提供doItnIn方法，通过传递Autopay服务的数据，返回一个BlueMedia\Itn\ValueObject\ItnIn对象，允许使用访问器或转换为数组。通过此对象，程序员可以使用所需的数据，例如更新数据库中的支付状态等。

处理完ITN消息后，需要传递响应。这是通过doItnInResponse方法完成的，它接受一个ItnIn对象和一个表示交易确认的参数。

以下为ITN处理示例

$result = $client->doItnIn($_POST['transactions']);

$itnIn = $result->getData();
$transactionConfirmed = $client->checkHash($itnIn);

// Jeżeli status płatności z ITN jest potwierdzony i hash jest poprawny - zakończ płatność w systemie
if ($itnIn->getPaymentStatus() === 'SUCCESS' && $transactionConfirmed) {
    $order = $this->orderRepository->find($itnIn->getOrderId());

    $order->setPaymentCompleted();
}

$itnResponse = $client->doItnInResponse($itnIn, $transactionConfirmed);

return new Response($itnResponse->getData()->toXml());

ITN，创建消息对象

在实现过程中，可能需要在处理ITN之前执行某些操作，例如根据货币数据配置客户端。在这种情况下，程序员可以使用getItnObject方法。

$itn = Client::getItnObject($_POST['transactions']);

$itn->getCurrency(); // PLN
// ...

获取当前可用的法规列表

getRegulationList方法允许查询当前法规列表，以及显示在服务中查看和客户端接受的链接。

$result = $this->client->getRegulationList('https://testpay.autopay.eu');

return $result->getData();

获取支付通道列表

testGetPaywayList方法允许查询当前支付列表。

$result = $this->client->getPaywayList('https://testpay.autopay.eu');

return $result->getData();

bluepayment-plugin / bm-sdk

维护者

详细信息