README

实现 Bancard vPOS 和 Bancard VentasQR 产品的库。

安装

依赖关系

PHP >= 8.0

通过 composer

composer require hds-solutions/bancard-sdk

用法

要设置您的 Bancard 凭证，请使用 Bancard::credentials() 方法。

use HDSSolutions\Bancard\Bancard;

Bancard::credentials(
    publicKey:  'YOUR_PUBLIC_KEY',
    privateKey: 'YOUR_PRIVATE_KEY',
);

库默认使用 staging 环境。要切换到 production 环境，请使用 Bancard::useProduction() 方法。

Bancard::useProduction();

此方法还可以接收一个布尔参数。例如，在 Laravel 中，您可以动态匹配您的环境

Bancard::useProduction(config('app.env') === 'production');

请求和响应对象功能

请求和响应对象有一些辅助方法

use HDSSolutions\Bancard\Bancard;

$response = Bancard::single_buy(...);

// this method returns true only if status == 'success'
if ( !$response->wasSuccess()) {
    // you can access the messages array received from Bancard
    foreach($response->getMessages() as $bancardMessage) {
        echo sprintf('Error: %s, Level: %s => %s',
            $bancardMessage->key,
            $bancardMessage->level,
            $bancardMessage->description);
    }
}

// this method returns the HTTP status code of the response
if ($response->getStatusCode() === 201) {
    // ...
}

// also, you can to access the raw body received
print_r($response->getBody()->getContents());

// you can access to the original request made
$request = $response->getRequest();
// and vice versa
$response = $request->getResponse();

// on the request object you also have access to the raw body sent
print_r($request->getBody()->getContents());

vPOS

单次购买
单次购买 Zimple
新卡
用户卡
删除卡
充电
确认
预授权确认
回滚

单次购买

用于生成调用 Bancard <iframe> 进行一次性支付的进程 ID 的端点。

use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Currency;

$singleBuyResponse = Bancard::single_buy(
    shop_process_id: $shop_process_id,
    amount:          $amount,
    description:     'Payment description',
    currency:        Currency::Guarani,
    return_url:      'https:///your-success-callback-path',
    cancel_url:      'https:///your-cancelled-callback-path',
);

if ( !$singleBuyResponse->wasSuccess()) {
    // show messages or something ... 
    $singleBuyResponse->getMessages();
}

// access the generated process ID to call the Bancard <iframe>
$process_id = $singleBuyResponse->getProcessId();

单次购买 Zimple

与上述相同，但用于 Zimple 支付。

use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Currency;

$singleBuyResponse = Bancard::single_buy_zimple(
    shop_process_id: $shop_process_id,
    amount:          $amount,
    description:     'Payment description',
    currency:        Currency::Guarani,
    phone_no:        $phone_no, // this field is automatically send on the additional_data property of the request
    return_url:      'https:///your-success-callback-path',
    cancel_url:      'https:///your-cancelled-callback-path',
);

可定制的请求

如果您需要，可以创建一个挂起的请求并在运行时更改其值。这适用于所有可用的请求。

use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Currency;

$singleBuyRequest = Bancard::newSingleBuyRequest(
    shop_process_id: $shop_process_id,
    amount:          $amount,
    description:     'Payment description',
    currency:        Currency::Guarani,
    return_url:      'https:///your-success-callback-path',
    cancel_url:      'https:///your-cancelled-callback-path',
);
// for example, enable Zimple flag for this request
$singleBuyRequest->enableZimple();
// for Zimple, you need to specify the user's phone number on the additional data property
$singleBuyRequest->setAdditionalData($phone_no);

// after building the request, you can call the execute() method to send the request to Bancard
if ( !$singleBuyRequest->execute()) {
    // if failed, you can access the response, and messages, ...
    $singleBuyRequest->getResponse()->getMessages();
}

新卡

用于生成调用 Bancard <iframe> 进行卡注册的进程 ID 的端点。

use HDSSolutions\Bancard\Bancard;

$cardsNewResponse = Bancard::card_new(
    user_id:    $user_id,
    card_id:    $card_id,
    phone_no:   $user_phone,
    email:      $user_email,
    return_url: 'https:///your-callback-path',
);

// access the generated process ID to call the Bancard <iframe>
$cardsNewResponse->getProcessId();

用户卡

用于获取已注册用户卡的端点。

use HDSSolutions\Bancard\Bancard;

$usersCardsResponse = Bancard::users_cards(
    user_id: $user_id,
));

// access the user cards
foreach ($usersCardsResponse->getCards() as $card) {
    echo sprintf('Brand: %s, Number: %s, Type: %s, Expiration Date: %s',
        $card->card_brand,
        $card->card_masked_number,
        $card->card_type,
        $card->expiration_date);
}

删除卡

用于删除已注册卡的端点。您需要从之前的请求中获得的 Card 模型实例。

use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Card;

$cardDeleteResponse = Bancard::card_delete(
    card: $card,
);

充电

用于使用已注册用户卡进行支付的端点。您需要从 Bancard::users_cards() 获得的 Card 模型实例。

use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Card;
use HDSSolutions\Bancard\Models\Confirmation;

$chargeResponse = Bancard::charge(
    card:            $card,
    shop_process_id: $shop_process_id,
    amount:          $amount,
    currency:        Currency::Guarani,
    description:     'Charge payment description',
));

if ( !$chargeResponse->wasSuccess()) {
    // show messages or something ... 
    $chargeResponse->getMessages();
}

// access to change Confirmation data
$confirmation = $chargeResponse->getConfirmation();
echo sprintf('Ticket No: %u, Authorization ID: %u',
    $confirmation->ticket_number,
    $confirmation->authorization_number);

// also access to the security information data
$securityInformation = $confirmation->getSecurityInformation();
echo sprintf('Country: %s, Risk Index: %.2F',
    $securityInformation->card_country,
    $securityInformation->risk_index);

确认

用于获取支付确认的端点。例如，如果上述充电请求保持为待确认支付。

use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\Confirmation;

$confirmationResponse = Bancard::confirmation(
    shop_process_id: $chargeResponse->getRequest()->getShopProcessId(),
);

回滚

用于回滚支付的端点。

use HDSSolutions\Bancard\Bancard;

$rollbackResponse = Bancard::rollback(
    shop_process_id: $chargeResponse->getRequest()->getShopProcessId(),
);

VentasQR

生成 QR
撤销 QR

商业代码 & 分支代码

为了使用 VentasQR，您需要通过 Bancard::qr_credentials() 方法设置您的凭证。

⚠ 重要：VentasQR 不由 Bancard::useProduction() 范围，因为您分配的域将定义您的测试/生产环境.

use HDSSolutions\Bancard\Bancard;

Bancard::qr_credentials(
    serviceUrl:     'YOUR_QR_ASSIGNED_DOMAIN',
    publicKey:      'YOUR_QR_PUBLIC_KEY',
    privateKey:     'YOUR_QR_PRIVATE_KEY',
    qrCommerceCode: 1234,
    qrBranchCode:   123,
);

生成 QR

请求 QR 支付的端点。

use HDSSolutions\Bancard\Bancard;
use HDSSolutions\Bancard\Models\QRExpress;

$qrGenerateResponse = Bancard::qr_generate(
    amount:      $amount,
    description: 'Payment description',
);

if ( !$qrGenerateResponse->wasSuccess()) {
    // show messages or something ...
    $qrGenerateResponse->getMessages();
}

// access the generated QR data
$qrExpress = $qrGenerateResponse->getQRExpress();
echo sprintf('QR Payment ID: %s, QR Image url: %s, QR Data: %s',
    $qrExpress->hook_alias,
    $qrExpress->url,
    $qrExpress->qr_data);

// access the list of supported clients
$supportedClients = $qrGenerateResponse->getSupportedClients();
foreach ($supportedClients as $supportedClient) {
    echo sprintf('Client name: %s, Client Logo url: %s',
        $supportedClient->name,
        $supportedClient->logo_url);
}

撤销 QR

撤销 QR 支付的端点。

use HDSSolutions\Bancard\Bancard;

$qrRevertResponse = Bancard::qr_revert(
    hook_alias: $qrExpress->hook_alias,
);

安全漏洞

如果您遇到任何与安全相关的问题，请随时在问题跟踪器上提交工单。

贡献

欢迎贡献！如果您发现任何问题或希望添加新功能或改进，请随时提交拉取请求。

贡献者

Hermann D. Schimpf

许可证

此库是开源软件，根据 GPL-3.0 许可证许可。请参阅许可证文件了解更多信息。

hds-solutions / bancard-sdk

维护者

详细信息