PayPal Configuration
Set up the PayPal payment gateway, its API credentials and its webhook.
Overview
PayPal is one of the payment gateways bundled with Light Store. It uses the PayPal REST API (Orders v2) and powers both the redirect checkout and the in-page checkout overlay.
Everything is configured in the admin dashboard under Configuration > Gateways (/admin/gateways), in the PayPal section.
| Field | Required | Description |
|---|---|---|
| Enable PayPal | Yes | Shows PayPal as a payment option at checkout |
| Client ID | Yes | Client ID of your PayPal app |
| Secret | Yes | Secret of your PayPal app |
| Webhook ID | No | The ID PayPal assigns to the webhook you create, used to verify events |
| Sandbox Mode | No | Talks to api-m.sandbox.paypal.com and skips SSL certificate verification |
PayPal requires a Business account to issue API credentials. You can check your account status here. Live mode also requires your store to be served over HTTPS.
API credentials
- Go to the PayPal Developer Dashboard and switch the mode toggle to Live (or leave it on Sandbox if you are testing).
- Open Apps & Credentials and click Create App. The name is only visible to you.
- Copy the Client ID into the Client ID field in the store.
- Reveal and copy the Secret into the Secret field.
- Enable Enable PayPal, match Sandbox Mode to the mode your credentials came from, and save.
Sandbox and live credentials are not interchangeable. A live app's Client ID sent to the sandbox API (or the reverse) fails with an access token error.
At this point checkout already works: a customer who approves the payment and returns to the store has their PayPal order captured and settled on return.
Webhook
The webhook is what captures and settles orders when the customer approves the payment but never returns to the store, and what marks denied captures as failed.
-
In the PayPal Developer Dashboard, open your app under Apps & Credentials.
-
Scroll to Webhooks and click Add Webhook.
-
Set the webhook URL to your store's webhook URL:
https://your-store.com/payments/webhook/paypalThe exact URL is also printed under the Webhook ID field in the store.
-
Under Event types, select only these three:
CHECKOUT.ORDER.APPROVEDPAYMENT.CAPTURE.COMPLETEDPAYMENT.CAPTURE.DENIED
-
Save the webhook. PayPal then lists it with an ID (something like
5GH12345ABCDE6789). Copy that ID into the Webhook ID field in the store and save.
Until the Webhook ID is filled in, events cannot be verified and are acknowledged and dropped, so nothing is fulfilled through webhooks. The ID is what the store sends to PayPal to check each event's signature.
Why only these three events?
The store ignores every other event type. Selecting "All Events" only fills your webhook event log with deliveries that are acknowledged and dropped.
An approved PayPal order is not money yet, so on CHECKOUT.ORDER.APPROVED the store captures the order itself and then settles it. PAYMENT.CAPTURE.COMPLETED covers captures that completed elsewhere, and PAYMENT.CAPTURE.DENIED fails the payment.
PayPal WebScr
Light Store also ships a second, email-only PayPal gateway called PayPal WebScr. It needs nothing but your PayPal email address and uses PayPal's classic payment form, at the cost of the API features described above.
Both gateways are labelled "PayPal" at checkout. If you enable PayPal WebScr, disable the standard PayPal gateway so customers are not offered the same label twice.