PayPal API Integration: A Complete Guide for UK Businesses

The PayPal API covers three distinct use cases that are often confused with each other: accepting payments from customers, paying money out to sellers or contractors, and managing recurring subscription billing. Each uses different API endpoints, different authentication flows, and suits different business models. This guide covers how the PayPal API works, which product is right for your use case, how authentication works, and what a production-ready integration looks like.

PayPal API products — which one do you need?

Orders API (inbound payments). The modern PayPal checkout integration. When a customer clicks Pay with PayPal on your platform, the Orders API creates the order, handles the PayPal authentication flow, and confirms the payment. Used on custom platforms and bespoke applications where a PayPal plugin isn’t available or doesn’t fit the payment flow. If you’re on WooCommerce or a standard ecommerce platform, the plugin handles this and you don’t need a custom integration.

Payouts API (outbound payments). Paying multiple recipients programmatically — marketplace sellers receiving their share of a sale, affiliates receiving commission, contractors receiving payment. Recipients must have a PayPal account; you pay to their PayPal email address or PayPal account ID. PayPal charges 2% per payout, capped at £1 in the UK. This is the most common custom PayPal build for businesses that aren’t on standard ecommerce platforms.

Subscriptions API (recurring billing). PayPal Billing Plans for recurring subscription payments. A customer authorises a billing agreement and PayPal charges them on the billing schedule automatically. Less common than Stripe Billing for SaaS, but relevant for businesses whose customers specifically prefer PayPal for subscriptions — certain demographics and markets where PayPal trust is high.

Pay Later / Pay in 3. PayPal’s buy now pay later offering. Surfacing Pay in 3 as a checkout option requires specific API integration — it’s not automatically available through standard PayPal checkout plugins and needs custom implementation to display correctly alongside other payment options.

How PayPal API authentication works

The PayPal REST API uses OAuth 2.0 client credentials authentication. You create a PayPal Developer App in the PayPal Developer Dashboard, which gives you a Client ID and Client Secret. These credentials are exchanged for a Bearer access token, which is then used in the header of every API request.

Access tokens expire after a set period (typically 9 hours). A well-built integration caches the token for its valid lifetime and requests a new one automatically when it expires, rather than fetching a new token on every API call.

PayPal maintains separate sandbox and production environments, each with their own credentials. All development and testing happens in sandbox — it behaves identically to production but uses test accounts rather than real money. The switch to production is simply a matter of using the production credentials and endpoint URL.

Both the Client ID and Client Secret must be stored server-side and never exposed in client-facing code. The PayPal JavaScript SDK (used for rendering the PayPal button in checkout flows) uses only the Client ID — which is safe to expose client-side — and handles the customer-facing authentication flow separately from the server-side API calls.

The Orders API payment flow

For custom checkout integrations, the Orders API flow works as follows. When a customer initiates a PayPal payment, your server creates an order via the Orders API — specifying the amount, currency and any purchase units (line items). PayPal returns an order ID. The client-side PayPal JavaScript SDK uses this order ID to launch the PayPal payment popup or redirect, where the customer authenticates with their PayPal account and approves the payment.

When the customer approves, the SDK fires an event on your page. Your client-side code sends the order ID to your server. Your server calls the Orders API to capture the payment — this is the step that actually moves the money. PayPal confirms the capture and returns the payment details. Your server updates your order status and the customer sees a confirmation.

The capture step is important. An approved PayPal order is not a completed payment until it is captured. A common mistake in custom integrations is treating the customer approval event as payment confirmation without completing the capture. The integration must capture the order server-side before treating the payment as complete.

Webhooks and event handling

PayPal sends webhook events to a URL you configure for all significant payment events. For checkout integrations: payment capture completed, payment capture denied, refund completed. For subscriptions: subscription activated, payment completed, subscription cancelled, payment failed. For disputes: dispute created, dispute resolved.

Webhook signature verification is essential. PayPal signs every webhook with credentials tied to your app. The integration must verify this signature before processing any webhook event — rejecting unverified requests prevents malicious actors from spoofing payment confirmation events.

PayPal webhooks can occasionally be delayed or delivered out of order. The integration should handle idempotency — if the same webhook event is received twice, processing it twice should not cause duplicate actions in your system. Storing processed webhook IDs and checking for duplicates before processing is the standard approach.

PayPal fees — what to expect

PayPal’s fee structure is important to understand before committing to it as a payment method, particularly for payout-heavy use cases.

Receiving payments: approximately 2.99% + 49p per transaction for UK PayPal payments. Higher than Stripe’s standard rate of 1.5% + 20p for European cards. For a £100 payment, PayPal costs £3.48 vs Stripe’s £1.70. The gap is meaningful at volume.

PayPal Payouts: 2% per payout, capped at £1 per transaction in the UK. Paying a seller £20 costs 40p. Paying a seller £100 costs £1 (at the cap). For low-value high-volume payouts, the percentage cost is high. For higher-value payouts, the cap makes it more reasonable.

For the full service details, see the PayPal API integration service. For the Payouts API specifically, see PayPal Payouts API integration. For how PayPal compares with Stripe, see PayPal vs Stripe. For what the build costs, see PayPal API integration cost.

PayPal vs Stripe for UK businesses — the headline comparison

The most common question when PayPal comes up as a payment option is whether it’s needed alongside Stripe, or instead of it. The short answer for most UK businesses: Stripe for the payment infrastructure, PayPal as an additional option for customers who specifically prefer it.

PayPal has a trust advantage with certain demographics — particularly older buyers, customers who are nervous about entering card details on an unfamiliar website, and anyone who has been using PayPal for twenty years and considers it their default payment method. Offering PayPal alongside card payments typically increases checkout conversion for these audiences. The additional integration cost is usually justified if a meaningful segment of your customers falls into this category.

For businesses where PayPal is the primary payment method rather than a secondary option — marketplaces where sellers want to receive PayPal payments, platforms operating in markets where PayPal is dominant, businesses whose customer base is heavily PayPal-oriented — the custom integration is the main event rather than an add-on. See PayPal vs Stripe for the full comparison.

PayPal Payouts vs Revolut for paying people out

Both PayPal Payouts and the Revolut Business API solve the same problem — paying multiple recipients programmatically. The key difference is the destination. PayPal Payouts sends money to a PayPal account (identified by email address). Revolut Business API sends money to a UK bank account (sort code and account number).

For marketplace sellers who are already set up to receive PayPal payments and expect to be paid via PayPal, the Payouts API is the natural choice. For trade-in businesses, contractor platforms, or any use case where the recipient would rather receive a bank transfer than a PayPal payment, the Revolut API is typically better. See the Revolut Business API integration service for the bank transfer payout approach.

Testing with the PayPal sandbox

PayPal’s sandbox environment is a full replica of the production API with test accounts and test credentials. Sandbox buyer and seller accounts can be created in the PayPal Developer Dashboard — these behave like real PayPal accounts for testing purposes, allowing end-to-end testing of the full payment, payout or subscription flow.

One practical note: PayPal’s sandbox can occasionally be slower or less reliable than their production environment, and some webhook events behave slightly differently. Testing the full webhook flow in sandbox is important, but real-world production testing with a small number of real transactions is also valuable before full deployment.

If you need help with a custom API integration for your website or business application, I can help. I build bespoke API integrations for UK businesses. See API integration pricing or get in touch to discuss your project.

Need a custom integration built?

I build custom API integrations — Stripe, Companies House and bespoke data pipelines. Reliable, well-documented, no agency overhead.

Discuss your project →