README

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

安装
- 发布资源文件
- 发布配置文件
端点
初始配置
- 获取访问令牌
- 配置PSPs
Cob
CobV
LoteCobV
Payload Location
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配置和删除位置的端点）
- POST /loc：创建payload位置。
- GET /loc：查询已注册的位置。
- GET /loc/{id}：检索payload位置。
- DELETE /loc/{id}/{txid}：解除一次收费与位置的关联。
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');

这些方法在所有Pix API资源中可用：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有集成，您可以在此包的配置文件中为每个PSP配置单独的参数，在config/laravel-pix.php中。

包中使用的默认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端点使用的过滤器列表。

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端点使用的过滤器列表。

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 上使用的筛选条件列表。

Payload Location

位置位置有效载荷汇集了用于处理有效载荷中使用的位置配置和删除的端点。

要使用位置有效载荷，请使用类 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 上使用的筛选条件列表。

恢复位置

要查询有效载荷位置，您必须使用方法 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 上使用的筛选条件列表。

请求退款

您可以通过方法 refund 请求退款，并提供要退款的Pix的 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向接收者用户发送的通知的端点。

要管理webhooks，请使用类 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();

查询已注册的webhooks

要查询所有已注册的webhooks，请使用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端点的所有过滤器

配置端点

要为每个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/',
    ];

之后，在配置文件中，在resolve_endpoints_using键下注册您的PSP端点解析器，该键位于此包的配置文件中，在所需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,
        ],
    ],

jrodella / laravel-pix

维护者

详情