betalabs / engine-sdk-gateway

5.3.7 2025-04-11 16:44 UTC

Requires

• php: >=7.2
• betalabs/engine-contracts: ^2.3
• garoevans/php-enum: ^1.2
• laravel/framework: ^7.0|^8.0|^9.0

MIT

• Betalabs Tecnologia LTDA.

• api
• sdk
• laravel
• betalabs

Published on Packagist.org on 2025-04-09 17:14 UTC

README

This package provides gateway interfaces used in Engine for your internal apps.

Installation

$ composer require betalabs/engine-sdk-gateway

Pix Automático (recurring Pix debit)

Optional contract for gateways that support Pix Automático. A gateway driver opts in by implementing the two interfaces below; Engine checks instanceof and refuses the payment method when the driver does not implement them, so drivers that do not support it are not affected.

Interface	Role
PixAutomaticAuthorizer	authorizePixAutomatic, refreshPixAutomaticAuthorization, cancelPixAutomaticAuthorization
PixAutomaticCharger	schedulePixAutomaticCharge, retryPixAutomaticCharge, cancelPixAutomaticCharge
PixAutomaticAuthorization	The authorization itself. Implemented by Engine (a persisted model), like Transaction: the gateway reads what to create from the getters and writes the gateway's answer through the setters.

How it maps to what already exists:

• The authorization plays the role the tokenized card plays for credit cards: it is created once per subscription, after the payer approves it in the bank app.
• Each cycle is a scheduled debit (schedulePixAutomaticCharge) created days before the due date. Nothing is paid when it returns: the Transaction is waiting payment and the final status arrives later (postback or polling), using the existing TransactionStatus.
• A debit refused for lack of balance is the only retryable one. The gateway must say which kind of failure it was in the history's status reason.
• Enums (PixAutomaticPeriodicity, PixAutomaticAmountMode, PixAutomaticAuthorizationStatus) use the Central Bank of Brazil's concepts, not any gateway's vocabulary: each driver translates them.

Design and rollout: docs/payments/pix-automatico-plano.md in the Engine repository.