PayPal

Prerequisites#

• A PayPal Business account
• Your application registered at developer.paypal.com
• Commerce accessible over HTTPS

Configuration#

Go to Admin → Settings → Payment Gateways → PayPal and fill in:

Click Save and enable the PayPal toggle.

Getting Your Credentials#

1. Go to developer.paypal.com
2. Log in with your PayPal Business account
3. Navigate to My Apps & Credentials
4. Under REST API apps, click Create App (or select an existing app)
5. Copy the Client ID and Client Secret from the app detail page

[!IMPORTANT] PayPal shows separate credentials for Sandbox and Live environments on the same app page. Ensure you copy the correct set. Using sandbox credentials in live mode (or vice versa) will cause all payment attempts to fail.

Setting Up the Webhook#

Commerce uses webhooks to confirm when a PayPal payment has completed.

1. Go to developer.paypal.com → My Apps & Credentials → your app
2. Scroll to Webhooks and click Add Webhook
3. Enter: https://yourdomain.com/webhooks/paypal
4. Subscribe to the event: PAYMENT.CAPTURE.COMPLETED
5. Click Save

[!TIP] Also subscribe to PAYMENT.CAPTURE.REFUNDED if you want refunds to be tracked automatically in Commerce's payment history.

How PayPal Payments Work#

Commerce uses PayPal Smart Buttons and the Orders API v2:

1. PayPal Smart Buttons are rendered inline on the invoice payment page — no redirect occurs
2. The client clicks the PayPal button and approves the payment in a pop-up overlay
3. Commerce creates an Order server-side via the PayPal Orders API
4. PayPal captures the order after client approval
5. PayPal fires the PAYMENT.CAPTURE.COMPLETED webhook
6. Commerce marks the invoice paid and sends the receipt email

The client never leaves the Commerce payment page during the PayPal flow.

[!WARNING] Pop-up blockers can interfere with the PayPal overlay. If a client reports that nothing happens when they click the PayPal button, ask them to allow pop-ups for your domain.

Sandbox Testing#

1. Enable the Sandbox toggle in gateway settings
2. Use your sandbox app credentials (Client ID and Secret from the Sandbox tab at developer.paypal.com)
3. Create a sandbox buyer account at developer.paypal.com → Sandbox → Accounts
4. Log in to sandbox.paypal.com with the sandbox buyer credentials to complete test payments

To receive sandbox webhooks, your development environment must be publicly accessible, or use a tunnelling tool (e.g. ngrok):

ngrok http 8000
# Use the ngrok HTTPS URL as your webhook endpoint in the PayPal sandbox app

Refunds#

PayPal refunds are processed via the captures/{capture_id}/refund endpoint. Partial and full refunds are supported through the Commerce refund interface (Admin → Invoice → Payments → Refund).

The refund appears in your PayPal account under Activity → Refunds within a few minutes.

Currency Support#

PayPal supports a wide range of currencies. Ensure your Commerce system currency and the client's invoice currency are supported by your PayPal account. Unsupported currencies will cause payment creation to fail with a PayPal API error logged to storage/logs/laravel.log.

Related Topics#

• Payment Gateways Overview
• Paying an Invoice (Client)
• Credit Notes & Refunds