How to Accept a Basic Digital Goods Payment Using Express Checkout

Important: This integration method is Deprecated as of January 1, 2017. For new integrations, see the PayPal Express Checkout Integration Guide.

Accepting a basic digital goods payment requires:

  1. Setting up the payment information for a digital goods payment.
  2. Redirecting the customer to PayPal for authorization.
  3. Obtaining authorized payment details.
  4. Capturing the payment.

Additional information is available at the following locations:

Prerequisites

When your application is ready for production use (after testing in the PayPal Sandbox), take advantage of micropayment pricing by doing the following steps during merchant account setup:

  1. Select a digital goods category
  2. Select micropayment pricing

Step 1: Set Up the Payment Information

When a customer is ready to check out, use the SetExpressCheckout call. In the request below, set the L_PAYMENTREQUEST_0_ITEMCATEGORY0 input field to Digital in order for micropayment pricing to apply.

For recommended lightbox functionality:

  • Detailed instructions are at Introducing Digital Goods for Express Checkout. Those instructions show how to use javascript to embed a payment flow, so users don't have to interrupt their use of the digital goods (the games, news, videos, etc.) for a purchase. When you use the provided javascript, set the expType value to instant for the best conversion rate.

The following SetExpressCheckout response contains a token for use in subsequent steps.

Request
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=merchant_user_name
&PWD=merchant_password
&SIGNATURE=merchant_signature
&METHOD=SetExpressCheckout
&VERSION=89
&cancelUrl=https://example.com/cancel    #For use if the consumer decides not to proceed with payment
&returnUrl=https://example.com/success   #For use if the consumer proceeds with payment
&PAYMENTREQUEST_0_CURRENCYCODE=USD    #The currency, e.g. US dollars
&PAYMENTREQUEST_0_PAYMENTACTION=SALE    #Payment for a sale
&PAYMENTREQUEST_0_AMT=21    #The amount authorized
&PAYMENTREQUEST_0_ITEMAMT=21
&L_PAYMENTREQUEST_0_ITEMCATEGORY0=Digital    #The item category must be set to Digital
&L_PAYMENTREQUEST_0_NAME0=my_movie
&L_PAYMENTREQUEST_0_QTY0=1
&L_PAYMENTREQUEST_0_AMT0=21

Response
--------
TOKEN=EC%2d2B984685J43051234
&ACK=Success
...

Step 2: Redirect the Customer to PayPal for Authorization

Redirect the customer to Paypal by using the token from Step 1 to construct the PayPal authorization URL, with the following format:

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

If the customer doesn't authorize payment, the customer is redirected to the cancel URL that you specified in the SetExpressCheckout call, so you can provide a way to re-initiate checkout.

As stated above, lightbox functionality is described in a separate document.

Step 3: Obtain Authorized Payment Details

If the customer authorizes the payment, the customer is redirected to the return URL that you specified in the SetExpressCheckout call. The return URL is appended with the same token as the token used above.

Use the GetExpressCheckoutDetails call to get the authorized payment details and the payer ID. The payer ID is a customer identifier for use in the DoExpressCheckoutPayment call.

Below is sample code. Please replace the token placeholder with the token from the SetExpressCheckoutPayment response (from Step 1).

Request
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=merchant_user_name
&PWD=merchant_password
&SIGNATURE=merchant_signature
&METHOD=GetExpressCheckoutDetails
&VERSION=89
&TOKEN=token_value

Response
--------
TOKEN=token_value
&ACK=Success
&PAYERID=3TXTXECKF1234   #Identifies the customer's account
&L_PAYMENTREQUEST_0_ITEMCATEGORY0=Digital
...

Step 4: Capture the Payment

The payment can be captured (collected) using the DoExpressCheckoutPayment call.

In this sample request, replace the placeholders with the payer ID and token from previous steps.

Request
-------
Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
HTTP method: POST
POST data:
USER=merchant_user_name
&PWD=merchant_password
&SIGNATURE=merchant_signature
&METHOD=DoExpressCheckoutPayment
&VERSION=89
&TOKEN=token_value
&PAYERID=3TXTXECKF1234   #From the GetExpressCheckoutDetails response; identifies the customer's account
&PAYMENTREQUEST_0_PAYMENTACTION=SALE  #Indicates that a payment will be processed
&PAYMENTREQUEST_0_AMT=21   #The amount of payment
&PAYMENTREQUEST_0_CURRENCYCODE=USD   #The currency, e.g. US dollars

Response
--------
TOKEN=token_value
&ACK=Success
&PAYMENTINFO_0_TRANSACTIONID=3CA20865912341234
...