README

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

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

安装

您可以使用 composer 安装此包。

composer require andersonav/laravel-psp-pix

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

发布资产

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

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

发布配置文件

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

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

此命令将复制文件 laravel-psp-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' => \Alves\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具有不同的token访问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 Alves\Pix\Pix;

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

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

获取访问令牌

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

use Alves\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 Alves\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 Alves\Pix\LaravelPix;

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

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

如果此包提供的认证类无法在您的PSP中获取access token，您可以创建自己的实现，只需创建一个类并扩展Alves\Pix\Api\Auth类即可

<?php

namespace App\Pix;

use Alves\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.
    }
}

现在，您需要为此包提供您的类以获取token，您可以通过应用程序的AppServiceProvider来实现

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

现在，您的认证类（带有您自己的逻辑）将用于获取access token，并且getOAuthToken()方法返回此类的getToken方法返回的内容。

可以为每个PSP配置认证类。

配置 PSP

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

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

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

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

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

Cob

Cob集合了与创建即时收费相关的端点。

有关每个端点应发送的请求的信息，请参阅官方央行文档，可在此处链接找到。

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

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

创建cob

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

use Alves\Pix\Pix;

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

审查即时收费

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

use Alves\Pix\Pix;

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

查询即时收款

要按特定交易id查询收费，您必须使用getByTransactionId方法，并提供交易id作为参数。

use Alves\Pix\Pix;

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

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

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

use Alves\Pix\Pix;

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

查询即时收款列表

要按开始日期、结束日期、状态和其他参数查询即时收费列表，请使用all()方法，并传递必要的过滤器。在此端点中，过滤器开始和结束是必需的。此软件包提供了一个API来应用过滤器，只需实例化一个新类来定义所需的过滤器，并使用withFilters()方法将它们应用到请求中。

use Alves\Pix\Pix;
use Alves\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集合了用于处理带到期日收费管理的端点。

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

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

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

创建带到期日的收费

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

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

审核到期收款

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

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

查询带到期日的收费

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

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

查询到期收款列表

要按开始日期、结束日期、状态和其他参数查询带到期日的即时收费列表，请使用all()方法，并传递必要的过滤器。在此端点中，过滤器开始和结束是必需的。此软件包提供了一个API来应用过滤器，只需实例化一个新类来定义所需的过滤器，并使用withFilters()方法将它们应用到请求中。

use Alves\Pix\Pix;
use Alves\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集合了用于处理带到期日批量收费管理的端点。

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

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

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

创建批量带到期日的收费

要创建批量带到期日的收费，请使用createBatch()方法，并提供批次id和要包含的收费。

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

审查带到期日批量收费

为了更新一批收费数据，请使用方法 updateBatch()，并告知要更新的批次id和新的数据。

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

查询到期的收费批次

为了查询到期的收费批次，请使用方法 getByBatchId()，并告知要查询的批次id。

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

查询批量到期的收费列表

为了查询批量到期的收费列表，请使用方法 all()，传递如开始时间、结束时间、状态等参数。在此端点的所有请求中，参数开始时间和结束时间是必填的。此包提供了一个API来应用请求中的过滤器，只需实例化一个用于所需过滤器的新的过滤器类，然后使用方法withFilters()将其应用于请求。

use Alves\Pix\Pix;
use Alves\Pix\Api\Filters\LoteCobvFilter;

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

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

此处列出了端点loteCobv可用的过滤器列表。

有效负载位置

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

要使用payload位置，请使用类Alves\Pix\Pix中的方法payloadLocation()。

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

创建有效负载位置

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

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

查询已注册的位置

要查询已注册的位置列表，请使用方法all()，传递如开始时间、结束时间、状态等参数。在此端点的所有请求中，参数开始时间和结束时间是必填的。此包提供了一个API来应用请求中的过滤器，只需实例化一个用于所需过滤器的新的过滤器类，然后使用方法withFilters()将其应用于请求。

use Alves\Pix\Pix;
use Alves\Pix\Api\Filters\PayloadLocationFilters;

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

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

此处列出了端点payloadLocation可用的过滤器列表。

恢复位置

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

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

从位置中解除收费的关联

要从位置中解除收费的关联，您必须使用方法detachChargeFromLocation()，并告知位置id。

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

执行成功后，实体loc将不再显示transaction_id，如果之前显示了。此外，与txid解除关联的关联实体cob或cobv也将不再显示位置。此操作不会更改关联的cob或cobv的状态。

收到的 PIX

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

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

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

查询Pix

您可以通过端到端(id end to end，e2eid)来查询接收到的Pix。

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

查询接收到的Pix

要查询所有接收到的Pix列表，请使用方法all()，传递如开始时间、结束时间、状态等参数。在此端点的所有请求中，参数开始时间和结束时间是必填的。此包提供了一个API来应用请求中的过滤器，只需实例化一个用于所需过滤器的新的过滤器类，然后使用方法withFilters()将其应用于请求。

use Alves\Pix\Pix;
use Alves\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 = \Alves\Pix\Pix::receivedPix()->refund('e2eid', 'refundId')->json();

查询退款

您可以通过此退款的id和Pix的e2eid来查询退款。

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

Webhooks

汇集了PSP接收者向接收者用户发送通知的端点。

要管理webhooks，请使用类Alves\Pix\Pix中的方法webhook。

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

配置 webhook PIX

这是配置关于接收到的Pix的通知服务的端点。仅通知与txid关联的Pix。要配置webhook，您必须使用方法create，并告知Pix的键和webhook应发送到的URL。

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

显示 webhook PIX 信息

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

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

取消 webhook PIX

要删除一个webhook，请使用delete方法，并告知与webhook关联的Pix键

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

查询已注册的webhooks

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

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

还可以包括一些过滤器，如开始时间、结束时间和分页，但在此端点中，它们都不是必需的

use Alves\Pix\Pix;
use Alves\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'    => \Alves\Pix\Api\Contracts\AuthenticatesPSPs::class,
            'resolve_endpoints_using' => YourCustomEndpointResolver::class,
        ],
    ],

andersonav / laravel-psp-pix

维护者

详细信息