How to Use Express Checkout to Accept a Basic Digital Goods Payment
Important: This integration method is deprecated as of January 1, 2017. PayPal continues to support existing merchants using this method, but please be advised new features and enhancements will not be applied to these integrations. For new integrations, see the PayPal Checkout Integration Guide.
Accepting a basic digital goods payment requires:
- Setting up the payment information for a digital goods payment.
- Redirecting the customer to PayPal for authorization.
- Obtaining authorized payment details.
- 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 micro-payment pricing by doing the following steps during merchant account setup:
- Select a digital goods category
- Select micro-payment 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
for micro-payment 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 toinstant
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
...