Security and operations.

Payment integrations cross trust boundaries and change financial state. Treat the API client, browser handoff, webhook endpoint, and queue as separate operational surfaces.

Protect credentials

The secret key is server-side only. It is sent as the username of HTTP Basic authentication on every API request.

• Store it in the deployment environment or secret manager.
• Never return it from a controller.
• Never put it in JavaScript, HTML, exception context, or logs.
• Keep test and live credentials in separate environments.
• Rotate a key if it may have been exposed.

Only Payrex::publicKey() is intended for browser use.

Protect the webhook secret

The webhook signing secret is different from API credentials. Store the secret returned when the endpoint is created and configure it as PAYREX_WEBHOOK_SECRET.

The package verifies signatures with constant-time comparison and checks the timestamp against a 300-second tolerance by default. Keep system time synchronized and monitor signature failures.

The webhook route has no CSRF token by design. Do not place it behind session authentication. Add rate limiting when appropriate:

'webhooks' => [
    // ...
    'middleware' => ['throttle:60,1'],
],

Queue and deduplicate listeners

PayRex retries failed or slow webhook deliveries for up to three days with exponential backoff. A valid event can therefore arrive more than once.

• Implement ShouldQueue.
• Put a unique index on the PayRex event ID.
• Make the domain transition conditional as a second line of defense.
• Return from the webhook request quickly.
• Keep failed jobs observable and retryable.

The timestamp freshness window is not deduplication.

Do not retry mutations blindly

The client retries only safe GET requests. PayRex does not document idempotency keys, so automatic retry of POST, PUT, or DELETE could create duplicate financial operations.

After an ambiguous timeout:

1. retain the local operation record;
2. reconcile through retrieval, webhooks, or the PayRex dashboard;
3. contact PayRex with relevant response or request identifiers when needed;
4. mutate again only when you know the first operation did not complete.

Handle money as integers

All amounts are integers in the smallest currency unit. For PHP, 10_000 is ₱100.00. Never convert a user-entered decimal amount with floating-point arithmetic at the API boundary. Parse and validate it into centavos using a decimal-safe approach.

The package locally validates only the documented payment-intent range. Line-item totals, refund ceilings, account eligibility, and other business rules remain server-validated.

Keep personal data out of logs

DTO $raw payloads can contain names, email addresses, billing details, payment metadata, and other sensitive information. Sanitize them before logging or attaching them to a public issue.

Do not log credentials, client secrets, full webhook headers, or unredacted payment-method details.

Monitor the integration

Useful signals include:

• ApiConnectionException and timeout frequency;
• authentication and permission failures;
• HTTP 429 and 5xx rates;
• webhook signature failures;
• webhook processing latency and failed jobs;
• duplicate event IDs;
• payment intents stuck in intermediate states; and
• refund, payout, and billing-statement reconciliation gaps.

Payrex::lastResponse() exposes the most recent status and response headers. PayRex does not guarantee specific header names, so treat any request or rate-limit header as optional.

Deployment checklist

• Test credentials are absent from production.
• The secret key never reaches client-side code.
• The correct live webhook signing secret is configured.
• The public webhook URL uses HTTPS.
• The server clock is synchronized.
• Webhook listeners are queued and idempotent.
• Queue failures and API exceptions are monitored.
• Configuration cache is rebuilt after secret changes.
• A reconciliation path exists for ambiguous mutations.
• Raw payload logging is sanitized.

Report vulnerabilities privately

Use the package repository's security policy for package vulnerabilities. Report vulnerabilities in PayRex itself directly to PayRex.