Uma solução simples para integrar a sua aplicação Laravel com a API PIX do Banco Central do Brasil

• Instalação
  • Publicando os assets
  • Publicando o arquivo de configuração
• Endpoints
• Configurações iniciais
  • Obtendo o token de acesso
  • Configurando PSPs
• Cob
  • Criando uma cobrança imediata
  • Revisando uma cobrança imediata
  • Consultando uma cobrança imediata
  • Criar cobranças imediatas sem transactionId
  • Consultando lista de cobranças imediatas
• CobV
  • Criando uma cobrança com vencimento
  • Revisando cobranças com vencimento
  • Consultando uma cobrança com vencimento
  • Consultar lista de cobranças com vencimento
• LoteCobV
  • Criando cobranças com vencimento em lote
  • Revisando lotes de cobranças com vencimento
  • Consultar lote de cobrança com vecimento
  • Consultar lista de lotes de cobrança com vencimento
• Payload Location
  • Criar location do payload
  • Consultar locations cadastradas
  • Recuperar location do payload
  • Desvincular uma cobrança de um location
• Pix recebidos
  • Consultar um pix recebido
  • Consultar lista de pix recebidos
  • Solicitar devolução de um pix
  • Consultar uma devolução de pix
• Webhooks
  • Configurar o webhook pix
  • Exibir informações sobre o webhook pix
  • Cancelar o webhook pix
  • Consutlar webhooks cadastrados

Este pacote oferece integração completa com a API PIX do banco central do Brasil.

Instalação

Você pode instalar este pacote utilizando o composer:

composer require mateusjunges/laravel-pix

Agora, é necessário publicar os assets utilizados e o arquivo de configuração do pacote.

Publicando os assets

Para publicar os assets deste pacote para a pasta public do seu projeto, utilize o comando

php artisan vendor:publish --tag=laravel-pix-assets

Publicando o arquivo de configuração

Para publicar o arquivo de configuração, execute o comando abaixo:

php artisan vendor:publish --tag=laravel-pix-config

Este comando vai copiar o arquivo laravel-pix.php para sua pasta config, com o seguinte conteúdo:

<?php

return [

    'transaction_currency_code' => 986,

    'country_code' => 'BR',

    /*
     | O PIX precisa definir seu GUI (Global Unique Identifier) para ser utilizado.
     */
    'gui' => 'br.gov.bcb.pix',

    'country_phone_prefix' => '+55',

    /*
     * Tamanho do QR code quer será gerado pelo gerador implementado no pacote, em pixels.
     */
    'qr_code_size' => 200,

    /*
     * Você pode definir um middleware para proteger a rota disponibilizada para gerar QR codes.
     * O nome registrado para este middleware precisa ser definido aqui.
     */
    'create_qr_code_route_middleware' => '',

     /*
     * Informações do Prestador de serviço de pagamento (PSP) que você está utilizando.
     * Você pode utilizar vários psps com este pacote, bastando adicionar um novo array com configurações.
     * base_url: URL base da API do seu PSP.
     * oauth_bearer_token: Você pode definir o seu Token
     */
    'psp' => [
        'default' => [
            'base_url'             => env('LARAVEL_PIX_PSP_BASE_URL'),
            'oauth_token_url'      => env('LARAVEL_PIX_PSP_OAUTH_URL', false),
            'oauth_bearer_token'   => env('LARAVEL_PIX_OAUTH2_BEARER_TOKEN'),
            'ssl_certificate'      => env('LARAVEL_PIX_PSP_SSL_CERTIFICATE'),
            'client_secret'        => env('LARAVEL_PIX_PSP_CLIENT_SECRET'),
            'client_id'            => env('LARAVEL_PIX_PSP_CLIENT_ID'),
            'authentication_class' => \Junges\Pix\Api\Contracts\AuthenticatesPSPs::class
        ]
    ],
];

Endpoints

Os endpoints disponibilizados por este pacote são os mesmos implementados pelo Banco Central, e documentados aqui. Entretanto, o seu provedor de serviços de pagamento (PSP) pode não implementar todos eles.

A lista de endpoints completa está descrita aqui:

• Cob (Reúne endpoints destinados a lidar com gerenciamento de cobranças imediatas)

  • PUT /cob/{txid}: Cria uma cobrança imediata.
  • PATCH /cob/{txid}: Revisar uma cobrança imediata.
  • GET /cob/{txid}: Consultar uma cobrança imediata.
  • POST /cob: Cria uma cobrança imediata com id de transação definido pelo PSP.
  • GET /cob: Consultar lista de cobranças imediatas.

• CobV (Reúne endpoints destinados a lidar com gerenciamento de cobranças com vencimento.)

  • PUT /cobv/{txid}: Cria uma cobrança com vencimento.
  • PATCH /cobv/{txid}: Revisar uma cobrança com vencimento.
  • GET /cobv/{txid}: Consultar uma cobrança com vencimento.
  • GET /cobv: Consultar lista de cobranças com vencimento.

• LoteCobV (Reúne endpoints destinados a lidar com gerenciamento de cobranças com vencimento em lote.)

  • PUT /lotecobv/{id}: Criar/Alterar lote de cobranças com vencimento.
  • PATCH /lotecobv/{id}: Utilizado para revisar cobranças específicas dentro de um lote de cobranças com vencimento.
  • GET /lotecobv/{id}: Utilizado para consultar um lote específico de cobranças com vencimento.
  • GET /lotecobv: Consultar lotes de cobranças com vencimento.

• PayloadLocation (Reúne endpoints destinados a lidar com configuração e remoção de locations para uso dos payloads)

  • POST /loc: Criar location do payload.
  • GET /loc: Consultar locations cadastradas.
  • GET /loc/{id}: Recuperar location do payload.
  • DELETE /loc/{id}/{txid}: Desvincular uma cobrança de uma location.

• Pix (Reúne endpoints destinados a lidar com gerenciamento de Pix recebidos.)

  • GET /pix/{e2eid}: Consultar Pix.
  • GET /pix: Consultar pix recebidos.
  • PUT /pix/{e2eid}/devolucao/{id}: Solicitar devolucão.
  • GET /pix/{e2eid}/devolucao/{id}: Consultar devolução.

• Webhook (Reúne endpoints para gerenciamento de notificações por parte do PSP recebedor ao usuário recebedor.)

  • PUT /webhook/{chave}: Configurar o webhook pix.
  • GET /webhook/{chave}: Exibir informações acerca do webhook pix.
  • DELETE /webhook/{chave}: Cancelar o webhook pix.
  • GET /webhook: Consultar webhooks cadastrados.

Configurações iniciais.

Para iniciar a utilização da API Pix, você precisa autenticar com o seu PSP via OAuth. Para isso, é necessário informar o seu client_id e client_secret, disponibilizados pelo seu PSP. Isso deve ser feito no arquivo .env de sua aplicação:

LARAVEL_PIX_PSP_CLIENT_SECRET="seu client_secret aqui"
LARAVEL_PIX_PSP_CLIENT_ID="seu client_id aqui"

Vários PSP que disponibilizam a API Pix possuem uma URL para obtenção do token de acesso diferente da URL para a API. Portanto, você precisa configurar as duas URLs no seu .env:

LARAVEL_PIX_PSP_OAUTH_URL="url para obtenção do access token"
LARAVEL_PIX_PSP_BASE_URL="url da api pix"

Agora, todas as chamadas a API Pix utilizarão estas credencias, e você não precisa informar manualmente para cada requisição. Entretando, se por algum motivo você desejar alterar estas credenciais em tempo de execução, é possível através dos métodos ->clientId() e ->clientSecret(), disponibilizados em todos os endpoints neste pacote. Um exemplo é mostrado abaixo:

use Junges\Pix\Pix;

$api = Pix::api()
    ->clientId('client_id')
    ->clientSecret('client_secret');

Estes métodos estão disponíveis em todos os recursos da api Pix: cob, cobv, loteCobv, payloadLocation, receivedPix e webhook.

Obtendo o token de acesso

Este pacote disponibiliza uma implementação de autenticação geral, que pode ser utilizada da seguinte forma:

use Junges\Pix\Pix;

// Se você já informou o seu client_id e client_secret no .env, não é necessário informar nesta requisição.
$token = Pix::api()->getOauth2Token()->json();

Alguns PSPs requerem a verificação de um certificado disponibilizado no momento da criação de sua aplicação. Este certificado pode ser informado no .env, ou informado na requisição através do método certificate(), e será carregado automaticamente na api.

use Junges\Pix\Pix;

// Se você já informou o seu client_id e client_secret no .env, não é necessário informar nesta requisição.
$token = Pix::api()->certificate('path/to/certificate')->getOauth2Token()->json();

Caso os endpoints do PSP utilizado necessitem da verificação deste certificado, você precisa informar este pacote para fazer esta verificação. Isto pode ser feito através do AppServiceProvider da sua aplicação, bastando adicionar esta linha ao método register:

use Junges\Pix\LaravelPix;

public function register()
{
    LaravelPix::validatingSslCertificate();
}

Agora, todas as chamadas aos endpoints da API Pix farão a verificação com o certificado informado.

Caso a classe de autenticação disponibilizada por este pacote não funcione para obter o access token no seu PSP, você pode criar sua própria implementação, bastando criar uma classe e extender a class Junges\Pix\Api\Auth:

<?php

namespace App\Pix;

use Junges\Pix\Api\Auth;

class CustomAuthentication extends Auth
{
    public function getToken(string $scopes = null)
    {
        // Metodo para retornar o token de acesso
    }
    
    public function getOauthEndpoint() : string{
        // Retorna o endpoint que deve ser utilizado para autenticação. 
        // Você precisa informar a URL completa.
    }
}

Agora, é necessário informar este pacote para utilizar a sua classe para obtenção do token de acesso. Você pode fazer isso através do AppServiceProvider da sua aplicação:

public function boot()
{
    \Junges\Pix\LaravelPix::authenticatesUsing(CustomAuthentication::class);
}

Agora, sua classe de autenticação com sua própria lógica será utilizada para obter o token de acesso, e o método getOAuthToken() retorna o conteúdo retornado pelo método getToken desta classe.

É possível configurar uma classe de autenticação para cada PSP.

Configurando PSPs

Se você possui integrações com mais de um psp, você pode configurar os parâmetros individuais para cara um no arquivo de configurações deste pacote, em config/laravel-pix.php.

O PSP default utilizado pelo pacote está definido na key default, do array de PSPs. Você pode alterar o PSP padrão através do método useAsDefaultPsp(), no seu service provider:

public function boot()
{
    \Junges\Pix\LaravelPix::useAsDefaultPsp('your-default-psp-here');
}

Para alterar o PSP em tempo de execução, você deve utilizar o método usingPsp(), disponível em todos os endpoints implementados neste pacote:

\Junges\Pix\Pix::cob()->usingPsp('your-psp-here');
\Junges\Pix\Pix::cobv()->usingPsp('your-psp-here');
\Junges\Pix\Pix::loteCobv()->usingPsp('your-psp-here');
\Junges\Pix\Pix::payloadLocation()->usingPsp('your-psp-here');
\Junges\Pix\Pix::receivedPix()->usingPsp('your-psp-here');
\Junges\Pix\Pix::webhook()->usingPsp('your-psp-here');

Cob

O Cob reúne os endpoints relacionados a criação de cobranças instantâneas.

Consulte a documentação oficial do banco central para informações sobre o request a ser enviado para cada endpoint, disponível neste link.

Para utilizar os endpoints do cob, utilize o método cob(), da class Junges\Pix\Pix:

$cob = \Junges\Pix\Pix::cob();

Criando um cob

Para criar uma cobrança instantânea, é necessário utilizar a api cob, disponibilizada pela classe Pix, neste pacote.

use Junges\Pix\Pix;

$cob = Pix::cob()->create('transactionId', $request)->json();

Revisar uma cobrança imediata

Para revisar uma cobrança imediata, deve ser utilizado o método updateByTransactionId(), informando o id da transação a ser atualizada e os dados para atualização.

use Junges\Pix\Pix;

$updateCob = Pix::cob()->updateByTransactionId('transactionId', $dataToUpdate)->json();

Consultando uma cobrança imediata

Para consultar uma cobrança através de um determinado id de transação, você deve utilizar o método getByTransactionId, informando o id da transação como parâmetro:

use Junges\Pix\Pix;

$cob = Pix::cob()->getByTransactionId('transactionId')->json();

Criando cobranças imediatas sem transactionId

Para criar uma cobrança imediata com transactionId definido pelo PSP, utilize o método createWithoutTransactionId(), informando apenas os dados para criação da cobrança, sem a necessidade de passar um id de transação:

use Junges\Pix\Pix;

$cob = Pix::cob()->createWithoutTransactionId($request);

Consultando lista de cobranças imediatas

Para consultar a lista de cobranças imediatas com parâmetros como inicio, fim, status e outros, utilize o método all(), passando os filtros necessários. Os filtros inicio e fim são obrigatórios para toda requisição neste endpoint. Este pacote disponibiliza uma api para aplicação de filtros na requisição, bastando instanciar uma nova classe para os filtros desejados e aplicá-los a requisição com o método withFilters():

use Junges\Pix\Pix;
use Junges\Pix\Api\Filters\CobFilters;

$filters = (new CobFilters())
    ->startingAt(now()->subMonth()->toISOString())
    ->endingAt(now()->addMonth()->toISOString());

$cobs = Pix::cob()->withFilters($filters)->all()->json();

A lista de filtros disponíveis para o endpoint cob é listada aqui:

CobV

O CobV reúne os endpoints destinados a lidar com o gerenciamento de cobranças com vencimento.

A documentação oficial do Banco Central do Brasil sobre os requests a serem enviados para cada endpoint pode ser visualizada aqui

Para utilizar estes endpoints, utilize o método cobv(), da classe Junges\Pix\Pix:

$cobv = \Junges\Pix\Pix::cobv();

Criando cobranças com vencimento

Para criar uma cobrança com vencimento, utilize o método createWithTransactionId:

$cobv = \Junges\Pix\Pix::cobv()->createWithTransactionId('transactionId', $request)->json();

Revisando cobranças com vencimento

Para revisar e atualizar uma cobrança com vencimento, utilize o método updateWithTransactionId:

$cobv = \Junges\Pix\Pix::cobv()->updateWithTransactionId('transactionId', $request)->json();

Consultar uma cobrança com vencimento

Para consultar uma cobrança com vencimento, você pode utilizar o método getByTransactionId, informando o id de transação da cobrança:

$cobv = \Junges\Pix\Pix::cobv()->getByTransactionId('transactionId')->json();

Consultar lista de cobranças com vencimento

Para consultar a lista de cobranças imediatas com vencimento com parâmetros como inicio, fim, status e outros, utilize o método all(), passando os filtros necessários. Os filtros inicio e fim são obrigatórios para todas as requisição neste endpoint. Este pacote disponibiliza uma api para aplicação de filtros na requisição, bastando instanciar uma nova classe para os filtros desejados e aplicá-los a requisição com o método withFilters():

use Junges\Pix\Pix;
use Junges\Pix\Api\Filters\CobvFilters;

$filters = (new CobvFilters())
    ->startingAt(now()->subMonth()->toISOString())
    ->endingAt(now()->addMonth()->toISOString());

$cobs = Pix::cobv()->withFilters($filters)->all()->json();

A lista de filtros disponíveis para o endpoint cobv é listada aqui:

LoteCobV

O loteCobV reúne os endpoints destinados a lidar com o gerenciamento de cobranças com vencimento em lote.

A documentação oficial do Banco Central do Brasil a respeito dos requests que devem ser enviados em cada requisiçao pode se encontrada neste link;

Para utilizar estes endpointes, utilize o método loteCobv(), da classe Junges\Pix\Pix:

$cobv = \Junges\Pix\Pix::loteCobv();

Criando cobrança com vencimento em lote

Para criar cobranças com vencimento em lote utilize o método createBatch(), informando o id do lote e as cobranças que devem ser incluídas:

$batch = \Junges\Pix\Pix::loteCobv()->createBatch('batchId', $request)->json();

Revisar lotes de cobranças com vencimento

Para atualizar dados de um lote de cobranças, utilize o método updateBatch(), informando o id do lote a ser atualizado e os novos dados:

$batch = \Junges\Pix\Pix::loteCobv()->updateBatch('batchIdToUpdate', $request)->json();

Consultar um lote de cobranças com vencimento

Para consultar um lote de cobranças com vencimento, utilize o método getByBatchId(), informando o id do lote que deseja consultar:

$batch = \Junges\Pix\Pix::loteCobv()->getByBatchId('batchId')->json();

Consultar lista de cobranças com vencimento em lote:

Para consultar a lista de cobranças com vencimento em lote com parâmetros como inicio, fim, status e outros, utilize o método all(), passando os filtros necessários. Os filtros inicio e fim são obrigatórios para todas as requisição neste endpoint. Este pacote disponibiliza uma api para aplicação de filtros na requisição, bastando instanciar uma nova classe para os filtros desejados e aplicá-los a requisição com o método withFilters():

use Junges\Pix\Pix;
use Junges\Pix\Api\Filters\LoteCobvFilter;

$filters = (new LoteCobvFilter())
    ->startingAt(now()->subMonth()->toISOString())
    ->endingAt(now()->addMonth()->toISOString());

$batches = Pix::loteCobv()->withFilters($filters)->all()->json();

A lista de filtros disponíveis para o endpoint loteCobv é listada aqui:

Payload Location

O payload location reúne os endpoints destinados a lidar com a configuração e remoção dos locations utilizados nos payloads.

Para utilizar o payload location, utilize o método payloadLocation(), da classe Junges\Pix\Pix:

$payloadLocation = \Junges\Pix\Pix::payloadLocation();

Criar location do payload

Para criar uma location do payload, utilize o método create, passando a location que deseja criar:

$payloadLocation = \Junges\Pix\Pix::payloadLocation()->create('payload-location')->json();

Consultar locations cadastradas

Para consultar a lista de locations cadastrados, com parâmetros como inicio, fim, status e outros, utilize o método all(), passando os filtros necessários. Os filtros inicio e fim são obrigatórios para todas as requisição neste endpoint. Este pacote disponibiliza uma api para aplicação de filtros na requisição, bastando instanciar uma nova classe para os filtros desejados e aplicá-los a requisição com o método withFilters():

use Junges\Pix\Pix;
use Junges\Pix\Api\Filters\PayloadLocationFilters;

$filters = (new PayloadLocationFilters())
    ->startingAt(now()->subMonth()->toISOString())
    ->endingAt(now()->addMonth()->toISOString());

$locs = Pix::payloadLocation()->withFilters($filters)->all()->json();

A lista de filtros disponíveis para o endpoint payloadLocation é listada aqui:

Recuperar location do

Para consultar a location de um payload, você deve utilizar o método getById():

$payloadLocation = \Junges\Pix\Pix::payloadLocation()->getById('payload-location-id')->json();

Desvincular uma cobrança de uma location

Para desvincular uma cobrança de uma location, você deve utilizar o método detachChargeFromLocation(), informando o id da location:

$detach = \Junges\Pix\Pix::payloadLocation()->detachChargeFromLocation('payload-location-id')->json();

ecutado com sucesso, a entidade loc não apresentará mais um transaction_id, se apresentava anteriormente à chamada. Adicionalmente, a entidade cob ou cobv associada ao txid desvinculado também passará a não mais apresentar um location. Esta operação não altera o status da cob ou cobv em questão.

Pix recebidos

Este método reúne endpoints destinados a lidar com gerenciamento de Pix recebidos.

Para utilizá-lo, utilize o método receivedPix, da classe Junges\Pix\Pix:

$receivedPix = \Junges\Pix\Pix::receivedPix();

Consultar pix

Você pode consultar um pix recebido através do id end to end (e2eid):

$pix = \Junges\Pix\Pix::receivedPix()->getBye2eid('pix-e2eid')->json()

Consultar pix recebidos

Para consultar a lista de todos os pix recebidos, com parâmetros como inicio, fim, status e outros, utilize o método all(), passando os filtros necessários. Os filtros inicio e fim são obrigatórios para todas as requisição neste endpoint. Este pacote disponibiliza uma api para aplicação de filtros na requisição, bastando instanciar uma nova classe para os filtros desejados e aplicá-los a requisição com o método withFilters():

use Junges\Pix\Pix;
use Junges\Pix\Api\Filters\ReceivedPixFilters;

$filters = (new ReceivedPixFilters())
    ->startingAt(now()->subMonth()->toISOString())
    ->endingAt(now()->addMonth()->toISOString());

$pix = Pix::receivedPix()->withFilters($filters)->all()->json();

A lista de filtros disponíveis para o endpoint receivedPix é listada aqui:

Solicitar devolução

Você pode solicitar uma devolução de um pix recebido através do método refund, informando o id e2eid do pix a ser devolvido e um id para a devolução:

$refundPix = \Junges\Pix\Pix::receivedPix()->refund('e2eid', 'refundId')->json();

Consultar devolução

Você pode consultar uma devolução através do id desta devolução e do e2eid do pix:

$refund = \Junges\Pix\Pix::receivedPix()->consultRefund('e2eid', 'refundId')->json();

Webhooks

Reúne endpoints para gerenciamento de notificações por parte do PSP recebedor ao usuário recebedor.

Para gerenciar webhooks, utilize o método webhook, da classe Junges\Pix\Pix:

$webhook = \Junges\Pix\Pix::webhook();

Configurar o webhook pix

Este é o endpoint para configuração do serviço de notificações acerca de Pix recebidos. Somente Pix associados a um txid serão notificados. Para configurar um webhook, você deve utilizar o método create, informando a chave pix e o URL para onde o webhook deve ser enviado:

$webhook = \Junges\Pix\Pix::webhook()->create('pixKey', 'https://url-do-webhook.com')->json();

Exibir informações sobre o webhook pix

Para consultar um webhook, utilize o método getByPixKey, informando a chave pix associada ao webhook:

$webhook = \Junges\Pix\Pix::webhook()->getByPixKey('pixKey')->json();

Cancelar o webhook pix

Para remover um webhook, utilize o método delete, informando a chave pix associada ao webhook:

$webhook = \Junges\Pix\Pix::webhook()->delete('pixKey')->json();

Consultar webhooks cadastrados

Para consultar todos os webhooks cadastrados, utilize o método all:

$webhooks = \Junges\Pix\Pix::webhook()->all()->json();

Também é possível incluir alguns filtros, como inicio, fim e paginação, mas neste endpoint nenhum deles é obritagtório:

use Junges\Pix\Pix;
use Junges\Pix\Api\Filters\WebhookFilters;

$filters = (new WebhookFilters())
    ->startingAt(now()->subMonth()->toISOString())
    ->endingAt(now()->addMonth()->toISOString());

$webhooks = Pix::webhook()->withFilters($filters)->all()->json();

A lista de filtros disponíveis para o endpoint webhook é listada aqui: