How To Use Coupons, Loyalty Programs and PLCC in Express Checkout

This guide describes how to handle coupons, loyalty programs, private label credit cards (PLCC) and co-branded payment cards in Express Checkout.

For demonstration purposes, this guide makes requests using the PayPal Sandbox. For information on making calls using the NVP/SOAP APIs, including obtaining the needed API credentials and how to make test calls using the Sandbox, see Apps 101.

The figure below shows the flow of calls through a typical Express Checkout transaction. It illustrates how the transaction flow interacts with the buyer and how your requests interact with PayPal (the Sandbox in this example).

This figure illustrates a typical Set, Get, Do Express Checkout transaction.

1. Set Up the Payment Information

When a buyer initiates a check out, call SetExpressCheckout to specify the payment action, amount of payment, return URL, and cancel URL.

curl https://api-3t.sandbox.paypal.com/nvp \
  -s \
  --insecure \
  -d USER=callerID                           # User ID of the PayPal caller account \
  -d PWD=callerPswd                          # Password of the caller account \
  -d SIGNATURE=callerSig                     # Signature of the caller account \
  -d METHOD=SetExpressCheckout \
  -d VERSION=93 \
  -d PAYMENTREQUEST_0_PAYMENTACTION=SALE     # type of payment \
  -d PAYMENTREQUEST_0_AMT=19.95              # amount of transaction \
  -d PAYMENTREQUEST_0_CURRENCYCODE=USD       # currency of transaction \
  -d RETURNURL=http://www.example.com/success.html # URL of your payment confirmation page \
  -d CANCELURL=http://www.example.com/cancel.html  # URL redirect if customer cancels payment

Note: Example calls are shown in cURL, and the code is wrapped and commented for readability.

The SetExpressCheckout response contains a token value that you use in subsequent calls to complete the transaction.

2. PayPal Returns a Token

If the SetExpressCheckout request is successful, PayPal returns a token string in the Token response field. The default lifetime of this token is 3 hours. You will need this token in the subsequent steps.

# SetExpressCheckout response
...
TOKEN=EC%2d4RX1920730957200V
...

Important: You must URL-decode the returned token value before you can use it in other Express Checkout calls.

Note: See the SetExpresssCheckout API references (NVP | SOAP) for request and response field details.

3. Redirect the Buyer to PayPal for Approval

Using the token valued returned from SetExpressCheckout, redirect the buyer to PayPal so he / she can approve the transaction:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=tokenValue

The redirect presents the buyer with a PayPal log-in page. After the buyer logs in, PayPal displays the transaction details on the Payments Review page. The buyer approves the payment on this page by clicking Continue.

4. PayPal Redirects the Buyer Back to Your Site

If the buyer approves the payment, PayPal directs the buyer to the payment confirmation page (the return URL specified in your SetExpressCheckout call in Step 1). If the buyer doesn't authorize the payment, PayPal directs the buyer to the cancel URL that you also specified in your SetExpressCheckout call, and you can attempt to re-initiate the checkout.

5. Obtain Approved Payment Details

If the buyer approves the payment, call GetExpressCheckoutDetails to obtain the PayerID (which uniquely identifies the buyer), and any other details you might need for transaction processing. For example, you can use the transaction details to display the buyer's shipping data, and other information, on your payment confirmation page.

Use the following sample by replacing tokenValue with the token from the SetExpressCheckoutPayment response:

curl https://api-3t.sandbox.paypal.com/nvp \
  -s \
  --insecure \
  -d USER=callerID \
  -d PWD=callerPswd \
  -d SIGNATURE=callerSig \
  -d METHOD=GetExpressCheckoutDetails \
  -d VERSION=93 \
  -d TOKEN=tokenValue

The response from this call includes the PayerID value, which is needed to capture the payment. It may also include wallet item information for the buyer, such as available coupons or loyalty cards. If either PayPal Credit® (formerly Bill Me Later®) or a private label credit card (PLCC) is used as the payment method, payment instrument information may also be returned.

# GetExpressCheckoutDetails response

TOKEN=EC%2d4RX1920730957200V
...
&PAYERID=6B9DKHQRKW4SG
...
&WALLETTYPE0=MERCHANT_COUPON
&WALLETID0=COUP3456
&WALLETDESCRIPTION0=Acme Inc. coupon

&WALLETTYPE1=LOYALTY_CARD
&WALLETID1=LY3456
&WALLETDESCRIPTION1=Acme Inc. Loyalty Program
...
&INSTRUMENTCATEGORY=2
&INSTRUMENTID=982345

Note: See the GetExpressCheckoutDetails API references (NVP | SOAP) for request and response field details.

6. Complete the Transaction

When the buyer confirms the payment, call DoExpressCheckoutPayment to capture (collect) the payment. Specify the PayerID and token value returned from the previous calls. You can also specify the coupons or loyalty rewards being applied towards the payment. You can also pass your own custom data with the transaction in the merchant data key / value pair fields.

curl https://api-3t.sandbox.paypal.com/nvp \
  -s \
  --insecure \
  -d USER=callerID \
  -d PWD=callerPswd \
  -d SIGNATURE=callerSig \
  -d METHOD=DoExpressCheckoutPayment \
  -d VERSION=93 \
  -d TOKEN=tokenValue \
  -d PAYERID=payerID                     # customer's unique PayPal ID \
  -d PAYMENTREQUEST_0_PAYMENTACTION=SALE # payment type \
  -d PAYMENTREQUEST_0_AMT=19.95          # transaction amount \
  -d PAYMENTREQUEST_0_CURRENCYCODE=USD  # transaction currency, e.g. US dollars \
...
  -d L_PAYMENTREQUEST_0_REDEEMEDOFFERNAME0=Acme Inc. Loyalty Program \
  -d L_PAYMENTREQUEST_0_REDEEMEDOFFERDESCRIPTION0=Applicable to all purchases \
  -d L_PAYMENTREQUEST_0_REDEEMEDOFFERAMOUNT0=5 \
  -d L_PAYMENTREQUEST_0_REDEEMEDOFFERTYPE0=LOYALTY_CARD \
  -d L_PAYMENTREQUEST_0_REDEEMEDOFFERID0=ACME1223611 \
  -d L_PAYMENTREQUEST_0_REDEEMEDOFFERPOINTSACCRUED0=50 \
...
  -d L_PAYMENTREQUEST_0_CUMMULATIVEPOINTSNAME0=Acme Inc. Loyalty Program \
  -d L_PAYMENTREQUEST_0_CUMMULATIVEPOINTSDESCRIPTION0=Applicable to all purchases \
  -d L_PAYMENTREQUEST_0_CUMMULATIVEPOINTSTYPE0=LOYALTY_CARD \
  -d L_PAYMENTREQUEST_0_CUMMULATIVEPOINTSID0=ACME1223611 \
  -d L_PAYMENTREQUEST_0_CUMMULATIVEPOINTSACCRUED0=526 \
...
  -d L_PAYMENTREQUEST_0_MERCHANTDATAKEY0=PLCC_PROMO_CODE \
  -d L_PAYMENTREQUEST_0_MERCHANTDATAVALUE0=872345

When PayPal processes DoExpressCheckoutPayment, it captures the payment by transferring the funds from the buyer's account to the appropriate merchant account and sends a confirmation e-mail to the buyer.

Note: See the DoExpressCheckoutPayment API references (NVP | SOAP) for request and response field details.

Learn More

For information on using the PayPal APIs, how to use the Sandbox for testing, and how to move your app into production, see links provided on the Apps 101 page.