Integrating with PayPal

On this page:

PayPal Transaction Steps

The following Opayo Direct PayPal transaction steps take place automatically. Although they take time to explain, from your customer’s perspective their experience of paying with PayPal is near seamless.

Step 1. Checkout Options

Your customer is ready to check-out their basket.

Express Checkout

Before entering their details, you can offer an Express Checkout option using PayPal or an alternative payment processor.

Payment choice buttons for PayPal or Visa, Mastercard, and American Express

Step 2. Payment Options

When the Express Checkout is not available or is not selected, your customer must enter their details. The input must be formatted to PayPal’s requirements as follows:

PayPal's validation



Max Length

Allowed Values








Valid email characters




















2 digit ISO 3166-1 code




Mandatory for US Addresses






Your customer now choses from the available card and PayPal payment methods.

Payment choice buttons for PayPal or Visa, Mastercard, and American Express

  • When your customer chooses a payment method other than PayPal, then the 3D- Authentication commences. Your customer enters their card number, expiry date, CV2 etc., and the full server-to-server POST is sent.
  • The PayPal payment option is referred to as Mark integration. It follows the Express Checkout flow and from an Opayo perspective, is almost identical.

Step 3. Choosing PayPal

When your customer chooses to pay with the PayPal Mark or Express Checkout:

  • The Opayo Direct registration POST is sent with the CardType field set to PAYPAL. No other card details are sent.
  • The POST includes a PayPalCallbackURL field. This points to a script on your site to handle the completion process.
Note: Mark implementations require the full Billingxxxx and Deliveryxxxx sections to be completed. Leave these empty for Express Checkout.

The POST is addressed to the Opayo Direct Transaction Registration URL for validation. If valid and found correct, our servers construct a message to send to the PayPal servers.

  • For Express Checkouts, a message is sent to ensure the customer enters their address when they reach the PayPal screens.
  • Mark checkouts already contain the customer’s information and the customer does not need to select an alternative address once on the PayPal screens.

The PayPal servers return a unique token to Opayo. We record it in the Opayo database against the transaction, before returning the Opayo Direct response to you. 

Step 4. On PayPal’s Site

You now redirect your customer’s browser to the PayPalRedirectURL value found in the Opayo Direct response.

Your customer then logs into PayPal and choses a payment method and for:

  • Express Checkouts they must enter or select a delivery address.
  • Mark transactions, the address selection is disabled.

Your customer confirms their details and PayPal exchanges information with Opayo. We then build a response message to POST via your customer’s browser to the PayPalCallbackURL that you provided in the original Opayo Direct POST. The URL is also the destination in the event of errors.

Step 5. Completing the Transaction

You can check everything and determine if you want to proceed with the transaction. For example, when the AddressStatus is UNCONFIRMED, and the PayerStatus is UNVERIFIED, you may not want to continue without PayPal Seller Protection?

  • When you DO want to proceed, you should store the delivery address details in your database (if they differ from those supplied), and build a Direct PayPal Capture message with the Accept field set to YES (Complete a PayPal Transaction). POST this to the Direct PayPal Completion URL.
  • If you do NOT want to proceed, you should build a Direct PayPal Capture message with the Accept field set to NO (Complete a PayPal Transaction). POST this to the Direct PayPal Completion URL. You can then redirect the customer back to select a different payment method and begin the Opayo Direct process again.

We will validate the POST and if correct, forward it to PayPal.

PayPal will now complete the transaction and return the details to us. We will then update the transaction with the required IDs and build a Direct Completion response to POST back to the PayPal Completion URL.

You can now display your transaction completion page to your customer.


You can email the Opayo Support team for help with your debugging issues.

Related Pages