README

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

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

安装

您可以使用composer安装此包

composer require owl-code-team/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：查询有到期日收费批量。
有效负载位置（汇集用于处理有效负载配置和删除位置的端点）
- POST /loc：创建有效负载位置。
- GET /loc：查询已注册的位置。
- GET /loc/{id}：恢复有效负载位置。
- 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。

初始配置。

要开始使用API Pix，您需要通过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"

提供API Pix的许多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"

现在，所有对API Pix的调用都将使用这些凭据，并且您无需为每个请求手动提供。但是，如果您出于某种原因想在运行时更改这些凭据，可以通过此包中所有端点提供的->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端点需要验证此证书，您需要向此包提供此包以进行验证。这可以通过在应用程序的AppServiceProvider中添加此行到register方法来完成。

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

此端点可用的过滤器列表如下

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

此端点可用的过滤器列表如下

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 聚合了处理 payload 中 locations 配置和删除的端点。

要使用 payload location，请使用 Junges\Pix\Pix 类的 payloadLocation() 方法

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

创建有效负载位置

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

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

查询已注册的位置

要查询已登记的 locations 列表，请使用 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 端点的筛选器列表

恢复 location

要查询 payload 的 location，您必须使用 getById() 方法

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

解除账单与 location 的关联

要解除账单与 location 的关联，您必须使用 detachChargeFromLocation() 方法，并提供 location 的 ID

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

操作成功后，实体 loc 将不再显示 transaction_id，如果之前有显示的话。此外，与解绑的 txid 关联的 cob 或 cobv 实体也将不再显示 location。此操作不会更改 cob 或 cobv 的 status。

Pix接收

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

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

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

查询 Pix

您可以通过端到端 (e2eid) ID 查询接收到的 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/',
    ];

之后，将您的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,
        ],
    ],

owl-code-team / laravel-pix

维护者

详细信息