PayPal integration: complete developer guide (2026)

PayPal integration usually means the Orders API for one-off payments or Subscriptions for recurring billing. The server creates and captures the order; the browser only approves it. Webhooks keep your database in sync.

What matters in practice

• Webhooks handle asynchronous events such as refunds and disputes.
• PayPal supports multiple currencies, but your pricing and settlement currency need a deliberate policy.

How to implement it

1. Create a sandbox app. Get the client ID and secret for the sandbox environment.
2. Create the order. Resolve the cart server-side and create the order with the correct currency.
3. Approve on the client. Render the PayPal button and capture the approval.
4. Capture on the server. Verify the order status and amount before fulfilling.
5. Subscribe to webhooks. Verify the signature and handle refunds, disputes and subscription changes.
6. Test. Declines, cancelled approvals, duplicate captures and currency mismatches.

A working example

// Server route: create an order
const response = await fetch("https://api-m.paypal.com/v2/checkout/orders", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Basic ${Buffer.from(`${id}:${secret}`).toString("base64")}`,
},
body: JSON.stringify({
intent: "CAPTURE",
purchase_units: [{ amount: { currency_code: "GBP", value: total } }],
}),
});

Production checklist

Area	Check
Environment	Sandbox and live credentials separated
Amount	Resolved server-side and matched at capture
Currency	Pricing and settlement policy defined
Webhook	Signature verification and idempotency
Testing	Declines, cancellations, duplicates and refunds
Reconciliation	Daily check between PayPal and your orders

Common mistakes

• Capturing an amount sent by the client.
• Fulfilling before verifying the capture response.
• Using the live environment for testing.
• Ignoring currency conversion and settlement fees.

When this is the wrong tool

Every tool has a boundary. If the team is small, the use case is simple and the operational cost is high, a simpler stack may be better. The right choice is the one you can debug, secure and hand over without the original author.

Rollout plan

1. Prove one slice. Use PayPal integration for one real route or feature, not the whole product.
2. Set the boundary. Write down what stays on the server, what runs on the client and how data crosses the boundary.
3. Add the safety net. Types, validation, tests and error handling around the new slice.
4. Measure. Check bundle size, latency, error rate and the developer experience before expanding.
5. Document and hand over. Record the pattern, the pitfalls and the version constraints.

Testing strategy

Layer	What to test	Why
Types	Strict compile and no unjustified any	Catches contract drift early
Unit	Pure logic, validation and state transitions	Fast feedback
Integration	API, database and auth boundaries	Most production failures live here
End-to-end	The critical user journey	Proves the wiring
Operations	Logs, errors, retries and rollback	A release is not finished at deploy

Operational checklist

• Pin the runtime and dependency versions; test upgrades in a branch.
• Keep secrets on the server and validate every external payload.
• Add structured logs with a request ID, but never log tokens or personal data.
• Set a performance or bundle budget and check it in CI.
• Write a short runbook for the most likely failure.

Sources and further reading

• PayPal REST APIs (developer.paypal.com)
• PayPal webhooks (developer.paypal.com)
• PCI Security Standards Council (pcisecuritystandards.org)

Related reading

• TypeScript best practices
• Next.js deployment guide
• Web application development