Transbank Sdk Laravel Package

Technical Evaluation

Architecture fit. transbank/transbank-sdk is a thin, stateless HTTP client library that wraps Transbank's REST payment APIs (Webpay Plus, Webpay Oneclick/Mall, Transacción Completa, Patpass Comercio). It has no service provider, no facade, and no framework coupling, so it slots into a Laravel app as a low-level transport rather than an opinionated package. That is a feature for us: it does not fight the container, and it avoids the anti-pattern of a vendor SDK owning application flow. It is a poor fit only if we expect the package to give us checkout UI, persistence, reconciliation, or webhook handling — it gives us none of that, and we would be building that layer ourselves regardless of package choice.

Release 5.1.0 is additive and confirms that shape: it adds a single class, MallBinInfo, exposing queryBin to retrieve card information for a card already registered under Oneclick Mall. No existing methods change, no configuration surface changes, no new dependency. It stays a transport primitive — the method returns card metadata that we must decide what to do with, which is exactly the boundary we wanted.

Integration feasibility. High. Composer-installable, BSD-3-Clause (permissive, no copyleft exposure, compatible with commercial redistribution), actively released (5.1.0 is a minor bump on the current major line, following the June 2025 release), and requires only Guzzle plus standard PHP JSON/cURL extensions. The main integration work is wrapping its static/global configuration (Options, commerce code, API key, environment) into container-bound singletons so sandbox and production credentials are not process-global. This is a familiar half-day pattern, not a design problem, but it must be done deliberately — static configuration is the single most common source of "wrong-environment charge" incidents in this ecosystem.

5.1.0 does not change this. Adopting it is a constraint bump within the existing major (^5.0 → ^5.1 if we want MallBinInfo), not a re-integration. It is strictly opt-in: if we do not use Oneclick Mall, the new class is dead weight we can ignore without pinning below it.

Technical risk. Low-to-moderate, and concentrated in the domain rather than the code:

• Vendor-concentration risk. Transbank is effectively the incumbent acquirer in Chile; the SDK itself is an official first-party artifact, which mitigates the abandonment risk suggested by 61 stars. Low star count and zero Packagist dependents reflect that consumers install it directly, not that it is unmaintained.
• Semantic versioning risk. Transbank has shipped breaking changes across major versions (v1 SOAP → v2 REST → current line). 5.1.0 is a clean additive minor, which is reassuring evidence of semver discipline inside the current major, but it does not reduce the risk at major boundaries. Pin the constraint and budget for a migration on each major.
• PCI scope. The redirect/hosted-page flows keep card data off our servers, which is the primary reason to use this SDK over a custom integration. Any use of Transacción Completa for card-not-present still keeps PAN out of our systems, but expands our logging and audit obligations.
• New in 5.1.0 — card metadata handling. MallBinInfo::queryBin returns information about a card already enrolled in Oneclick. That is not PAN data, but it is cardholder-adjacent metadata, and it only works against stored Oneclick credentials. Risk is low provided we treat the response as transient display/routing data, do not persist it beyond what a stated purpose requires, and do not let it leak into logs or analytics. If we cache it, the cache inherits a data-retention obligation.
• Payment-state ambiguity. The SDK faithfully surfaces Transbank's state machine (authorized / committed / reversed / failed), and does not protect us from double-commit or lost-response scenarios. That is our problem to solve, and it is the real risk in the engagement. queryBin is a read-only lookup and does not interact with that state machine at all, which limits its blast radius.

Key questions.

1. Which products do we actually need — Webpay Plus redirect only, or Oneclick/Mall for stored credentials, or Transacción Completa? The answer changes the integration surface materially, and it now also determines whether 5.1.0 is relevant at all: MallBinInfo is Oneclick Mall-only.
2. Which environment tier and contract do we hold with Transbank, and are sandbox credentials and production commerce codes provisioned under our own merchant account or a partner's?
3. Do we need deferred capture, refunds, or partial reversals in the first release? These drive schema and reconciliation design more than the SDK does.
4. Who owns reconciliation — do we ingest Transbank settlement reports, or rely on per-transaction status polling?
5. Is there an existing Laravel wrapper already in the codebase (community wrappers are common), and if so, is it on the current SDK major — and does it expose the 5.1.0 surface or pin below it?
6. New: Is BIN lookup an actual product requirement (installment/promotion display, card-brand routing) or a "nice to have"? If it is a requirement, we need to confirm with Transbank that the capability is enabled on our commerce code in both sandbox and production, because a class existing in the SDK does not guarantee the endpoint is provisioned for us.

Integration Approach

Stack fit. Clean fit for Laravel 10/11/12 on PHP 8.1+. Bind Options and a TransbankClient service as container singletons driven by config/services.php and .env (TRANSBANK_ENV, TRANSBANK_COMMERCE_CODE, TRANSBANK_API_KEY). Wrap each product (WebpayPlus, Oneclick, TransaccionCompleta) in an application-level gateway class that returns our own DTOs — never let Transbank\...\Response objects leak into controllers, jobs, or views. Keep the SDK strictly at the infrastructure boundary. If we adopt 5.1.0, MallBinInfo belongs behind the same Oneclick gateway as a lookupBin(string $username, string $token)-style method returning our own DTO, not called directly from a controller.

Version decision. Treat 5.1.0 as an in-place minor upgrade with no migration step. If the BIN capability is not in scope for this release, there is no urgency to bump — but there is also no reason to hold back, since nothing existing changes. If it is in scope, bump the constraint to ^5.1 and add it to the Oneclick workstream rather than as a standalone task.

Migration path. Two realistic starting points. If greenfield, go straight to the current SDK major and the REST endpoints; do not adopt any SOAP-era wrapper. If we are replacing the legacy kcc/transbank-sdk or a hand-rolled SOAP integration, the migration is not a drop-in: endpoint, credential, and response-shape changes mean we should stand up the new gateway in parallel behind a feature flag, route a small percentage of traffic, and dual-write transaction records so we can diff outcomes before cutover. Budget for a shadow-mode period covering at least one full settlement cycle.

Compatibility. PHP 8.x and Guzzle 7 are the practical constraints; verify against our pinned Guzzle version, because Laravel's HTTP client and the SDK's own Guzzle usage can coexist but we should not mix them for the same call. Confirm the SDK major supports every product we need — product coverage has lagged across versions, and 5.1.0's addition is evidence that the Oneclick Mall surface is still being filled in, so check the changelog rather than assuming a full API surface. Check that our queue worker, webhook receiver, and HTTP timeout settings align with Transbank's response-time characteristics.

Sequencing.

1. Provision sandbox credentials and confirm merchant contract and product enablement — including, if applicable, whether BIN lookup is enabled on our commerce code.
2. Build the config binding, gateway wrapper, and DTO layer; write contract tests against the sandbox.
3. Implement the checkout initiation and return-URL handler with idempotency keys and a persisted transaction ledger.
4. Implement commit, refund, and status-query paths with explicit timeout and retry policy.
5. New, only if BIN lookup is in scope: add the queryBin wrapper path behind the Oneclick gateway, with an explicit decision on caching, retention, and logging redaction before any code is written.
6. Build reconciliation against Transbank reports; add alerting on unmatched transactions.
7. Shadow-run, then cut over behind a flag with a documented rollback to the prior provider.

Operational Impact

Maintenance. Low code churn, but the package is a dependency on an external regulated counterparty, so maintenance is really vendor-relationship maintenance: tracking Transbank's API changes, certificate and credential rotation, and major-version upgrades. Assign explicit ownership. Pin the version, run an automated dependency update check, and treat any major bump as a scheduled project rather than a routine merge. Minors like 5.1.0 can flow through normal review — the diff is a new class with no behavioural change to existing paths — but the reviewer should still confirm the "no changes to existing methods" claim against the diff rather than the release note.

Support. First-line support is ours; Transbank provides merchant support for transaction disputes and certification. Establish early who we call for a stuck settlement versus a failed API call, and add a separate line for "BIN lookup returns an error or unexpected metadata" if we ship that feature, since it is a distinct endpoint with its own enablement state. Document the escalation path and keep the merchant commerce code and integration engineer contact in the runbook.

Scaling. The SDK is stateless and network-bound; scaling is about outbound HTTP behaviour, not the library. Set conservative connect/read timeouts, use connection reuse, and cap concurrency to whatever our Transbank agreement tolerates. Payment calls should not sit in the request/response cycle where avoidable — initiate, persist, and let the return URL or a queued job finalize state. Add circuit breaking so a Transbank outage degrades to a clear "payment unavailable" path instead of exhausting PHP-FPM workers. queryBin is a read-only, low-volume lookup; it should not be on the checkout critical path, and it must not be allowed to fail a payment flow if it times out.

Failure modes. The dangerous cases are ambiguous, not clean: a timeout after Transbank processed a commit, a duplicated commit from a user retry, a return-URL that never arrives because the user closed the tab, and refunds issued against a transaction we recorded as failed. Mitigations are architectural — idempotency keys on initiation, never blindly retrying a commit, treating the return URL as an optimization rather than the source of truth, and reconciling against settlement reports daily. Also plan for sandbox/production credential crossover, which is the highest-frequency self-inflicted incident in this integration class. The 5.1.0 surface adds no new financial failure mode, but it does add a data-handling one: logging a raw BIN response is easy, silent, and hard to unwind.

Ramp-up. Engineering ramp-up is roughly one to two days for a developer familiar with Laravel HTTP clients; the SDK's API surface is small, and 5.1.0 adds one class. The real ramp-up is payments literacy — the transaction lifecycle, capture versus commit, reversals, and reconciliation — which is a one-to-two-week curve for the team and should be paired with a written runbook. Allocate a senior reviewer with payments experience for the commit/refund paths specifically, since that is where correctness failures translate directly into financial loss and chargeback exposure. The BIN lookup is a low-complexity add-on and does not extend that curve.