Orotpay Laravel Package

Getting Started

Start with the package README and published config; for macopedia/orotpay v1.0.3 the first steps are:

1. Install with Composer and let Laravel package discovery register the service provider:

   composer require macopedia/orotpay
   

2. Publish any package config/assets if the README instructs it:

   php artisan vendor:publish --tag=orotpay-config
   

3. Add credentials and mode settings to .env, typically merchant/client ID, secret/key, and sandbox/live mode. Keep secrets out of source control.
4. Clear cached config after env changes:

   php artisan config:clear
   

5. First use case: create a payment for an order, redirect the customer to the payment page, then handle the return/callback and update the order only after server-side verification.

v1.0.3 is a small patch release: it stops sending the customer IP in dev mode. No migration or API-breaking change is indicated, but local tests or debugging flows that expected the IP to be forwarded should be adjusted.

Implementation Patterns

• Wrap the package in your own application service or action, e.g. CreateOrotpayPayment, rather than calling package classes directly from controllers. This keeps gateway-specific details isolated and makes future upgrades easier.
• Persist a local payment/order record before redirecting to the gateway. Store your order ID, gateway reference, amount, currency, status, and timestamps. Use a unique constraint on the gateway reference.
• Treat browser return URLs as UX only. The authoritative payment status should come from the server-to-server callback/webhook or an explicit status lookup.
• In the webhook controller:
  • Exclude the route from CSRF protection.
  • Verify the signature/checksum using the package’s documented method.
  • Reject mismatched order ID, amount, or currency.
  • Make processing idempotent; gateways commonly retry callbacks.
  • Queue heavier order updates and return a 2xx quickly.
• Use events/listeners for payment status transitions, e.g. PaymentSucceeded, PaymentFailed, so order and notification logic stays decoupled.
• For local development, v1.0.3 means the IP is not sent in dev mode. If you are testing a flow that depends on IP forwarding, test against sandbox/non-dev mode or mock the gateway request instead of assuming the IP will be present.
• In tests, prefer Http::fake() or the package’s fake/client abstraction if provided. Assert that your app validates signatures, handles duplicate callbacks, and does not mark orders paid from an unverified redirect.

Gotchas and Tips

• v1.0.3 changes dev-mode payload behavior. If you have request assertions, logs, or gateway-side checks expecting an IP field locally, update them. This is a privacy-oriented patch and should not require application changes in normal production flows.
• Run php artisan config:clear after changing .env; Laravel’s config cache can otherwise keep old gateway mode or credentials.
• Never log secrets, full callback payloads containing PII, or raw card/payment credentials. The dev-mode IP change is a reminder to treat request metadata carefully.
• Verify callbacks before touching order state. Check signature, amount, currency, and order status, and do not trust the return URL alone.
• Design for duplicate and out-of-order callbacks. Use idempotency keys or “update only if status is still pending” database updates.
• Add a reconciliation command/job that queries the gateway for pending payments. Webhooks can be missed.
• Keep the package on a constrained version such as ^1.0 and review patch notes. This release is a patch, so no special upgrade procedure is expected beyond normal regression testing of local payment flows.