Laravel Omise Laravel Package

Getting Started

• composer require soap/laravel-omise — Laravel's package auto-discovery registers the service provider and the Omise facade alias, so there is nothing to add to config/app.php on a modern skeleton.
• Publish the config first: php artisan vendor:publish --tag=omise-config. If the tag has changed between versions, run plain php artisan vendor:publish and pick the provider from the list — this is the single fastest way to see what the package actually exposes.
• Add OMISE_PUBLIC_KEY, OMISE_SECRET_KEY and OMISE_API_VERSION (default 2019-05-29) to .env. Use pkey_test_… / skey_test_… locally; the key prefix is the only thing separating test from live, there is no separate sandbox host.
• Where to look first: config/omise.php for the knobs, then the Omise facade class in src/ for the resource accessors (charges(), customers(), tokens(), sources(), refunds(), transfers(), recipients(), schedules(), search()). The tests directory is usually the best source of real call shapes.
• First use case: a one-off card charge. The card number belongs in Omise.js on the front end; your controller receives omiseToken and calls Omise::charge(['amount' => 100000, 'currency' => 'thb', 'card' => $request->omiseToken]). Amounts are integers in the smallest currency unit — 100000 = ฿1,000.00.

Implementation Patterns

• Wrap the facade. The Omise facade is awkward to mock. Put charges behind your own PaymentGateway interface with a single charge(Order $order, string $token): ChargeResult method, bind it in a service provider, and swap in a fake for tests. This is the highest-leverage decision you make in day one.
• Token vs customer. For one-off payments, charge the token directly. For repeat billing, create the customer once (Omise::customers()->create([... 'card' => $token])), store the cust_… id on your user, and charge with 'customer' => $customerId thereafter. Never store the token itself — it is single-use.
• Non-card methods. PromptPay / TrueMoney / Alipay / internet banking go through sources: create the source, charge with 'source' => $sourceId, then redirect to $charge['authorize_uri'] and re-fetch the charge on return. Model this as a separate PendingCharge record rather than trying to fit it into the card flow.
• 3-D Secure. Check authorized and status on the returned charge. status === 'pending' plus a non-null authorize_uri means redirect; status === 'successful' means done. Always re-fetch by id after the return URL instead of trusting query parameters.
• Webhooks. Register the route outside the web middleware group (CSRF will reject Omise's POST), return 200 immediately, and push the payload onto a queue. Omise does not sign webhooks the way Stripe does, so verify by re-fetching the charge/event from the API and comparing the amount and currency against your own order record before fulfilling anything.
• Idempotency. Omise supports an idempotency key on charge creation; if the package's charge() signature doesn't expose it, drop to OmiseCharge::create($params, $publicKey, $secretKey) from the underlying SDK for that one call. Guard webhook handlers with a unique index on event_id / charge_id.
• Reconciliation. Webhooks can arrive out of order or not at all. Add a scheduled command that pages Omise::charges()->all([...]) for the last 24h and settles anything your webhook missed. This is not optional for money.
• Multi-tenant keys. If each tenant has its own Omise account, don't rely on the singleton config; build a small factory that constructs the client per tenant and resolves it from the container.

Gotchas and Tips

• Amounts are integers in the smallest unit. THB has 100 satang. (int) ($total * 100) on a float will eventually produce an off-by-one-satang charge — use brick/money or integer arithmetic from the start.
• Errors are exceptions, not return values. The SDK throws OmiseException subclasses: OmiseCardException, OmiseInvalidCardException, OmiseFailedCaptureException, plus OmiseNotFoundException (bad id), OmiseAuthenticationException (bad key) and OmiseApiConnectionException (timeout). Catch OmiseNotFoundException and OmiseAuthenticationException separately — they usually mean a bug or a config problem, not a declined card.
• Persist the failure reason. $charge['failure_code'] and failure_message are what your support team will need. failure_code values are a stable enum; the message is not.
• config:cache is the classic "wrong keys in production" bug. The config file reads env() at boot; after changing .env on a cached deploy you must re-run php artisan config:cache. Same for Octane — restart the workers or the singleton client keeps the old credentials.
• Test cards and magic amounts. Omise's documented test cards (success, generic decline, insufficient funds) plus the magic amount for failed captures let you exercise every branch without touching live keys. Put them in a seeder or Pest dataset.
• Never log the payload wholesale. Tokens are safe to log; card numbers, card['number'], and full webhook bodies are not. Add a Log::shareContext / middleware sanitizer before you need it.
• Extension point: the service provider binds the client into the container. Rebinding that binding in your own provider is the clean way to decorate requests (retries, metrics, a fake in tests) without forking the package.
• v1.6.1 shipped with only a compare link in the release notes — no documented features, fixes, or breaking changes. Treat it as a patch: pin ^1.6, and if you depend on internals, diff v1.6.0...v1.6.1 yourself before deploying. Re-run your payment integration tests after the bump; a wrapper package this thin can change a method signature without a major version.