Troubleshooting.

Start with the exception class and the most recent response metadata. They usually distinguish configuration, transport, request, and PayRex API failures.

try {
    // PayRex operation
} catch (\ByRcsc\LaravelPayrex\Exceptions\PayrexException $exception) {
    logger()->error('PayRex operation failed', [
        'exception' => $exception::class,
        'status' => $exception->statusCode,
        'error_codes' => array_map(
            fn ($error) => $error->code,
            $exception->errors(),
        ),
        'response_status' => Payrex::lastResponse()?->status,
    ]);
}

Sanitize all logged payloads.

No secret key is configured

InvalidConfigurationException with “Set PAYREX_SECRET_KEY” means the resolved configuration contains no usable secret.

1. Confirm PAYREX_SECRET_KEY exists in the running environment.
2. Confirm the key belongs to the intended test or live mode.
3. Run php artisan optimize:clear.
4. Rebuild configuration cache during deployment.
5. Confirm long-running workers were restarted after the change.

Authentication or permission failure

AuthenticationException is HTTP 401: the key is missing, malformed, or rejected. PermissionException is HTTP 403: the key is valid but the account cannot perform that operation.

Do not print the key while debugging. Compare its environment, mode, and permissions through your secret manager and PayRex account.

A request returns 404

ResourceNotFoundException means the route exists but the record does not. Check the resource prefix, environment, and whether it was deleted.

RouteNotFoundException means PayRex has no matching API route. Confirm the operation exists in the current PayRex documentation. In particular, PayRex does not provide a retrieve route for a billing statement line item; read it from the parent statement's lineItems.

A typed enum property is null

Unknown enum values intentionally decode to null. Inspect the object's raw payload:

$status = $intent->status;
$literal = $intent->raw['status'] ?? null;

This usually means PayRex introduced a value that the installed package does not model yet. Preserve the literal in diagnostics and check for a newer package release before reporting it.

A retrieved customer is deleted

PayRex can return a deleted-customer tombstone with HTTP 200:

if ($customer->isDeleted()) {
    // Clear or repair the local association.
}

This is not a failed hydration or missing 404.

Billing statement finalization fails

PayRex requires a due date at finalization but drops due_at from creation. Use the full sequence:

$statement = Payrex::billingStatements()->create(customerId: $customerId);

Payrex::billingStatementLineItems()->create(
    billingStatementId: $statement->id,
    unitPrice: 10_000,
);

Payrex::billingStatements()->update(
    id: $statement->id,
    dueAt: now()->addDays(14)->timestamp,
);

Payrex::billingStatements()->finalize($statement->id);

A webhook returns HTTP 400

Check:

• PAYREX_WEBHOOK_SECRET is the endpoint's signing secret, not an API key;
• the test endpoint uses the test secret and the live endpoint uses the live secret;
• a proxy or middleware is not rewriting the raw request body;
• the configured header matches Payrex-Signature;
• the server clock is synchronized; and
• the tolerance is appropriate for the environment.

Do not disable verification to make the request pass.

A listener does not run

1. Run php artisan payrex:webhook-test "payment_intent.succeeded".
2. Confirm the type is mapped in config/payrex.php.
3. Confirm Laravel discovers or registers the listener.
4. Confirm the queue worker is running and watching the correct queue.
5. Inspect failed jobs.
6. Confirm the real endpoint is enabled and subscribed to the type.

The synthetic command tests event wiring, not the remote endpoint or signature.

A listener runs twice

Duplicate delivery is expected behavior, not proof of a signature failure. Deduplicate using a unique event-ID record and make the business transition idempotent.

A mutation timed out

Do not immediately repeat the call. The request may have reached PayRex even though the response did not reach your application. Reconcile through a safe retrieve operation, a webhook, the PayRex dashboard, or PayRex support.

Get help

For usage questions, start a GitHub discussion. For a reproducible package defect or an API response that is not modeled correctly, open an issue with a minimal reproduction and sanitized response.

For PayRex account, settlement, eligibility, or API-policy questions, contact PayRex directly.

What to read next

• Errors and retries for the exception hierarchy and retry rules.
• Installation and setup to verify credentials and cached configuration.
• Security and operations to prevent common production failures.