Express Checkout with Payflow Gateway - Basic integration

A Sale payment action is straight forward. With a Sale payment action (TRXTYPE=S) funds are immediately captured at the time the customer places an order on the website and moved from the buyers PayPal account to the merchant’s PayPal account.

Sale is used as the payment action when merchants sell digital goods or products that they usually ship within 3-4 days of the order date.

Integration steps

  1. Meet the prerequisites.
  2. Add the in-context JavaScript.
  3. Integrate the Express Checkout basic APIs.

Prerequisites

To use the PayPal Payflow API, you must have API credentials that identify you as a PayPal business or premier account holder authorized to perform various API operations. To set up the required test accounts and credentials, see Create test accounts.

Note: Do not URL encode the request. Payflow only accepts ASCII English characters.

The endpoints for all Payflow API calls are:

Live: https://payflowpro.paypal.com
Sandbox: https://pilot-payflowpro.paypal.com

In-Context JavaScript

Include the PayPal checkout.js JavaScript on the page hosting the PayPal button. Make sure you do not download a local copy. Use the full PayPal URL for the JavaScript file as follows:

<script src="//www.paypalobjects.com/api/checkout.js" async></script> 

Basic Implementation

A basic Express Checkout integration assumes that you are sending the API calls from your own server using a <form> or <a> tag. The following integration script with setup must be loaded after the <form> or <a> tags.

<form id="myContainer" method="post" action="/checkout"></form> 
 
    <script> 
      window.paypalCheckoutReady = function () { 
        paypal.checkout.setup('<Your-Merchant-ID>', { 
            environment: 'sandbox', 
            container: 'myContainer' 
          }); 
      }; 
    </script> 
 
<script src="//www.paypalobjects.com/api/checkout.js" async></script> 

How the in-context JavaScript works

  • The setup call in the PayPal checkout JavaScript method populates a PayPal button automatically in the container specified. In the above example the container is the form itself.
  • When the button is clicked, the PayPal JavaScript uses AJAX to manage the form submit action behind the scenes. The form submit action then invokes your SetExpressCheckout code.
  • This redirects the buyer to a PayPal URL containing the appended token.
  • The PayPal JavaScript displays the PayPal payment page within a secure pop-up window on your website. The buyer can complete the PayPal checkout within the PayPal managed pop-up window overlaying your website.
  • When the buyer completes PayPal checkout, the buyer is redirected to the return URL specified in your SetExpressCheckout API call.

For more in-context integration details and options, see the Express Checkout with In-Context integration guide.

Note: If you are experiencing issues while implementing the in-context flow, please reach out to your integration engineer at PayPal for assistance.

Features and browser support

Please refer to the in-context features and browser support page to determine if your Express Checkout integration is a good candidate for the in-context checkout experience option.

In the case of all PayPal features not supported by in-context checkout, the full-page checkout flow is presented.

The Express Checkout basic integration

A basic Express Checkout integration consists of three API calls:

  1. SetExpressCheckout
  2. GetExpressCheckoutDetails
  3. DoExpressCheckoutPayment

SetExpressCheckout

A SetExpressCheckout call (ACTION=S) initiates the Express Checkout process and generates a token that is used to track the buyer through the rest of the checkout process.

Below is a simple SetExpressCheckout call containing the minimum parameters.

Note: For more information about Payflow parameters specifically for the SetExpressCheckout call (ACTION=S), see the Express Checkout for Payflow reference.

Request

USER=username
VENDOR=vendor
PARTNER=PayPal
PWD=password
TRXTYPE=S 
TENDER=P 
ACTION=S 
AMT=0.01 
CURRENCY=USD 
RETURNURL=https://example.com/return 
CANCELURL=https://example.com/cancel 
ORDERDESC=test order 
INVNUM=INX123 

The amount (AMT) of the transaction does not have to be final. Adjustments can be made later for shipping and tax, for example. RETURNURL is the URL of the payment review page on your website where the buyer confirms the order and payment. CANCELURL is the URL of the original page on the merchant’s website where the buyer initially chose PayPal as a payment type.

Response

RESULT=0 
RESPMSG=Approved 
TOKEN=EC-CK3O9GB4M911WAMPD 
CORRELATIONID=ec093d08c9f3 

The two fields to note in the response are RESULT and TOKEN. RESULT indicates the success or failure of the request. Check the Results values table, in the Payflow developer guide, for the different result codes you might receive in case of error. The TOKEN returned identifies this Express Checkout transaction with PayPal. You pass the TOKEN back to PayPal in the subsequent API calls.

Passing line item details

In the SetExpressCheckout API request, you need to pass line items to make sure the buyers can see the amount while completing the checkout at PayPal. The total amount of the transaction will not be displayed in the in-context PayPal screen if line items are not passed. This is also a recommended and ideal way of implementing Express Checkout.

Below is a snippet from an API call with all the line item parameters,

// Order totals 
AMT=13.00 
TAXAMT=6.00 
ITEMAMT=7.00 // item totals  
FREIGHTAMT=3.00 
DISCOUNT=3.00  //this will be considered as -3 as it’s a discount field. 
 
// Line item details – line item 1 
L_NAME0=Burton Lucky Pants - Women's 
L_DESC0=Item 1 desc 
L_ITEMNUMBER0=123456 
L_COST0=1.00 
L_TAXAMT0=1.00 
L_QTY0=5 
 
// Line item details – line item 2 
L_NAME1=Arbor Roundhouse CX Snowboard 2013 
L_DESC1=Item 2 desc 
L_ITEMNUMBER1=98765 
L_COST1=2.00 
L_TAXAMT1=1.00 
L_QTY1=1 
This is how the line items show up in the UI, 

Redirect the buyer to PayPal

Once you receive the SetExpressCheckout response, redirect the buyer to PayPal and append the TOKEN to the redirect URL.

Live:

https://www.paypal.com/checkoutnow?token=EC-token

Sandbox:

https://www.sandbox.paypal.com/checkoutnow?token=EC-token

Once on the PayPal payment page, the buyer does the following:

  • Logs in to PayPal.
  • Selects shipping and a funding source.
  • Continues the transaction and returns to your site.

The return URL is the URL you specified in the SetExpressCheckout API request. PayPal appends the PayerID and token to the return URL.

https://example.com /return?token=EC-7BX27754BT8623257&PayerID=UPGGM5VND8D5Q

The token is used to keep track of the transaction as a whole and the payer ID is used to track the buyer paying with PayPal.

GetExpressCheckoutDetails

The GetExpressCheckoutDetails call (ACTION=G) retrieves the buyer’s information, such as, name, email address, and shipping address, from PayPal. You can use this information then to dynamically display the shipping method and amount to the buyer when the buyer returns to your site for Payment confirmation.

Provide the token obtained from the SetExpressCheckout response in the GetExpressCheckoutDetails request.

Below is a sample request and its response containing the minimum parameters.

Note: For more information about Payflow parameters specifically for the GetExpressCheckoutDetails call (ACTION=G), see the Express Checkout for Payflow reference.

Request

USER=username
VENDOR=vendor
PARTNER=PayPal
PWD=password
TRXTYPE=S
TENDER=P
ACTION=G
TOKEN=EC-561546500C9429808

Response

RESULT=0
RESPMSG=Approved
AVSADDR=Y
AVSZIP=Y
TOKEN=EC-561546500C9429808
PAYERID=3T5GGNEZ8T33S
CORRELATIONID=96336a90caa9
EMAIL=buyer@umulla.com
PAYERSTATUS=verified
PHONENUM=408-841-8029
FIRSTNAME=Usman Adeel
LASTNAME=Mulla
SHIPTOSTREET=1 Main St 
SHIPTOCITY=San Jose
SHIPTOSTATE=CA
SHIPTOZIP=95131
SHIPTOCOUNTRY=US
DISCOUNT=3.00
SHIPTONAME=Usman Adeel Mulla
COUNTRYCODE=US
ADDRESSSTATUS=Y 

DoExpressCheckoutPayment

DoExpressCheckoutPayment call (ACTION=D) authorizes the buyer’s funding sources. In the case of a Sale transaction (TRXTYPE=S), DoExpressCheckoutPayment finalizes the transaction and moves the money to the merchant’s PayPal account.

In the request, include the final line item details, including any changes that may have occurred, for example, any additional shipping costs or taxes based on the address provided by PayPal in the GetExpressCheckoutDetails call. Also include the token and the payer ID in the DoExpressCheckoutPayment request.

Below is a sample request and response containing the minimum parameters.

Note: For more information about Payflow parameters specifically for the DoExpressCheckoutPayment call (ACTION=D), see the Express Checkout for Payflow reference.

Request

USER=username
VENDOR=vendor
PARTNER=PayPal
PWD=password
TRXTYPE=S
TENDER=P
ACTION=D
TOKEN=EC-561546500C9429808
PAYERID=3T5GGNEZ8T33S
CURRENCY=USD
ORDERDESC=test order
AMT=13.00
TAXAMT=6.00
ITEMAMT=7.00
FREIGHTAMT=3.00
DISCOUNT=3.00
L_NAME0=Burton Pants - Women's
L_DESC0=Item 1 desc
L_ITEMNUMBER0=123456
L_COST0=1.00  
L_TAXAMT0=1.00
L_QTY0=5
L_NAME1=Arbor Roundhouse CX Snowboard 2013
L_DESC1=Item 2 desc
L_ITEMNUMBER1=98765
L_COST1=2.00
L_TAXAMT1=1.00
L_QTY1=1 

Response

RESULT=0
PNREF=B1PP8B8EE9EE
RESPMSG=Approved
AVSADDR=Y
AVSZIP=Y
TOKEN=EC-561546500C9429808
PAYERID=3T5GGNEZ8T33S
PPREF=6M668496YP144384E
CORRELATIONID=e7186a87e275f
FEEAMT=0.81
TAXAMT=6.00
PAYMENTTYPE=instant
PENDINGREASON=completed 

The transaction is complete and appears in your PayPal account.

Display a Receipt or a Thank You page to the customer.

Note: Use the transaction PNREF returned in the DoExpressCheckoutPayment response as the transaction ID for processing refunds.

Feedback

Have feedback?

Let us know.