PayPal Expanded Checkout Best Practices

Documentation Index

Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt

Use this file to discover all available pages before exploring further.

This page explains the best practices and core concepts that drive authorization, risk, and liability for card payments in Expanded Checkout. It is written for payments and backend engineers who are familiar with card-not-present processing, issuers and acquirers, and REST APIs. It focuses on elements that shape system behavior, such as data quality, 3D Secure, stored credentials, retry patterns, and related signals. It does not include step-by-step integration flows or SDK usage.

​

Why data quality drives Expanded Checkout authorization

Passing complete and accurate cardholder data is the most impactful step a partner or merchant can take to improve authorization rates. Card issuers use this data to make real-time approval decisions. Incomplete data increases false declines.

​

Important data fields

The Expanded Checkout authorization model assumes the issuer receives a complete cardholder profile. The fields below are the minimum set required for the issuer to evaluate risk correctly.

​

Recommended data fields

The following fields are not required but improve risk scoring and authorization outcomes:

​

Address Verification Service (AVS)

AVS compares the billing address provided by the customer with the address on file at the card issuer. A complete billing address is a prerequisite for AVS to act as a reliable fraud signal. Issuers use AVS as one of the primary indicators to distinguish legitimate mismatches from fraud. In Expanded Checkout, feed AVS codes into your decisioning model as nuanced signals rather than a pass or fail switch.

Best Practice: For non-matching AVS responses, prompt the customer to re-verify their billing address before declining the transaction.

Note:

• Issuers outside the US, Canada, and the UK do not consistently support AVS.
• If you use AVS filters in your fraud-prevention systems, collect the billing street and postal code so AVS can be evaluated when available.

​

3D Secure (3DS) in Expanded Checkout authorization

3D Secure (3DS) is an authentication protocol that adds a verification layer for card-not-present transactions. Correct implementation is critical for liability shift protection, regulatory compliance (EU PSD2/SCA), and fraud reduction. For more information, see:

• 3D Secure Integration
• 3DS Response Parameters

​

When Expanded Checkout relies on 3DS

Think of 3DS as a policy switch. You trade a small amount of friction for a significant liability and fraud-reduction benefit in certain scenarios.

• Mandatory: EU/EEA transactions (PSD2 Strong Customer Authentication requirement)
• Recommended: High-risk verticals (travel, digital goods, subscriptions)
• Recommended: High-value transactions (typically >$100)
• Recommended: Cross-border transactions

​

How 3DS changes liability in Expanded Checkout

Always check liability_shift first when handling a 3DS response. In Expanded Checkout, liability_shift is the primary conceptual signal: it tells you whether the issuer or the merchant is expected to absorb fraud losses for this transaction class. Your risk policies should key off this value, not just the presence of 3DS. See 3D Secure Response Parameters for more information.

​

Maximizing frictionless authentication

Frictionless authentication (no customer challenge) provides the best conversion outcome. Increasing the frictionless rate may lead to higher authorization and completion rates because fewer customers drop out during additional challenges. To maximize frictionless flow, send the following data in your 3DS request:

• Billing and shipping address
• Customer email and phone
• IP address
• Account age and purchase history indicators

​

Stored credentials and card-on-file

Stored credentials (card-on-file) extend a one-time card payment into an ongoing, reusable payment relationship. The way you represent customer-initiated transactions (CIT) and merchant-initiated transactions (MIT) in Expanded Checkout affects authorization rates and customer experience. Merchant-initiated authorization can improve significantly when CIT and MIT flags are set correctly and you pass the appropriate network transaction references. See SCA payment indicators for more information on Strong Customer Authentication.

​

Customer-Initiated Transactions (CIT)

A CIT occurs when the customer is actively participating in the checkout, such as one-click checkout with a saved card. In most Expanded Checkout integrations, the customer completes 3D Secure authentication on the first transaction before storing credentials for future use. Initial authentication improves MIT authorization and shifts liability away from the merchant.

• Authenticate the first CIT with 3DS when storing credentials for future use.
• Set stored_credential.payment_initiator = CUSTOMER.
• Set stored_credential.payment_type = ONE_TIME or RECURRING.
• Store the network_transaction_reference returned from the first CIT response. You need this value for all future MITs.

​

Merchant-Initiated Transactions (MIT)

A MIT is an automated charge without active customer participation, such as a subscription renewal or auto-top-up. Successful MIT behavior depends on carrying forward a trusted reference to the original CIT.

• Include previous_transaction_reference from the original CIT. Missing references reduce MIT authorization rates.
• Set stored_credential.payment_initiator = MERCHANT.
• Set stored_credential.usage = SUBSEQUENT.
• Set stored_credential.payment_type = RECURRING or UNSCHEDULED.

​

Network transaction reference priority

In Expanded Checkout, network transaction references carry the history of a cardholder’s prior approvals. Use the strongest available reference to improve MIT authorization rates.

1. First Priority: previous_transaction_reference (from PayPal CIT)
   • PayPal manages CIT reference retrieval automatically
   • Highest authorization rates
2. Second Priority: previous_network_transaction_reference (from a non-PayPal PSP)
   • Use when the initial CIT was processed outside of PayPal
   • Include all relevant network data fields

​

Response code handling

Expanded Checkout exposes issuer and system response codes as signals, not just errors. Proper response code handling determines when to retry, when to switch payment methods, and when to stop the flow. It also shapes how you communicate with customers and protects your overall authorization rates.

​

Soft declines (retryable)

Soft declines represent temporary or recoverable conditions where a retry may succeed if you adjust timing, amount, or funding source.

​

Hard declines (do not retry)

Hard declines indicate a terminal decision from the issuer or scheme. Additional retries with the same card are unlikely to succeed and can add risk or noise.

​

System and technical errors (retry with same idempotency key)

​

Customer messaging guidelines

Do:

• Be specific but non-technical in customer-facing messages.
• Provide clear next steps, such as “Try a different card” or “Contact your bank”.
• Offer alternative payment methods.

Do not:

• Expose technical error codes or internal decline reasons.
• Reveal fraud detection logic or specific AVS/CVV failure details.
• Use vague messages such as “An error occurred.”

Security note: Revealing fraud logic helps fraudsters circumvent detection systems. Always use generic messaging for fraud-related declines.

​

How Expanded Checkout handles declines and retries

Payments that are initially declined may be soft declines that can succeed on retry. A well-implemented retry strategy can recover significant revenue, particularly for subscription businesses.

​

Idempotency and safe retries

Idempotency keys are the core mechanism that lets Expanded Checkout support safe retries without creating duplicate charges.

• Reusing the same key preserves a single logical transaction, even if the request is sent multiple times, and adds a safety layer around your retry sequence.
• Most merchants apply idempotency keys to all state-changing operations, including create, authorize, capture, refund, and void.
• Idempotency keys are valid for 24 hours. After 24 hours, a reused key is treated as a new transaction.

​

Subscription retry schedule

For recurring billing failures, use a graduated retry schedule with customer communications at each step. Expanded Checkout does not enforce a specific retry schedule. The following pattern illustrates a common approach that balances recovery and customer experience for recurring payments:

​

Guidelines

• Maximum retries: Most merchants attempt 4–5 retries before cancelling the subscription.
• Hard declines: In practice, hard declines are treated as terminal decisions, so merchants typically stop retries and ask the customer to update their payment method.
• Backup payment method: After the second failed retry, it is common to prompt for a backup payment method rather than waiting until the final attempt.
• Time and day optimization: Many merchants distribute retries across different times of day and days of the week, since balances and issuer risk posture vary over time.

​

How Expanded Checkout keeps stored cards up to date

Stored cards introduce risks when they stop working after reissues, expirations, or other card updates. This section explains how network tokenization and the real-time account updater help keep stored payment methods usable over time while reducing declines.

​

Network tokenization

Network tokenization replaces a card’s Primary Account Number (PAN) with a network-issued token that remains valid even when the physical card expires or is reissued. Implementation options:

• PayPal Vault: PayPal manages tokenization end-to-end. Recommended for most partners and merchants. Save Payment Methods
• Third-Party Tokens: Use your own network tokens with PayPal. Network Token Processing

​

Real-Time Account Updater (RTAU)

RTAU proactively updates stored card information when cards are replaced, expired, or reissued by the card issuer. This can improve auth rates on recurring and stored-credential transactions. RTAU is valuable for:

• Subscription and recurring billing businesses
• Merchants storing payment methods for repeat customers

See Real-Time Account Updater Documentation for more information.

​

Security and compliance

This section outlines the key security and compliance expectations for integrating with Expanded Checkout.

​

TLS requirements

Expanded Checkout integrations must follow PayPal’s current HTTPS and TLS standards for all API traffic. For the latest requirements on supported TLS versions, cipher suites, and certificate expectations, see:

• PayPal security guidelines for developers
• Security guidelines and best practices

​

API key management

• Store API credentials in environment variables. Never hard-code them.
• Use separate credentials for sandbox and production environments.
• Rotate keys every 6–12 months.
• Never commit credentials to version control or share through email or chat.
• Apply IP restrictions and least-privilege access principles.

​

Authentication and session security

• Passwords must be at least 6 characters, contain alphanumeric characters, and be validated against a list of common passwords.
• Passwords must be transmitted over HTTPS and stored using a non-reversible hashing method, such as bcrypt with a unique salt per user.
• Session tokens must be cryptographically strong, transmitted only over secure sessions, and re-authenticated after 15 minutes of inactivity.
• Implement controls to prevent brute force attacks on login credentials, including account lockout and CAPTCHA mechanisms.

​

Fraud prevention

Implement multiple layers of fraud prevention to protect your integration and your customers:

1. reCAPTCHA — Prevents bot-based card testing attacks. Google reCAPTCHA
2. FraudNet — PayPal’s device fingerprinting SDK for risk analysis. FraudNet Integration
3. Velocity Limits — Limit transactions per card, IP address, and email address to detect unusual patterns.
4. AVS/CVV Verification — Always collect and verify. Decline after multiple consecutive failures.
5. Fraud Protection Advanced (FPA) — ML-powered fraud detection and behavioral analytics. FPA Documentation

​

Anti-phishing and site security

• Collect login credentials only on HTTPS pages using Extended Validation (EV) certificates.
• Maintain a process to proactively monitor for and take down spoofing and phishing sites.
• Provide a mechanism for customers to report suspected spoof sites.
• Protect against Cross-Site Scripting (XSS) and Cross-Site Request Forgery (XSRF) with appropriate framework controls. Test periodically with commercial tools, especially on new code deployments.
• Maintain a vulnerability management process covering infrastructure patching and application library updates, with patches prioritized by criticality.

​

Monitoring and diagnostics

This section describes how to use monitoring and diagnostics to understand Expanded Checkout behavior and authorization patterns in production.

​

Decline reason targets

​

Critical alerts

Set up real-time alerting for the following thresholds:

​

P0: Page immediately

• Authorization rate drops below 75%.
• Overall error rate exceeds 10%.
• Decline volume increases by more than 50% in 1 hour.

​

P1: Warning

• Authorization rate drops more than 5% vs. 7-day average.
• Webhook endpoint returns more than 5% errors.
• Any single decline code increases by more than 20%.

​

Diagnostic tools

• Decline Analysis Reports: Access via PayPal Business account under Reports > Decline Analysis. See the Decline Analysis documentation for more details.

​

Webhook implementation

Webhooks are mandatory for production integrations. They are required because customers may not return to the success page, and many payment events are asynchronous, such as 3D Secure authentication, Automated Clearing House (ACH) payments, and disputes.

​

Requirements

• HTTPS endpoint, publicly accessible, returning a 2xx status within 5–10 seconds.
• Process webhooks asynchronously — do not block the response.
• Verify HMAC signatures on every incoming webhook to confirm it originated from PayPal.
• Implement idempotent webhook processing — PayPal will retry failed deliveries up to 25 times with exponential backoff.

​

Critical events to handle

​

Glossary

​

Related resources

• PayPal Developer Security Guidelines
• 3D Secure Integration
• SCA payment indicators