README

PHP SDK 用于 Braspag Pagador API 和 Card Protected API

要求

PHP >= 8.0

描述

PHP SDK 用于 Braspag Pagador API.

安装

通过 Composer

composer require vitorccs/braspag-pagador-php-sdk

参数

* 仅当使用 Card Protected API 时必填

可以通过环境变量定义

# Em um arquivo .env do seu projeto:
BRASPAG_MERCHANT_ID=myMerchantId
BRASPAG_MERCHANT_KEY=myMerchantKey
BRASPAG_CLIENT_ID=myClientId
BRASPAG_CLIENT_SECRET=myClientSecret
BRASPAG_SANDBOX=true

# Os serviços captarão automaticamente
$saleService = new \Braspag\SaleService();
$cardService = new \Braspag\CardService();

或作为服务参数传递

# Para serviços da API Pagador
$parameters = new \Braspag\Entities\Pagador\Parameters(
    'myMerchantId',
    'myMerchantKey', 
    true // modo sandbox
);
$saleService = new \Braspag\SaleService($parameters);

# Para serviços da API Cartão Protegido
$parameters = new \Braspag\Entities\CartaoProtegido\Parameters(
    'myMerchantId',
    'myClientId'
    'myClientSecret', 
    true // modo sandbox
);
$cardService = new \Braspag\CardService($parameters);

实现的服务

API Pagador - 交易

$saleService = new \Braspag\SaleService();

创建交易（适用于任何支付方式）

// Nota: utilize preferencialmente os Sales Builder (descrito mais
// abaixo na documentação) para gerar o parâmetro $sale
$response = $saleService->create($sale);

撤销交易（适用于任何支付方式）

// importante: amount deve ser em centavos e tipo inteiro
$response = $saleService->refund($paymentId, $amount);

API Pagador - 查询

$queryService = new \Braspag\QueryService();

通过 Payment ID（支付 ID）获取交易

$response = $queryService->getByPaymentId($paymentId);

通过 Merchant Order Id（商户订单 ID）获取交易

$response = $queryService->getByMerchantOrderId($merchantOrderId);

通过 Recurrent Payment ID（周期性支付 ID）获取交易

$response = $queryService->getByRecurrentPaymentId($recurrentPaymentId);

Card Protected API

$cardService = new \Braspag\CardService($parameters);

为信用卡生成 Token

// Nota: utilize preferencialmente o CardBuilder (descrito mais
// abaixo na documentação) para gerar o parâmetro $card
$response = $cardService->createToken($card);

获取与 Alias 关联的 Token

$response = $cardService->getTokenByAlias($alias);

通过 Token 获取卡数据

$response = $cardService->getCardByToken($token);

挂起 Token

$response = $cardService->suspendToken($token);

恢复 Token

$response = $cardService->unsuspendToken($token);

删除 Token

$response = $cardService->removeToken($token);

构建器（Builders）

为了辅助创建交易，提供了一些构建器

API Pagador - 创建地址

use Braspag\Builders\Pagador\AddressBuilder;

$address = AddressBuilder::create()
    ->setZipCode('06455-030')
    ->setStreet('Alameda Xingu')
    ->setNumber(512)
    ->setComplement('21o andar')
    ->setDistrict('Barueri')
    ->setState('SP')
    ->setCity('São Paulo')
    ->get();

API Pagador - 创建客户

use Braspag\Builders\Pagador\CustomerBuilder;

// Somente Nome é obrigatório para todos os Meios de Pagamento
$customer = CustomerBuilder::create('Nome Cliente')
    ->setIdentity('01.027.058/0001-91')
    ->setEmail('email@email.com')
    ->setBirthdate('2000-01-01')
    ->setAddress($address)
    ->setIpAddress('64.111.123.211')
    ->get();

API Pagador - 创建 PIX 支付

use Braspag\Builders\Pagador\Sales\PixSaleBuilder;

$amount = 1000; // 10.00
$pixSale = PixSaleBuilder::create(Providers::CIELO, $amount)
    ->withCustomer($customer)
    ->withMerchantOrderId('000000006')
    ->setQrCodeExpiration(8200)
    ->get();

API Pagador - 创建银行汇票支付

use Braspag\Builders\Pagador\Sales\BoletoSaleBuilder;

$amount = 1000; // 10.00
$boletoSale = BoletoSaleBuilder::create(Providers::CIELO, $amount)
    ->withCustomer($customer)
    ->withMerchantOrderId('000000006')
    ->setAssignor('Nome do Cedente')
    ->setExpirationDate('2022-11-20')
    ->get();

API Pagador - 创建信用卡支付

use Braspag\Builders\Pagador\Cards\CreditCardBuilder;
use Braspag\Builders\Pagador\Sales\CreditCardSaleBuilder;

// primeiro, criamos o cartão
$creditCard = CreditCardBuilder::create()
    ->setCardNumber('4324017527053834')
    ->setBrand('Visa')
    ->setHolder($customer->Name)
    ->setExpirationDate('09/2030')
    ->setSecurityCode(333)
    ->setSaveCard(true)
    ->get();

// depois criamos a venda
$amount = 1000; // 10.00
$creditCardSale = CreditCardSaleBuilder::create(Providers::SIMULADO, $amount)
    ->withCustomer($customer)
    ->withMerchantOrderId('000000007')
    ->withCreditCard($creditCard)
    ->withCustomerAddress($address)
    ->withCustomerDeliveryAddress($address)
    ->get();

API Pagador - 创建借记卡支付

use Braspag\Builders\Pagador\Cards\DebitCardBuilder;
use Braspag\Builders\Pagador\Sales\DebitCardSaleBuilder;

$debitCard = DebitCardBuilder::create()
    ->setCardNumber('4324017527053834')
    ->setBrand('Visa')
    ->setHolder($customer->Name)
    ->setExpirationDate('09/2030')
    ->setSecurityCode(333)
    ->setSaveCard(true)
    ->get();

$amount = 1000; // 10.00
$debitCardSale = DebitCardSaleBuilder::create(Providers::SIMULADO, $amount)
    ->withCustomer($customer)
    ->withMerchantOrderId($merchantOrderId)
    ->withDebitCard($debitCard)
    ->setReturnUrl('https://www.myreturnurl.com/path')
    ->get();

Card Protected API - 创建信用卡

use Braspag\Builders\CartaoProtegido\CardBuilder;

$card = CardBuilder::create()
    ->setCardNumber('4551870000000183')
    ->setHolder('Joao da Silva')
    ->setAlias('meu_alias')
    ->setExpirationDate('12/2025')
    ->setSecurityCode('123')
    ->get();

错误处理

此库抛出以下异常

主要

BraspagValidationException 对于失败的请求（HTTP 4xx 或 5xx）并返回 API Braspag 的错误消息。
BraspagRequestException 对于失败的请求（HTTP 4xx 或 5xx）没有错误处理或各种连接问题（没有 HTTP 响应）。

在创建交易服务中

BraspagProviderException 对于尽管返回成功（HTTP 2xx），但响应体指示 Provider 返回错误的情况（状态 = 0）。

在查询交易服务中

BraspagNotFoundException 当尝试定位不存在的交易时（例如，通过 PaymentId 或 MerchantOrderId）。

响应体示例，其中将抛出 BraspagProviderException 异常

{
  ...
  "Payment": {
    ...
    "Status": 0,
    "ProviderReturnMessage": "ERRO AO REALIZAR OPERACAO",
    ...
  }
}

响应体示例，其中将抛出 BraspagValidationException 异常

[
    {
        "Code": 133,
        "Message": "Provider is not supported for this Payment Type"
    }
]

实现示例

error_reporting(E_ALL);
ini_set('display_errors', 1);

require __DIR__.'/vendor/autoload.php';

putenv('BRASPAG_MERCHANT_ID=myMerchantId');
putenv('BRASPAG_MERCHANT_KEY=myMerchantKey');
putenv('BRASPAG_SANDBOX=true');

use Braspag\Builders\Pagador\CustomerBuilder;
use Braspag\Builders\Pagador\Sales\PixSaleBuilder;
use Braspag\Enum\Providers;
use Braspag\Exceptions\BraspagProviderException;
use Braspag\Exceptions\BraspagRequestException;
use Braspag\Exceptions\BraspagValidationException;
use Braspag\SaleService;
use Braspag\QueryService;

try {
    $saleService = new SaleService();
    $queryService = new QueryService();

    // CRIANDO TRANSAÇÃO
    $customer = CustomerBuilder::create('Nome Cliente')
        ->setIdentity('01.027.058/0001-91')
        ->get();
        
    $pixSale = PixSaleBuilder::create(Providers::BRADESCO2, 20)
        ->withCustomer($customer)
        ->withMerchantOrderId('000000006')
        ->get();
        
    $checkSuccess = true;  // Habilitar BraspagProviderException
    $response = $saleService->create($pixSale, $checkSuccess);
    print_r($response);
    
    // CONSULTANDO UMA TRANSAÇÃO
    $response = $queryService->getByPaymentId('47f59f6c-d649-4d10-a8a5-104eca634ff2');
    print_r($response);

} catch (BraspagProviderException $e) { // erros de Provider
    echo sprintf('Provider: %s (Payment Status: %s)', $e->getMessage(), $e->getErrorCode());
    // NOTA: em erros de Provider, a Braspag irá criar a Transação normalmente
    // Caso queira capturar o corpo da reposta, utilize o método abaixo:
    $response = $e->getResponseData();
    
} catch (BraspagValidationException $e) { // erros de Validação da API
    echo sprintf('Validation: %s (Code: %s)', $e->getMessage(), $e->getErrorCode());

} catch (BraspagRequestException $e) { // demais erros não tratados (HTTP 4xx e 5xx)
    echo sprintf('Request: %s (HTTP Status: %s)', $e->getMessage(), $e->getErrorCode());

} catch (\Exception $e) { // demais erros
    echo $e->getMessage();
}

测试

如果想要贡献，请实现 PHPUnit 的单元测试。

执行

composer test

vitorccs / braspag-pagador-php-sdk

维护者

详细信息