wpdesk/bm-sdk

Blue Media PHP SDK

维护者

详细信息

github.com/wpdesk/bm-sdk

源代码

安装: 478

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 19

3.2.1 2022-06-27 13:01 UTC

Requires

Requires (Dev)

LGPL-3.0-only df6b236315cbdbbe1554b74ef04e714cc0fd164b

This package is not auto-updated.

Last update: 2024-09-17 22:41:59 UTC

README

该仓库包含的代码允许执行Blue Media 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

客户端配置

要创建通信层，需要创建一个类BlueMedia\Client的对象，提供服务id和共享密钥（由BlueMedia提供）。

$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 |
);

通过支付墙跳转的交易

执行交易的最简单类型是跳转到BlueMedia服务并带上交易数据。支付处理完全由BlueMedia服务端完成。

要执行交易，需要调用getTransactionRedirect方法，正确执行该方法将返回一个表单，该表单将执行跳转到BlueMedia服务。

$result = $client->getTransactionRedirect([
   'gatewayUrl' => 'https://pay-accept.bm.pl', // Adres bramki BlueMedia
   'transaction' => [
       'orderID' => '123', // Id transakcji, wymagany
       'amount' => '1.20', // Kwota transakcji, wymagany
       'description' => 'Transakcja 123-123', // Tytuł transakcji, opcjonalny
       'gatewayID' => '0', // Identyfikator kanału płatności, opcjonalny, w tym przypadku można ustawić jako 0 lub pominąć
       '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();

支付后，BlueMedia服务将跳转到之前配置的支付返回地址。跳转通过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

该方法接受与通过支付墙跳转的交易相同的参数，区别在于发送的标题不同，这使得BlueMedia服务可以以不同的方式处理请求。在响应中，将收到继续交易的链接或告知没有继续交易的响应以及支付状态。

交易前，继续支付链接

$result = $client->doTransactionInit([
    'gatewayUrl' => 'https://pay-accept.bm.pl',
    'transaction' => [
        'orderID' => '123',
        'amount' => '1.20',
        'description' => 'Transakcja 123-123',
        'gatewayID' => '0',
        'currency' => 'PLN',
        'customerEmail' => 'test@hostname.domain'
    ]
]);

$transactionContinue = $result->getData();

$transactionContinue->getRedirectUrl(); // https://pay-accept.bm.pl/payment/continue/9IA2UISN/718GTV5E
$transactionContinue->getStatus(); // PENDING
$transactionContinue->getOrderId(); // 123
$transactionContinue->toArray(); // [...]
// ...

交易前，取消继续

$result = $client->doTransactionInit([
    'gatewayUrl' => 'https://pay-accept.bm.pl',
    '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://pay-accept.bm.pl',
    '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(); // Blue Media
$transactionBackground->getBankHref(); // https://ssl.bsk.com.pl/bskonl/login.html
$transactionBackground->toArray(); // [...]
// ...

调用示例（支付表格）

$result = $client->doTransactionBackground([
    'gatewayUrl' => 'https://pay-accept.bm.pl',
    '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（即时交易通知）处理

BlueMedia服务在完成支付后，会将支付状态消息发送到先前配置的ITN地址。数据以XML格式发送，并额外进行了base64编码。SDK提供了doItnIn方法，该方法在接收到BlueMedia服务的数据后，返回一个准备好的对象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://pay-accept.bm.pl');

return $result->getData();

获取支付渠道列表

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

$result = $this->client->getPaywayList('https://pay-accept.bm.pl');

return $result->getData();