Asaas Sdk Php Laravel Laravel Package

Product Decisions This Supports

• Build vs. buy for payments integration: this is a thin Laravel service-provider/facade wrapper around the Asaas PHP SDK, so the real decision is "buy the integration layer, own the business logic." Adopting it should remove weeks of boilerplate (auth, HTTP client config, config publishing, DI bindings) without locking you out of the underlying Asaas API.
• Reconciliation and idempotency design (v1.9.0.0): the only change in this release is support for the externalReference field. That field is the hook that lets every charge, subscription, or transfer carry your internal identifier (order ID, invoice ID, tenant ID) into Asaas and back out through webhooks and API reads. This directly enables: matching gateway events to internal records without heuristic/amount-plus-date matching, safe retry semantics when a create call times out, and cleaner finance/ops reporting.
• Roadmap sequencing: treat this as an enabler for anything touching billing — checkout flows, subscription lifecycle, dunning/retry, refunds, split payments to subaccounts. If your roadmap has payments in the next two quarters, adopting now (while the surface area is small) is cheaper than retrofitting externalReference into already-written persistence and webhook handlers.
• Vendor concentration risk: this is a community SDK (jetimob) tracking a single Brazilian gateway. It supports a decision to keep gateway-specific code behind an internal interface so a second PSP can be added without rewriting domain logic.
• Feature parity tracking: because the SDK lags the upstream Asaas API (this release is a single field, contributed by a first-time contributor), a standing decision is needed on who monitors [Asaas API changelogs] vs. [SDK releases], and whether gaps get patched locally or upstreamed.

When to Consider This Package

Adopt when:

• You are on Laravel (the value here is the service provider, config, and facade — it is worthless in Symfony, plain PHP, or a non-PHP service).
• Your payment volume runs through Asaas (Brazilian market: Pix, boleto, credit card, subaccounts/split), or Asaas is a serious candidate in your gateway evaluation.
• You want speed to first transaction and are willing to accept a thinner abstraction than a first-party SDK would give you.
• You need externalReference-style correlation between gateway objects and internal domain entities — which this release now covers, though confirm it is exposed on the specific resources you use (charges vs. subscriptions vs. transfers), not just the one the PR touched.
• Your team is comfortable reading the vendor SDK underneath when docs are thin.

Look elsewhere (or wrap heavily) when:

• You need multi-gateway abstraction as a product requirement — this SDK is Asaas-specific by design; use it behind your own PaymentGateway port, or pick an agnostic layer.
• You require formal support SLAs, security review artifacts, or long-term maintenance guarantees. This is a small-maintainer package; a single field addition shipped as a minor version, and the cadence suggests it is maintained reactively.
• You are outside Brazil or need gateways Asaas does not serve.
• You need strict semver guarantees across a large blast radius — the four-segment version scheme (1.9.0.0) and a .0-patch convention mean you should pin exact versions and read every changelog rather than trusting ^1.9.
• Your compliance posture forbids transmitting PII/cardholder data through a third-party wrapper you have not audited. Budget for a code read of the wrapper plus the transitive asaas-sdk-php dependency.

How to Pitch It (Stakeholders)

To executives (one paragraph): This release is small but useful — it lets every payment record we create carry our own internal reference ID into the gateway, so finance and support can trace a charge to an order or customer instantly instead of matching on amounts and dates. Combined with the package itself, it means we can stand up Asaas payments in Laravel on a bought integration layer rather than building one, and keep the reconciliation model clean from day one. Cost is low and reversible: it is a thin wrapper, so the main investment is our own domain code, which stays ours either way. The watch item is that this is a small community-maintained package, so we pin versions and keep the gateway behind an internal interface.

To engineering (the ask): Upgrade to v1.9.0.0, then actually use externalReference — set it on every create call from a single correlation-ID service, persist it locally, and assert on it in webhook handlers before mutating state. Verify the field is plumbed through the specific resources and DTOs you depend on, not just the one path the PR touched, and add a contract test that round-trips it. Pin the dependency to an exact version, add the package to the dependency-review and changelog-monitoring list, and file upstream PRs for any Asaas API fields we need that the SDK has not yet surfaced rather than forking silently. No breaking changes in this release; the change is additive and safe to take alongside unrelated work.