- How do I install and set up giorgigrdzelidze/laravel-bog-sdk in a Laravel app?
- Install the package with Composer from your project root using composer require giorgigrdzelidze/laravel-bog-sdk; the service provider is auto-discovered on standard Laravel versions. After installation, publish the package configuration file with vendor:publish and add your Bank of Georgia client credentials to your .env file. Because DTO contracts have changed between releases, pin an explicit version constraint in composer.json rather than relying on a floating tag. Then run a single read-only call, such as a balance or account lookup, against the sandbox before wiring it into scheduled jobs.
- Which Bank of Georgia APIs does this Laravel package support?
- The package covers Bonline, Payments, iPay, Installment, Billing, BOG-ID (OpenID Connect) and Open Banking. Bonline is the module most Laravel finance teams use, since it exposes account balances, statements, daily activity and card-payment data. Each API area is exposed through domain-oriented service classes and typed DTOs rather than raw arrays, which keeps controller and job code readable. Check the README for the exact method surface of each module before designing your integration.
- How do I configure BOG API credentials and switch between sandbox and production?
- Credentials are supplied through the published config file, which reads from environment variables so you can keep separate sandbox and production values per deployment. Environment selection, plus account and currency identifiers, are configuration concerns rather than hard-coded arguments, so you can drive them from config or a database-backed settings table. Keep secrets in .env or your secret manager and never commit the published config with real credentials. Use distinct config caches per environment and verify the resolved credentials with a cheap API call after each deploy.
- Which Laravel and PHP versions are supported by this BOG SDK?
- The package relies on typed DTOs, so it targets modern PHP versions with native typed property support and contemporary Laravel releases. The authoritative constraints live in the package's composer.json and README, so check those before upgrading your framework. If you run an older Laravel version, test installation in a branch first because auto-discovery and config publishing behaviour varies across major versions. Pin both the package and your PHP minor version in CI to avoid surprise resolution changes.
- How do I fetch account balances and statements from Bonline using this package?
- You resolve the Bonline service from the container and call its balance, statement or daily-activity methods, which return typed DTOs you can map into Eloquent models or your own finance domain objects. The v1.1.0 release corrected statement pagination and a balance call that previously returned HTTP 400, so treat that version as the minimum for production use. Statement responses include card-payment entries, and CardPaymentDto::fromText() parses merchant, terminal and amount details out of the narrative text. Because that parsing depends on narrative formatting, validate it against real statements from your own merchant accounts before trusting it in reconciliation.
- How does OAuth2 authentication and token refresh work in laravel-bog-sdk?
- The package handles the OAuth2 flow for you, obtaining access tokens from the configured credentials and attaching them to outgoing Bonline and Open Banking requests. Tokens should be cached rather than requested on every call, so make sure your cache store is shared across queue workers and web nodes. If you run long-lived queue jobs, keep requests short-lived and let the package refresh credentials instead of holding a token for the whole job. Monitor authentication failures separately from business errors so you can distinguish expired credentials from API-side issues.
- How do I verify Bank of Georgia callback signatures with this package?
- The package includes callback signature verification so you can validate incoming BOG webhooks before acting on the payload. Verify the raw request body exactly as received, then reject anything that fails and return the expected HTTP status rather than throwing an unhandled exception. Because callbacks may be retried, make your handlers idempotent by keying on the payment or transaction identifier. Log verification failures with enough context to debug certificate or secret rotation problems without storing sensitive payload fields.
- Is v1.1.0 a breaking change and how stable are the DTO contracts?
- Yes, in practice. todayActivities()->get() now returns an array of TodayActivityDto instead of data mapped onto TransactionDto, which is a return-type change shipped in a minor release. The statement pagination, balance and daily-activity fixes in the same release are corrective and low risk, and additions like CardPaymentDto and the BalanceDto accountKey and statementBalance fields are additive. Until the maintainer publishes an explicit backward-compatibility policy, pin the version and review the changelog in CI before bumping. Treat DTO property names as an external contract that needs its own regression tests.
- How do I migrate code that reads entryAmountCredit or entryAmountDebit after upgrading?
- Replace reads of entryAmountCredit and entryAmountDebit with the credit, debit and nomination fields on TodayActivityDto, and update type hints and docblocks that reference TransactionDto for today's activities. Those old fields were already returning empty values against the live API, so you are unlikely to lose real data, but the change still requires a code review and a queue of regression tests. Search your codebase for todayActivities(), entryAmountCredit, entryAmountDebit and related field names before deploying. Run the upgrade in a non-production environment first and compare record counts and sums against a known statement period.
- Can I stream large statements, and how should I handle BOG rate limits and errors in production?
- The package exposes a stream() method for statement ingestion, which lets you process large volumes page by page instead of loading a full year of transactions into memory at once. Verify the streamed record count against the envelope's TotalCount and make sure partial-page failures surface as clear exceptions rather than silently truncated results. Bonline rate limits, retry expectations and error semantics are not documented by the package, so implement your own backoff, retry budget and alerting around API calls. Add contract tests using recorded statement, balance and today-activity fixtures, and monitor API error rates and ingested record counts after each deployment.