Upgrade your Website Payment Standard integration

UpgradeCurrent

If you have a Website Payment Standard integration, PayPal recommends upgrading to PayPal Commerce Platform. Upgrading to PPCP have following benefits:

Accept Venmo, Apple Pay, Pay Later, and other alternative payment methods your customer prefer. *Availability may vary based on your region.
Mobile-optimized buyer experience that works seamlessly across all devices, capturing the growing mobile commerce market.
Enhanced fraud protection and PCI-DSS compliance with PayPal’s latest security infrastructure.
Hero Section Image

Get Started

Prerequisites

Before starting the migration, ensure you have:

  • Developer Account: Sign up for a PayPal developer account if you don't have one
  • REST App Creation: Create apps in the PayPal Developer Dashboard to obtain client credentials
  • Technical Requirements:
    • HTTPS-enabled server for webhook endpoints
    • Ability to make server-side HTTP requests
    • Database to store merchant credentials and transaction data
1

Identify WPS Integration

WPS 3rd Party Cart - Cart Upload

This implementation sends an entire shopping cart to PayPal in one HTML form submission. All items, quantities, and prices are included as hidden form fields.

WPS Buy Now - Platform-Managed Cart

Your platform maintains the shopping cart internally in your database. When checkout occurs, you send a single "Buy Now" button to PayPal with just the cart identifier and total amount. PayPal sees this as a single item purchase, while your platform retains all the detailed cart information.

WPS 3rd Party Cart Example Code
Deprecated
1

2
3
4
5
6
7
8
9
10
WPS Buy Now Example Code
Deprecated
1

2
3
4
5
6
7
8
9
10
2

Map WPS Parmeters to PPCP Structure

Understand how your existing WPS data fields translate to the new PPCP JSON structure. PPCP uses a hierarchical JSON structure instead of flat form fields. Proper mapping ensures no data is lost during migration and maintains transaction integrity.

Parameter Mapping Reference Table

WPS Parameter PPCP Field Notes
business payee.email_address or payee.merchant_id Identifies the receiving merchant account
item_name_x items[x].name Product name, max 127 characters
amount_x items[x].unit_amount.value Price per unit, must be string format
quantity_x items[x].quantityMust be string format in PPCP
currency_code amount.currency_code3-letter currency code (USD, EUR, etc.)
custom custom_idYour platform's internal reference (max 255 chars)
invoice invoice_idUnique invoice number
shipping amount.breakdown.shipping.valueShipping cost component
return application_context.return_urlWhere to send buyer after approval
cancel_return application_context.cancel_url Where to send buyer on cancellation
WPS vs PPCP API Payload Structure
WPS API Payload Example
Deprecated
1

2
3
4
5
6
7
8
9
10
3

Set Up Partner Platform Authentication

Implement secure authentication mechanisms for both platform-level and merchant-specific API calls. PPCP uses OAuth 2.0 for platform authentication and a special assertion header for merchant operations. This dual-authentication model allows your platform to act on behalf of multiple merchants securely.

Generate Platform Access Token

This token authenticates your platform with PayPal's API. It's required for all API calls and expires after 8-9 hours.

Generate Platform Access Token Code Example
Upgraded
1

2
3
4
5
6
7
8
9
10
4

Implement Partner Referrals API for Merchant Onboarding

Replace manual merchant PayPal email collection with automated, permission-based onboarding. The Partner Referrals API enables programmatic merchant onboarding with proper permissions, eliminating manual processes and ensuring your platform has the necessary access to process payments on behalf of merchants.

Create Partner Referral

Generate a unique URL where the merchant will grant permissions to your platform:

Create Partner Referral Example Code
Upgraded
1

2
3
4
5
6
7
8
9
10
4

Migrate Checkout Flow

Replace HTML form submissions with secure API calls and modern JavaScript SDK integration. The new checkout flow provides better security, more payment options, and complete control over the payment process while maintaining PCI compliance.

WPS Cart Upload Migration

This section shows the complete transformation from legacy HTML forms to modern API integration:

WPS Example Code
Deprecated
1

2
3
4
5
6
7
8
9
10
PPCP Frontend JavaScript Example Code
Upgraded
1

2
3
4
5
6
7
8
9
10
PPCP Backend Order Creation Example Code
Upgraded
1

2
3
4
5
6
7
8
9
10
Order Capture

Complete the payment after buyer approval. This is the final step that actually moves money.

PPCP Backend Order Capture Example Code
Upgraded
1

2
3
4
5
6
7
8
9
10
6

Replace IPN and PDT with Webhooks

Replace manual merchant PayPal email collection with automated, permission-based onboarding. The Partner Referrals API enables programmatic merchant onboarding with proper permissions, eliminating manual processes and ensuring your platform has the necessary access to process payments on behalf of merchants.

Create Partner Referral

Generate a unique URL where the merchant will grant permissions to your platform:

WPS IPN Example Code
Deprecated
1

2
3
4
5
6
7
8
9
10
PPCP Webhook Example Code
Upgraded
1

2
3
4
5
6
7
8
9
10
Set Up Webhook Configuration

You can either set up webhook programmatically or manually via PayPal Developer Dasbhoard.

Webhook Configuration Example Code
Upgraded
1

2
3
4
5
6
7
8
9
10
PDT to API Response Migration

Migrate legacy PDT handler to modern Webhook handler with signature verification.

WPS PDT Example Code
Deprecated
1

2
3
4
5
6
7
8
9
10
PPCP Webhook Example Code
Upgraded
1

2
3
4
5
6
7
8
9
10
7

Test Your Integration

Test these scenarios to ensure complete coverage:

Test Scenario

Test Steps

Expected Result

Validation Points

Successful Payment

  1. Create order

  2. Approve with test account

  3. Capture payment

Order captured successfully

  • Order status = COMPLETED

  • Webhook received

  • Database updated

  • Platform fee collected

Cancel Payment

  1. Create order

  2. Click cancel at PayPal

Return to cancel URL

  • Order status remains CREATED

  • No capture attempted

  • Redirect works correctly

Validation Error

  1. Create order with mismatched totals

Order creation fails

  • 422 error returned

  • Error details provided

  • No order created

Refund Process

  1. Complete payment

  2. Issue refund via API

Refund successful

  • Refund webhook received

  • Database updated

  • Merchant balance adjusted

Merchant Onboarding

  1. Create referral

  2. Complete signup

  3. Grant permissions

Merchant onboarded

  • MERCHANT.ONBOARDING.COMPLETED webhook

  • Permissions verified

  • Merchant can process payments

Multiple Items

Add 10+ different items to cart

All items display correctly

  • Items array properly formatted

  • Totals calculate correctly

  • All items shown at PayPal

Platform Fees

Create order with 10% platform fee

Fee collected correctly

  • Fee shown in capture response

  • Settlement breakdown correct

  • Platform account credited

Webhook Retry

  1. Fail webhook processing

  2. Wait for retry

Webhook retried automatically

  • Retry received with same event ID

  • Prevents duplicate

  • Eventually processes successfully

Currency Support

Test with other currencies you support

Correct currency handling

  • Currency codes accepted

  • Decimal places correct

  • Exchange rates applied (if applicable)

Error Recovery

  1. Timeout during capture

  2. Retry capture

Idempotent handling

  • Second capture returns same result

  • No duplicate charge

  • PayPal-Request-Id prevents double processing

Need additional troubleshooting help? Check our detailed FAQ page.

Having Issues?

Contact a Payment Specialist who can guide you through the upgrade process or call us at (888) 429-3035.

Docs
OnlineIn-PersonMultiparty3rd-partyPayoutsDisputesReportsIdentityTrackingArchive
Tools
Sandbox API executorDemo portalNegative testingCodespacesVS Code ExtensionCredit card generatorWebhooksAPI StatusSecure file transfer
APIs & SDKs
REST APIsJavaScript SDKNVP/SOAP APIsDonate SDKBraintree Graph
Community
Community homeBlogEventsChampionsVideos
© PayPal 1999–2024
ReferencePayPal.comPrivacyCookiesSupportLegalContact

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more