Radial Integration | 2016

PayPal Processing

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 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 Express Checkout Flow

This PayPal Express Checkout flow 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.

1. When the customer is ready to check out, the webstore submits a SetExpress request.

   The SetExpress response returns a Token used in the next two steps.

2. Webstore submits a GetExpress request by using the Token returned in Step 1.

   The SetExpress response returns a PayerId that uniquely identifies the customer.

3. 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.

4. 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.

5. 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.

PayPal Express Checkout 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.

1. 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.

2. Webstore submits a GetExpress request by using the Token returned in Step 1.

   The SetExpress response returns a PayerId that uniquely identifies the customer.

   The GetExpress response returns additional financial information

3. 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.

4. 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.

5. 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:

1. The Webstore accepts the Order and send it to OMS for processing.
2. OMS submits a PaymentSettlement request to capture the funds.
3. 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.
4. 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:

1. The webstore refuses the order and show the customer alternate payment options.
2. 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, the Express Checkout flow continues with the folowing steps:

1. The webstore does one of the following:
   • If the maximum number of DoAuthorization retries has been reached, the webstore submits a PaymentAuthCancel request to void the Order.
   • If additional retries are available, the webstore retries the DoAuthorization call.
   • The webstore accepts the order and prompts the OMS to try again to make another DoAuthorization call before the order is shipped.

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

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

Customer Account Hold Must Be Released

A successful DoExpress call places a hold on the customer account which can be released only if OMS submits a PaymentAuthCancel request with TenderType=PY. This can be achieved in two different ways depending on the subsequent DoAuthorization Call:

• If DoAuthorization call returns a Success or SuccessWithWarning, the OMS submits PaymentSettlement request to capture the funds. After final line item shipment (i.e. no further capture necessary), OMS sends one final PaymentSettlement request with FinalDebit flag set to true, which finalizes the funds capture (no more capture settlement requests are possible afterwards) and also trigger a PaymentAuthCancel request with TenderType=PY and will release the hold on the account.
• If DoAuthorization call returns a Failure then OMS submits PaymentAuthCancel request with TenderType=PY to release the hold.

PayPal Processing Notes

• A PayPal DoExpress is valid for 60 Days. After that it expires and another DoExpress request has to 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 has to be sent. The value can be adjusted to 29 days.
• Both DoExpress and DoAuth have to be valid when a Capture Settlement call is made.

Flow Diagram: DoAuthorization Success

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

Flow Diagram: DoAuthorization Failure

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

Flow Diagram: DoAuthorization Timeout

Webstore Retries Successfully

The following flow diagram shows the PayPal Express Checkout 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 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 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.

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

Set Up Billing Agreement as Part of an Initial Purchase

1. The webstore submits a SetExpress request with Recurring field set to true. The response contains a Token that is used in subsequent requests.
2. The webstore redirects the customer to PayPal's website to approve the agreement, which is valid for two years.
3. 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.
4. 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.
5. 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

1. 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.
2. The webstore redirects the Customer to PayPal's website to approve the agreement.
3. 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

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

PayPal Recurring Flow Diagram - With Initial Purchase

PayPal Recurring Flow Diagram - Without Initial Purchase

Copyright © 2017 Radial. All rights reserved.