PayPal
PayPal lets international shoppers pay with a PayPal balance or card. TakeTheme uses PayPal's REST API: the shopper approves the payment at PayPal, and the funds are captured immediately afterwards.
Connecting
Settings → Payments → PayPal.
| Credential | Required | Where to find it |
|---|---|---|
| Client ID | Yes | PayPal Developer dashboard → your app |
| Client Secret | Yes | Same app |
| Webhook ID | — | Created when you register a webhook in PayPal; needed to verify webhook signatures |
| Setting | Default | What it does |
|---|---|---|
| Environment | sandbox | sandbox for testing, live for real money |
| Send payment confirmation email | on | Emails the customer when payment succeeds |
| Notify on payment failures (emails) | empty | Alerts your team when a checkout fails |
| Auto mark orders as paid | on | Not currently enforced — a confirmed payment always marks the order paid |
Sandbox credentials only work with sandbox, live credentials only with live. Switching the environment without swapping the credentials makes every payment fail. Remember to flip this to live before you launch — it defaults to sandbox.
Payment flow
PayPal is confirmed through two independent paths, which is why it's the most resilient of the gateways:
- Webhook — PayPal posts to
POST /v1/webhooks/paypal. Handled events: order approved, capture completed, capture denied, capture refunded. - Return URL — when the shopper lands back on your store, TakeTheme asks PayPal for the order's status directly. If it's approved but not yet captured, TakeTheme captures it right there and creates the order.
Whichever arrives first wins; the other becomes a no-op. A duplicate capture cannot record a second transaction, and the order is only ever created once.
Register your webhook in PayPal and paste the resulting Webhook ID into the credentials form. Without it, webhook signatures can't be verified — you'll still get orders via the return path, but you lose the confirmation route for shoppers who close the tab before being redirected.
Refunds
Refunding in TakeTheme records the refund locally — it does not call PayPal's refund API. Issue the refund from your PayPal account, then record it on the order.
TakeTheme does listen for PayPal's PAYMENT.CAPTURE.REFUNDED webhook, so a refund you issue at PayPal is logged against the payment.
Troubleshooting
Payments work in testing but fail after launch.
The Environment setting is still sandbox, or you swapped one credential and not the others.
Some orders appear late. That's the return-URL path doing the capture on the shopper's redirect rather than the webhook. Register a webhook and store its ID for the faster path.
A refund at PayPal isn't reflected on the order. Check the webhook is registered and the Webhook ID is stored — that event is how TakeTheme learns about refunds made outside the dashboard.