The complete guide
PayPal integration: the complete guide
Updated November 18, 2026 · Published by Danny Rathod, Founder, StackLift AI. Written with AI assistance; how we make content.
Short answer
A PayPal integration lets customers pay with their PayPal balance, bank, or card inside your checkout. Your server creates an order through PayPal's REST API, the customer approves it, and your server captures the payment and listens for webhooks. Most of the work is capture logic, webhook handling, refunds, and testing in the sandbox.
What does a PayPal integration do?
PayPal is a payment option many customers already trust. Adding it often lifts checkout completion for shoppers who do not want to type card details, and it gives you a second route when a card fails.
- PayPal buttons at checkout, on product pages, or in the cart.
- One-time payments and, where your account supports it, recurring billing.
- Refunds and partial refunds from your admin.
- Order and shipping details passed from your store.
- Payment status sent back to your order records.
Many products offer PayPal next to cards. See Stripe for the card side.
How does a PayPal integration work?
Your server authenticates to PayPal's REST API with a client ID and secret and receives a short-lived access token. It then creates an order with the amount and items. The customer approves it in a PayPal window, and your server captures the funds.
PayPal sends webhook events, such as a completed capture or a refund, and each event can be verified. PayPal provides separate sandbox accounts for buyers and sellers, with sandbox credentials and a different base URL from live.
Because approval and capture are separate steps, an approved order is not yet money in your account. Treat the order as paid only after capture succeeds.
What data moves, and in which direction?
| Data | Direction | How often |
|---|---|---|
| Order amount, items, and shipping | Your app to PayPal | Per checkout |
| Customer approval | PayPal to browser to your app | Per checkout |
| Capture request and result | Your app and PayPal | Per order |
| Refund requests | Your app to PayPal | Per refund |
| Capture, refund, and dispute events | PayPal to your app (webhooks) | As events happen |
What drives the effort of a PayPal integration?
The typical effort shown above covers a standard checkout. It grows with the points below. For ranges by project type, see ecommerce cost.
- Checkout design: buttons, pay later options, or a full redirect.
- Subscriptions or one-time payments only.
- Multiple currencies and rounding rules.
- Webhook verification and retry handling.
- Refund, dispute, and seller-protection evidence flows.
- Syncing with your order system and accounting.
- Sandbox and live environment setup.
What are the common PayPal integration pitfalls?
- Mixing sandbox and live credentials or base URLs, which returns authorization errors.
- Treating an approved order as paid before capture.
- Rounding errors when totals do not match to the cent.
- Testing webhooks with the simulator only. Simulated events can fail signature checks, so run real sandbox payments too.
- Registering webhooks on the wrong app, so events never arrive.
- Ignoring disputes, which carry deadlines for evidence.
Decide early what your orders look like when a payment is pending, captured, refunded, or disputed. A small state table agreed with your finance and support teams prevents many arguments later. It also gives testers a clear list of cases to run in the sandbox before launch. Keep PayPal reference IDs on every order, so support can find a payment in seconds.
Build it custom or use a no-code connector?
| Need | Ready connector or plugin | Custom integration |
|---|---|---|
| PayPal on a standard store | Platform plugin often enough, see Shopify or WooCommerce | Not needed |
| Log PayPal sales to other tools | Zapier or Make | Overkill |
| Checkout in your own app | Not enough | Needed |
| Custom order, refund, and ledger rules | Rarely fits | Needed |
How do you test and launch a PayPal integration?
- Create sandbox buyer and seller accounts and run a full purchase.
- Test approval, cancel, decline, and capture failure paths.
- Run refunds and partial refunds and check your order status.
- Send real sandbox events to your webhook and confirm verification.
- Replay an event and confirm no duplicate fulfillment.
- Swap in live credentials only in production and make one small real payment.
- Watch errors for the first days, with rollback ready.
How does StackLift scope a PayPal integration?
A senior architect reviews the scope before it becomes a commitment. The free estimate prices payments feature by feature. Agents work on feature branches and never touch production secrets, and CI/CD, observability, and rollback are part of the plan from sprint one.
Questions people ask
Should I add PayPal if I already use Stripe?
Many customers prefer PayPal, so offering both can help. It does add a second system to test, reconcile, and support, so keep one internal payment model.
What is the difference between approving and capturing a PayPal order?
Approval means the customer agreed to pay. Capture is when your server collects the funds. Mark the order paid only after capture succeeds.
Can PayPal handle subscriptions?
It offers recurring billing, but features vary by account and country. Confirm what your account supports before designing plans.
How do I test PayPal without real money?
Use the sandbox, with its own buyer and seller accounts and credentials. Test with real sandbox payments, not only simulated webhook events.
What happens when a customer opens a PayPal dispute?
PayPal notifies you and sets a deadline to respond with evidence. Your admin should record the dispute and make order, shipping, and communication records easy to pull.
Is PayPal safe for card data?
Customers pay inside PayPal's own window, so card details do not pass through your servers. You still protect your credentials, verify webhooks, and keep your checkout page secure.