README

SDK em PHP para API Braspag Pagador e API Cartão Protegido

Requisitos

PHP >= 8.0

Descrição

Instalação

Via Composer

composer require vitorccs/braspag-pagador-php-sdk

Parâmetros

* Obrigatório apenas se for utilizar a API Cartão Protegido

Podem ser definidos por variáveis de ambiente:

# 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();

Ou passados como argumentos do serviço:

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

Serviços implementados

API Pagador - Transação

$saleService = new \Braspag\SaleService();

Criar Transação (para qualquer Meio de Pagamento)

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

Estornar Transação (para qualquer Meio de Pagamento)

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

API Pagador - Consultas

$queryService = new \Braspag\QueryService();

Obter Transação por Payment ID (ID de Pagamento)

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

Obter Transação por Merchant Order Id (Identificador da Loja)

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

Obter Transação por Recurrent Payment ID (ID de Pagamento Recorrente)

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

API Cartão Protegido

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

Gerar um Token para um Cartão de Crédito

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

Obter o Token que está associado ao Alias

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

Obter os dados do Cartão pelo seu Token

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

Suspender o Token

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

Reativar o Token

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

Remover o Token

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

Construtores (Builders)

Para auxiliar a criar uma Transação, foram disponibilizados alguns construtores:

API Pagador - Criando Endereço

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 - Criando Cliente

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 - Criando Pagamento PIX

use Braspag\Builders\Pagador\Sales\PixSaleBuilder;

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

API Pagador - Criando Pagamento Boleto Bancário

use Braspag\Builders\Pagador\Sales\BoletoSaleBuilder;

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

API Pagador - Criando Pagamento Cartão de Crédito

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 - Criando Pagamento Cartão de Débito

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

API Cartão Protegido - Criando Cartão de Crédito

use Braspag\Builders\CartaoProtegido\CardBuilder;

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

Tratamento de erros

Esta biblioteca lança as exceções abaixo:

Principais:

BraspagValidationException para requisições que falharam (HTTP 4xx ou 5xx) e possuem mensagem de erro retornado pela API Braspag.
BraspagRequestException para requisições que falharam (HTTP 4xx ou 5xx) sem tratamento de erro ou problemas de conexão diversos (sem resposta HTTP).

No serviço de Criar Transação:

BraspagProviderException para requisições que embora tenham retornado como sucesso (HTTP 2xx), o corpo da resposta indica um erro retornado pelo Provider Status = 0.

No serviço de Consultar Transação:

BraspagNotFoundException ao tentar localizar uma Transação que não existe (ex: localizar por PaymentId ou MerchantOrderId).

Exemplo de corpo da resposta onde será lançado uma exceção BraspagProviderException

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

Exemplo de corpo da resposta onde será lançado uma exceção BraspagValidationException

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

Exemplo de implementação

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();
}

Testes

Caso queira contribuir, por favor, implementar testes de unidade em PHPUnit.

Para executar:

composer test

vitorccs / braspag-pagador-php-sdk

Maintainers

Details