PHPackages                             vitorccs/braspag-pagador-php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. vitorccs/braspag-pagador-php-sdk

ActiveLibrary

vitorccs/braspag-pagador-php-sdk
================================

SDK em PHP para API Braspag Pagador

v1.7.0(1y ago)0986GPL-3.0PHPPHP >=8.0

Since Oct 27Pushed 1y ago1 watchersCompare

[ Source](https://github.com/vitorccs/braspag-pagador-php-sdk)[ Packagist](https://packagist.org/packages/vitorccs/braspag-pagador-php-sdk)[ Docs](https://github.com/vitorccs/braspag-pagador-php-sdk)[ RSS](/packages/vitorccs-braspag-pagador-php-sdk/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (7)Dependencies (3)Versions (9)Used By (0)

Braspag Pagador - SDK PHP
=========================

[](#braspag-pagador---sdk-php)

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

Requisitos
----------

[](#requisitos)

- PHP >= 8.0

Descrição
---------

[](#descrição)

SDK em PHP para a [API Braspag Pagador](https://braspag.github.io/manual/braspag-pagador).

Instalação
----------

[](#instalação)

Via Composer

```
composer require vitorccs/braspag-pagador-php-sdk
```

Parâmetros
----------

[](#parâmetros)

ParâmetroObrigatórioPadrãoComentárioBRASPAG\_MERCHANT\_IDSimnullMerchant ID para autenticaçãoBRASPAG\_MERCHANT\_KEYSimnullMerchant Key para autenticaçãoBRASPAG\_CLIENT\_ID\*SimnullClient ID para API Cartão ProtegidoBRASPAG\_CLIENT\_SECRET\*SimnullClient Secret para API Cartão ProtegidoBRASPAG\_SANDBOXNãofalseHabilita o modo SandboxBRASPAG\_TIMEOUTNão30Timeout em segundos para estabelecer conexão com a API*\* 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
----------------------

[](#serviços-implementados)

### API Pagador - Transação

[](#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

[](#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

[](#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)
-----------------------

[](#construtores-builders)

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

### API Pagador - Criando Endereço

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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
-------------------

[](#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](https://braspag.github.io/manual/braspag-pagador#lista-de-status-da-transa%C3%A7%C3%A3o).

**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
------------------------

[](#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
------

[](#testes)

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

Para executar:

```
composer test
```

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance38

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~158 days

Recently: every ~225 days

Total

8

Last Release

551d ago

PHP version history (2 changes)1.0.0PHP >=7.4

v1.5.0PHP >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/2d5d2e771a97ac9dc5a1a1c8a18ec3cf97b5ea7872bfbc0fd62b060545cf6dfa?d=identicon)[vitorccs](/maintainers/vitorccs)

---

Top Contributors

[![vitorccs](https://avatars.githubusercontent.com/u/9891961?v=4)](https://github.com/vitorccs "vitorccs (30 commits)")

---

Tags

braspag-pagadorphpsdkbraspagpagador

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/vitorccs-braspag-pagador-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/vitorccs-braspag-pagador-php-sdk/health.svg)](https://phpackages.com/packages/vitorccs-braspag-pagador-php-sdk)
```

###  Alternatives

[neuron-core/neuron-ai

The PHP Agentic Framework.

1.8k245.3k21](/packages/neuron-core-neuron-ai)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3731.2M42](/packages/tencentcloud-tencentcloud-sdk-php)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)