Installation & configuration#

Requirements#

• PHP 8.2 or newer (Laravel 13 itself requires PHP 8.3+)
• Laravel 11, 12, or 13

Install#

composer require luigel/laravel-paymongo:^3.0

The service provider and the Paymongo facade are auto-discovered, so there is nothing to register.

Add your API keys#

Copy your keys from the PayMongo dashboard into .env:

PAYMONGO_SECRET_KEY=sk_test_...
PAYMONGO_PUBLIC_KEY=pk_test_...

Keys starting with sk_test_ / pk_test_ work in test mode: nothing is charged, and PayMongo's test cards and e-wallet test pages complete payments for you. Develop with them, and swap in your sk_live_ / pk_live_ keys only in production.

The secret key authenticates every server-side call. The public key is only needed for the few calls meant for the browser, such as retrieving a payment intent with its client key.

Add your webhook secret#

PayMongo tells your app a payment succeeded by calling a webhook. When you register a webhook endpoint, PayMongo returns a secret_key that signs every delivery; the package verifies deliveries against it:

PAYMONGO_WEBHOOK_SECRET=whsk_...

Your first payment walks through registering an endpoint and getting this secret.

PayMongo signs test-mode and live-mode deliveries differently. Set PAYMONGO_LIVEMODE=true in production so the package checks the live-mode signature.

Configuration#

Every option has a sensible default and can be set from .env:

Variable	Default	What it does
PAYMONGO_SECRET_KEY	none	Secret API key for server-side calls
PAYMONGO_PUBLIC_KEY	none	Public API key for client-key calls
PAYMONGO_WEBHOOK_SECRET	none	Signing secret of your webhook endpoint
PAYMONGO_LIVEMODE	false	Verify webhook signatures as live-mode deliveries
PAYMONGO_BASE_URL	https://api.paymongo.com/v1	API base URL
PAYMONGO_TIMEOUT	30	Request timeout, in seconds
PAYMONGO_RETRIES	2	Retries after the first attempt, for failures safe to repeat; 0 disables them
PAYMONGO_RETRY_DELAY	200	First wait between attempts, in milliseconds; it doubles on every retry
PAYMONGO_MAX_RETRY_DELAY	5000	Longest wait between attempts, in milliseconds
PAYMONGO_AUTO_IDEMPOTENCY	true	Send an idempotency key with every POST
PAYMONGO_WEBHOOK_TOLERANCE	300	Oldest webhook timestamp accepted, in seconds; 0 disables the check
PAYMONGO_WEBHOOK_DEDUPE	true	Skip webhook deliveries already handled
PAYMONGO_WEBHOOK_DEDUPE_STORE	default cache store	Cache store that remembers handled deliveries

To change anything that is not an environment variable, such as named secrets for several webhook endpoints, publish the config file to config/paymongo.php:

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

The Config page of the Reference lists every option in that file.

Check it works#

Run a read-only call from Tinker. With a test key it lists your test-mode webhook endpoints, which is an empty list on a new account:

php artisan tinker --execute 'dump(Luigel\Paymongo\Facades\Paymongo::webhooks()->list());'

An AuthenticationException means the secret key is missing or wrong.

AI coding agents (Laravel Boost)#

The package ships Laravel Boost resources, so AI agents working in your app know the v3 API. You get a guideline covering the centavo rule, the services, data objects, webhooks and the testing fake. You also get two skills: paymongo-docs, which has the agent read PayMongo's official docs before answering, and paymongo-v3-upgrade, which walks the agent through migrating from 2.x.

php artisan boost:install              # new Boost setup
php artisan boost:update --discover    # existing Boost app: pick up newly installed packages

Select luigel/laravel-paymongo when prompted. Boost then loads the guideline into every agent session.

Next: take your first payment.