README

一个简单的方法将您的Laravel应用程序与巴西中央银行的PIX API集成

安装
- 发布资产
- 发布配置文件
端点
初始配置
- 获取访问令牌
- 配置PSPs
Cob
CobV
LoteCobV
有效负载位置
Pix接收
Webhooks
配置端点

本包提供与巴西中央银行PIX API的完整集成。

安装

您可以使用composer安装此包

composer require mateusjunges/laravel-pix

现在，需要发布所使用的资产和包的配置文件。

发布资产

要发布此包的资产到您的项目public文件夹，请使用以下命令

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

发布配置文件

要发布配置文件，请执行以下命令

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

此命令会将laravel-pix.php文件复制到您的config文件夹，内容如下

<?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
        ]
    ],
];

端点

此包提供的端点与中央银行实现的一致，并在此处进行了文档说明。然而，您的支付服务提供商（PSP）可能并未实现所有端点。

完整端点列表在此处描述

Cob（汇集用于处理即时收费管理的端点）
- PUT /cob/{txid}：创建一个即时收费。
- PATCH /cob/{txid}：审查一个即时收费。
- GET /cob/{txid}：查询一个即时收费。
- POST /cob：创建一个由PSP定义交易ID的即时收费。
- GET /cob：查询即时收费列表。
CobV（汇集用于处理有到期日收费管理的端点）
- PUT /cobv/{txid}：创建一个有到期日的收费。
- PATCH /cobv/{txid}：审查一个有到期日的收费。
- GET /cobv/{txid}：查询一个有到期日的收费。
- GET /cobv：查询有到期日的收费列表。
LoteCobV（汇集用于处理批量有到期日收费管理的端点）
- PUT /lotecobv/{id}：创建/修改有到期日收费批次。
- PATCH /lotecobv/{id}：用于在有到期日收费批次中审查特定收费。
- GET /lotecobv/{id}：用于查询特定到期收款批次。
- GET /lotecobv：查询到期收款批次。
PayloadLocation（汇集用于处理payload配置和删除locations的端点）
- POST /loc：创建payload的location。
- GET /loc：查询已注册的locations。
- GET /loc/{id}：获取payload的location。
- DELETE /loc/{id}/{txid}：解绑一个收款与一个location的关系。
Pix（汇集用于处理接收的Pix端点）
- GET /pix/{e2eid}：查询Pix。
- GET /pix：查询接收到的Pix。
- PUT /pix/{e2eid}/devolucao/{id}：请求退款。
- GET /pix/{e2eid}/devolucao/{id}：查询退款。
Webhook（汇集用于管理接收者PSP向接收者用户发送的通知端点）
- PUT /webhook/{chave}：配置Pix webhook。
- GET /webhook/{chave}：显示有关Pix webhook的信息。
- DELETE /webhook/{chave}：取消Pix webhook。
- GET /webhook：查询已注册的webhooks。

初始设置。

为了开始使用Pix API，您需要通过OAuth与您的PSP进行身份验证。为此，您需要提供由您的PSP提供的client_id和client_secret，并在您的应用.env文件中设置。

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

提供Pix API的许多PSP具有不同的URL来获取访问令牌，这与API的URL不同。因此，您需要在您的.env中配置这两个URL。

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

现在，所有对Pix API的调用都将使用这些凭据，并且您不需要在每次请求中手动提供。但是，如果您出于某种原因希望在执行时更改这些凭据，则可以通过此包中所有端点提供的->clientId()和->clientSecret()方法进行，以下是一个示例。

use Junges\Pix\Pix;

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

这些方法在api Pix的所有资源中均可用：cob、cobv、loteCobv、payloadLocation、receivedPix和webhook。

获取访问令牌

此包提供了一种通用的身份验证实现，可以使用以下方式使用：

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

一些PSP在创建应用时要求验证提供的证书。此证书可以在.env中提供，或在请求中通过certificate()方法提供，并将自动加载到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();

如果使用的PSP的端点需要验证此证书，则需要通知此包进行验证。这可以通过添加以下行到register方法中的AppServiceProvider来完成。

use Junges\Pix\LaravelPix;

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

现在，所有对API Pix端点的调用都将使用提供的证书进行验证。

如果此包提供的身份验证类无法在您的PSP中获取访问令牌，则可以创建自己的实现，只需创建一个类并扩展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.
    }
}

现在，需要通知此包以使用您的类来获取访问令牌。您可以通过在应用AppServiceProvider中执行此操作来实现。

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

现在，您的具有自己逻辑的身份验证类将被用于获取访问令牌，并且getOAuthToken()方法返回此类中getToken方法返回的内容。

可以为每个PSP配置身份验证类。

配置PSPs

如果您有多个PSP的集成，您可以在此包的配置文件config/laravel-pix.php中为每个PSP配置单独的参数。

包中默认使用的PSP在PSP数组中的default键中定义。您可以通过在服务提供者中调用useAsDefaultPsp()方法来更改默认的PSP。

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

要实时更改PSP，您必须使用本包中所有端点都提供的usingPsp()方法。

\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

Cob收集与创建即时收款相关的端点。

有关向每个端点发送的请求的信息，请参阅官方银行中央文档，可通过此链接获取。

要使用cob端点，请使用Junges\Pix\Pix类中的cob()方法。

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

创建cob

要创建即时收款，必须使用本包中由Pix类提供的cob API。

use Junges\Pix\Pix;

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

审查即时收款

要审查即时收款，必须使用updateByTransactionId()方法，提供要更新的交易id和更新数据。

use Junges\Pix\Pix;

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

查询一个即时收费

要通过对特定交易id的查询来咨询收款，您必须使用getByTransactionId方法，提供交易id作为参数。

use Junges\Pix\Pix;

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

创建不带`transactionId`的即时收款

要使用由PSP定义的transactionId创建即时收款，请使用createWithoutTransactionId()方法，只需提供创建收款的必要数据，无需传递交易id。

use Junges\Pix\Pix;

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

查询即时收费列表

要使用如开始日期、结束日期、状态和其他参数进行筛选来查询即时收款的列表，请使用all()方法，传递必要的筛选条件。在此端点中的所有请求都必须提供筛选条件开始和结束。此包提供了一个用于在请求中应用筛选器的API，只需实例化一个用于所需筛选器的新类，然后使用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();

在此处列出可用于端点cob的筛选器列表

筛选器	使用方法
开始	`startingAt()`
结束	`endingAt()`
cpf	`cpf()`
cnpj	`cnpj()`
cnpj	`cnpj()`
locationPresente	`withLocationPresent()`或`withoutLocationPresent()`
状态	`withStatus()`
分页：当前页	`currentPage()`
分页：每页项目数	`itemsPerPage()`

CobV

CobV收集处理有到期日的收款的端点。

有关向每个端点发送的请求的巴西中央银行官方文档，请在此处查看。

要使用这些端点，请使用Junges\Pix\Pix类中的cobv()方法。

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

创建有到期日的收款

要创建有到期日的收款，请使用createWithTransactionId方法。

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

审查有到期日的收费

要审查和更新有到期日的收款，请使用updateWithTransactionId方法。

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

查询有到期日的收款

要查询有到期日的收款，您可以使用getByTransactionId方法，提供收款的交易id。

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

查询有到期日的收费列表

要查询具有如开始日期、结束日期、状态和其他参数的有到期日收款的列表，请使用all()方法，传递必要的筛选条件。在此端点中的所有请求都必须提供筛选条件开始和结束。此包提供了一个用于在请求中应用筛选器的API，只需实例化一个用于所需筛选器的新类，然后使用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();

在此处列出可用于端点cobv的筛选器列表

筛选器	使用方法
开始	`startingAt()`
结束	`endingAt()`
cpf	`cpf()`
cnpj	`cnpj()`
cnpj	`cnpj()`
locationPresente	`withLocationPresent()`或`withoutLocationPresent()`
loteCobvId	`cobvBatchId()`
状态	`withStatus()`
分页：当前页	`currentPage()`
分页：每页项目数	`itemsPerPage()`

LoteCobV

loteCobV收集处理有到期日的批量收款的端点。

有关在每个请求中应发送的请求的巴西中央银行官方文档，请在此处找到。

要使用这些端点，请使用类 Junges\Pix\Pix 中的方法 loteCobv()

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

创建批量到期收款

要创建批量到期收款，请使用方法 createBatch()，并指定批次 ID 和要包含的收款

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

审查批量到期收款

要更新一个批量收款的数据，请使用方法 updateBatch()，并指定要更新的批次 ID 和新数据

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

查询批量到期收款

要查询一个批量到期收款，请使用方法 getByBatchId()，并指定要查询的批次 ID

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

查询批量到期收款列表

要查询批量到期收款列表，并带有如开始时间、结束时间、状态等参数，请使用方法 all()，并传递必要的筛选器。在此端点中，筛选器 开始 和 结束 是必需的。此包提供了一种在请求中应用筛选器的 API，只需实例化一个新类以创建所需的筛选器，然后使用方法 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();

此处列出了端点 loteCobv 可用的筛选器列表

筛选器	使用方法
开始	`startingAt()`
结束	`endingAt()`
分页：当前页	`currentPage()`
分页：每页项目数	`itemsPerPage()`

有效负载位置

位置路径汇总了用于处理 payload 中的位置配置和删除的端点。

要使用位置路径，请使用类 Junges\Pix\Pix 中的方法 payloadLocation()

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

创建有效负载位置

要创建一个 payload 位置，请使用方法 create，并传递要创建的位置

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

查询已注册的位置

要查询已注册的位置列表，并带有如开始时间、结束时间、状态等参数，请使用方法 all()，并传递必要的筛选器。在此端点中，筛选器 开始 和 结束 是必需的。此包提供了一种在请求中应用筛选器的 API，只需实例化一个新类以创建所需的筛选器，然后使用方法 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();

此处列出了端点 payloadLocation 可用的筛选器列表

筛选器	使用方法
开始	`startingAt()`
结束	`endingAt()`
txIdPresente	`withTransactionIdPresent()` 或 `withoutTransactionIdPresent`
tipoCob	`withTypeCob()` 或 `withTypeCobv()`
分页：当前页	`currentPage()`
分页：每页项目数	`itemsPerPage()`

恢复位置

要查询一个 payload 的位置，您必须使用方法 getById()

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

解除收款与位置的关联

要解除收款与位置的关联，您必须使用方法 detachChargeFromLocation()，并指定位置 ID

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

执行成功后，实体 loc 将不再具有 transaction_id（如果之前存在），此外，与 txid 解除关联的关联实体 cob 或 cobv 也将不再具有位置。此操作不会更改 cob 或 cobv 的 status。

Pix接收

此方法汇集了用于处理接收到的 Pix 的端点。

要使用它，请使用类 Junges\Pix\Pix 中的方法 receivedPix

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

查询 Pix

您可以通过端到端 ID (e2eid) 查询接收到的 Pix

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

查询接收到的 Pix

要查询所有接收到的 Pix 的列表，并带有如开始时间、结束时间、状态等参数，请使用方法 all()，并传递必要的筛选器。在此端点中，筛选器 开始 和 结束 是必需的。此包提供了一种在请求中应用筛选器的 API，只需实例化一个新类以创建所需的筛选器，然后使用方法 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();

此处列出了端点 receivedPix 可用的筛选器列表

筛选器	使用方法
开始	`startingAt()`
结束	`endingAt()`
txid	`transactionId()`
txIdPresente	`withTransactionIdPresent()` 或 `withoutTransactionIdPresent`
devolucaoPresente	`withRefundPresent()` 或 `withoutRefundPresent()`
cpf	`cpf()`
cnpj	`cnpj()`
分页：当前页	`currentPage()`
分页：每页项目数	`itemsPerPage()`

申请退款

您可以通过refund方法请求退款，并提供要退款的pix的id（e2eid）和退款id。

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

查询退款

您可以通过该退款的id和对应的pix的e2eid来查询退款信息。

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

Webhooks

收集PSP接收方对用户接收方进行通知管理的端点。

为了管理webhook，请使用Junges\Pix\Pix类中的webhook方法。

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

配置Pix webhook

这是关于接收到的Pix服务通知的配置端点。只有与txid关联的Pix才会被通知。要配置webhook，您需要使用create方法，并告知pix键和webhook应发送到的URL。

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

显示Pix webhook信息

要查询webhook，请使用getByPixKey方法，并告知与webhook关联的pix键。

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

取消Pix webhook

要删除webhook，请使用delete方法，并告知与webhook关联的pix键。

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

查询已注册的webhook

要查询所有已注册的webhook，请使用all方法。

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

也可以添加一些过滤器，如开始时间、结束时间和分页，但在此端点中这些都不是必需的。

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

此处列出了可用于webhook端点的所有过滤器。

筛选器	使用方法
开始	`startingAt()`
结束	`endingAt()`
分页：当前页	`currentPage()`
分页：每页项目数	`itemsPerPage()`

配置端点

为了为每个PSP配置特定的端点，您需要为每个不遵循BACEN公约的PSP创建一个EndpointResolver。要创建一个端点解析器，创建一个具有所需名称的类并实现CanResolveEndpoints接口，或者简单地扩展本包中可用的Endpoints类。它提供了所需的端点，您可以将端点数组复制过来并根据您的PSP进行修改。

    public array $endpoints = [
        self::OAUTH_TOKEN  => '/oauth/token',
        self::CREATE_COB   => '/cob/',
        self::GET_COB      => '/cob/',
        self::UPDATE_COB   => '/cob/',
        self::GET_ALL_COBS => '/cob/',

        self::CREATE_COBV  => '/cobv/',
        self::GET_COBV     => '/cobv/',
        self::GET_ALL_COBV => '/cobv/',

        self::CREATE_LOTE_COBV  => '/lotecobv/',
        self::UPDATE_LOTE_COBV  => '/lotecobv/',
        self::GET_LOTE_COBV     => '/lotecobv/',
        self::GET_ALL_LOTE_COBV => '/lotecobv/',

        self::CREATE_WEBHOOK => '/webhook/',
        self::GET_WEBHOOK    => '/webhook/',
        self::DELETE_WEBHOOK => '/webhook/',
        self::GET_WEBHOOKS   => '/webhooks/',

        self::RECEIVED_PIX        => '/pix/',
        self::RECEIVED_PIX_REFUND => '/devolucao/',

        self::CREATE_PAYLOAD_LOCATION     => '/loc/',
        self::GET_PAYLOAD_LOCATION        => '/loc/',
        self::DETACH_CHARGE_FROM_LOCATION => '/loc/',
        self::PAYLOAD_LOCATION_TXID       => '/loc/',
    ];

之后，在包的配置文件中，在PSP配置的resolve_endpoints_using键下注册您的PSP的端点解析器。

'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,
            'resolve_endpoints_using' => YourCustomEndpointResolver::class,
        ],
    ],

mateusjunges / laravel-pix

维护者

详细信息

README