PayPal Processing [DEPRECATED]

Note: This page describes a legacy PayPal integration that uses a redirect method called the PayPal Express Checkout flow (Redirect). This redirect method is no longer supported.

PayPal is the faster, safer way to pay and get paid on-line, via mobile devices and in store. The service allows people to send money without sharing financial information, with the flexibility to pay using their account balances, bank accounts, credit cards or promotional financing.

PayPal integration is handled through integration with the Payment Service. There is no direct integration to PayPal.

PayPal integration is handled through integration with the Payment Service. Integration with payment service can be done by the following two ways:

PayPal Express Checkout flow (a redirect-based implementation)
PayPal SDK Javascript Smart Button (the new go-forward recommended integration)

For information on accepting payments through Venmo, a PayPal-owned payments application, see Venmo.

PayPal Full Lifecycle Flow Diagram

The following flow diagram shows the series of calls and events for a typical transaction involving a PayPal payment

Flow Diagram for Order Canceled Because of Fraud

The following flow diagram shows the series of calls and events for an order paid by PayPal but then canceled because of the results of the fraud/risk assessment.

PayPal SDK Javascript Smart Button

With this integration, once the buyer/customer clicks on the PayPal payment method button the SDK invokes a createOrder() method and the login page pops up. Based on whether the customer approves or cancels the order, SDK will redirect to the respective urls either confirmation page or cancel page. The main advantage is that webstore doesn't needs to handle the redirects. Everything will be handled by the SDK smart button.

For detailed description and integration. Please refer to PayPal SDK JavaScript Smart Button.

PayPal Express Checkout flow (Redirect)

This PayPal Express Checkout flow (Redirect) example covers the system interactions that occur between a webstore, the Order Management System (OMS), and the Payments API. The Risk API is assumed to return Success in all the scenarios.

For a detailed diagram of the sequence of actions in PayPal Express Checkout, click here.

The Express Checkout process includes the following steps.

Set up the payment authorization. When the customer is ready to check out, the webstore submits a SetExpress request, with AddressOverride = 0 (in other words, no address information is sent in the request).
The SetExpress response returns a Token used in subsequent steps.
Redirect the customer to PayPal site.
Redirect the customer to Paypal by using the token from Step 1 with the PayPal authorization URL, for example:
https://www.sandbox.paypal.com/checkoutnow?token=EC-TOKENHERE
- If the customer doesn't approve the payment authorization, the customer is redirected to the cancel URL that you specified in the Set Express Checkout call, so you can provide a way to re-initiate authorization.
- If the customer approves the payment authorization, the customer is redirected to the return URL (specified in Set Express Checkout), appended with the token from Step 1.
Get the customer's PayerID with a GetExpress call.
The webstore submits a GetExpress request by using the Token returned in Step 1. The GetExpress response returns a PayerId that uniquely identifies the customer.
Set up the PayPal order with a DoExpress call. .
The webstore submits a DoExpress request with the Token,and PayerId, and the amount of the order. The amount must include shipping handling, and tax, and must specify the currency.
The DoExpress response call returns the TransactionId, also known as the PayPal Order Id. A successful DoExpress call places a hold on the customer account that can be released only if voided explicitly on PayPal's end.
Authorize the payment with DoAuthorize call.
The webstore submits a DoAuthorization request specifying the transaction amount of the order.
The DoAuthorization response includes a ResponseCode value with the results of PayPal's DoAuthorization processing.
Continue the process according to the ResponseCode value:
- If the value is Success or SuccessWithWarning, see Success Processing, below.
- If the value is Failure, see Failure Processing, below.
- If the value is Timeout, see Timeout Processing, below.

Note: In case of PayPal SDK smart button, there will be no redirection required and everything is handled by the smart button itself.

PayPal Express Checkout (Redirect) Easy Payments Flow

PayPal Easy Payments allows a customer to pay for a purchase with a specific amount over a specific number of months at a promotional APR. PayPal manages all credit repayment services and takes liability for non-payment. Merchants receive the full funds ins their PayPal accounts immediately upon settlement of the transaction, similar to a standard PayPal transaction, except that Easy Payments transactions are subject to additional transaction fees.

When the customer is ready to check out, the webstore submits a SetExpress request with <Installment>true</Installment>.
The SetExpress response returns a Token used in the next two steps.
Redirect the customer to PayPal site.
Redirect the customer to Paypal by using the token from Step 1 with the PayPal authorization URL for example:
https://www.sandbox.paypal.com/checkoutnow?token=EC-TOKENHERE
- If the customer doesn't approve the payment authorization, the customer is redirected to the cancel URL that you specified in the Set Express Checkout call, so you can provide a way to re-initiate authorization.
- If the customer approves the payment authorization, the customer is redirected to the return URL (specified in Set Express Checkout), appended with the token from Step 1.
Webstore submits a GetExpress request by using the Token returned in Step 1.
The GetExpress response returns a PayerId that uniquely identifies the customer.
The GetExpress response returns additional financial information
The webstore submits a DoExpress request with the Token and PayerId.
The DoExpress response call returns the TransactionId, also known as the PayPal Order Id. A successful DoExpress call places a hold on the customer account that can be released only if voided explicitly on PayPal's end.
The webstore submits a DoAuthorization request specifying the transaction amount of the order.
The DoAuthorization response includes a ResponseCode value with the results of PayPal's DoAuthorization processing.
Continue the process according to the ResponseCode value:
- If the value is Success or SuccessWithWarning, see Success Processing, below.
- If the value is Failure, see Failure Processing, below.
- If the value is Timeout, see Timeout Processing, below.

Success Processing

If the ResponseCode value is Success or SuccessWithWarning, the following steps conclude the Express Checkout flow:

The Webstore accepts the Order and send it to OMS for processing.
OMS submits a PaymentSettlement request to capture the funds.
After final line item shipment (when no further capture is necessary), OMS sends one final PaymentSettlement request with FinalDebit flag set to true. This request finalizes the funds capture, and no more capture settlement requests are possible afterwards.
The final request triggers a Payment Service void request to PayPal. The void request releases the hold on the account created by the successful DoExpress call.

Failure Processing

If the ResponseCode value is Failure, the following steps conclude the Express Checkout flow:

The webstore refuses the order and show the customer alternate payment options.
The webstore submits a PaymentAuthCancel request to release the hold on the order created by the successful DoExpress call.

Timeout Processing

If the ResponseCode value is Timeout during Express Checkout, the webstore can retry the DoAuthorization call. Radial recommends a maximum of three retry attempts, but the Payment service does not enforce a specific limit in the number of retries.

To retry after a Timeout response, the webstore submits another DoAuthorization call. (As an alternative, the webstore can accept the order and prompt the OMS to try another DoAuthorization call before the order is shipped.)

The DoAuthorization response includes a ResponseCode value with the results of PayPal's DoAuthorization processing. The next step depends on the ResponseCode value.

Success/SuccessWithWarning: see Success Processing, above.
Failure: The webstore or OMS submits a PaymentAuthCancel request to release the hold on the account created by the successful DoExpress call in Step 3.
Timeout: The webstore or OMS retries the DoAuthorization call, or submits PaymentAuthCancel request to void the Order if maximum number retries is reached.

If the maximum number of DoAuthorization retries has been reached, and the response is still Timeout, the webstore or OMS submits a PaymentAuthCancel request to void the Order.

Customer Account Hold Must Be Released

A successful DoExpress call places a hold on the customer account which can be released only if the OMS or webstore submits a PaymentAuthCancel request with TenderType=PY.

The PaymentAuthCancel happens in two different ways depending on the subsequent DoAuthorization call.

If the DoAuthorization call returns a Failure, then the OMS or webstore must submit a PaymentAuthCancel request with TenderType=PY to release the hold.
If the DoAuthorization call returns a Success or SuccessWithWarning, the OMS or webstore submits a PaymentSettlement request to capture the funds. After the final line item shipment (which means that no further capture is necessary), the OMS or webstore sends one final PaymentSettlement request with FinalDebit flag set to true, which finalizes the funds capture (no more capture settlement requests are possible afterwards). This final PaymentSettlement request automatically triggers a PaymentAuthCancel request with TenderType=PY, which releases the hold on the account.

PayPal Processing Notes

A PayPal DoExpress is valid for 60 Days. After that it expires and another DoExpress request must be sent. The value can be adjusted to 365 days.
A PayPal DoAuth is valid for 3 days. After that it expires and another DoAuth request must be sent. The value can be adjusted to 29 days.
Both DoExpress and DoAuth must be valid when a Capture Settlement call is made.

Flow Diagram: DoAuthorization Success

The following flow diagram shows the PayPal Express Checkout (Redirect) process with a DoAuthorization success.

Flow Diagram: DoAuthorization Failure

The following flow diagram shows the PayPal Express Checkout (Redirect) process with a DoAuthorization failure.

Flow Diagram: DoAuthorization Timeout

Webstore Retries Successfully

The following flow diagram shows the PayPal Express Checkout (Redirect) process with a DoAuthorization timeout, after which the webstore retries successfully.

Webstore Accepts Order and OMS Retries Successfully

The following flow diagram shows the PayPal Express Checkout (Redirect) process with a DoAuthorization timeout, after which the webstore accepts the order and OMS retries successfully.

Webstore Accepts Order and OMS Retries Unsuccessfully

The following flow diagram shows the PayPal Express Checkout (Redirect) process with a DoAuthorization timeout, after which the webstore accepts the order, OMS retries unsuccessfully, and OMS cancels the order with a PaymentAuthCancel request.

PayPal Recurring Pay Flow

The PayPal recurring pay flow consists of two processes.

Set up the Billing Agreement. This can be done with or without an initial purchase by the customer.
Capture funds during each time period specified in the billing agreement.

Set Up Billing Agreement as Part of an Initial Purchase

The webstore submits a SetExpress request with Recurring field set to true. The response contains a Token that is used in subsequent requests.
The webstore redirects the customer to PayPal's website to approve the agreement, which is valid for two years.
The webstore submits a GetExpress request, using the Token returned in the SetExpress response. The GetExpress response returns a PayerId, which uniquely identifies the customer.
The webstore submits a DoExpress request, using the Token and PayerId. The DoExpress response call returns the TransactionId, which serves as the Billing Agreement Id.
The webstore submits a CreateBillingAgreement request, using the Token from the SetExpress response. The CreateBillingAgreement response contains the Billing Agreement Id that is used to make recurring payments. The Billing Agreement Id is valid for two years.

Set Up Billing Agreement Without an Initial Purchase

The webstore submits a SetExpress request with Recurring field set to true and Amount field set to 0. The response contains a Token that is used in subsequent requests.
The webstore redirects the Customer to PayPal's website to approve the agreement.
The webstore submits a CreateBillingAgreement request, using the Token from the SetExpress response. The CreateBillingAgreement response contains the Billing Agreement Id that is used to make recurring payments. The Billing Agreement Id is valid for two years.

Capture Payments During Each Time Period of the Billing Agreement

The webstore submits a DoReferenceTransaction request with the Billing Agreement Id and payment Amount.
The webstore places the order in OMS.
After the successful DoReferenceTransaction request, OMS submits a PaymentSettlement request to capture the funds.