PayPal Express Checkout API Operations

The PayPal NVP API provides three primary methods related to Express Checkout. These operations initialize the transaction, obtain information about the buyer, and complete the transaction. Table 2-2 outlines these methods and some of the most fundamental parameters for each of them.

Table 2-2. Express Checkout API operations

API operation	Description
SetExpressCheckout	Sets up the Express Checkout transaction. You can specify information to customize the look and feel of the PayPal site and the information it displays. At a minimum, you must specify the following information: URL to the page on your website to which PayPal redirects after the buyer logs into PayPal and approves the payment successfully. URL to the page on your website to which PayPal redirects if the buyer cancels the transaction. Total amount of the order or your best estimate of the total. (Although exact shipping or handling amounts may not yet be known, this value should be estimated as accurately as possible.)
GetExpressCheckoutDetails	Obtains information about the buyer from PayPal, including shipping information.
DoExpressCheckoutPayment	Completes the Express Checkout transaction, including the actual total amount of the order.

Figure 2-6 provides an overview of the Express Checkout user experience from a software developer’s perspective. Before digging in deeper, it may be helpful to think through the following cursory explanation of these Express Checkout integration points. For the purposes of this checkout flow, let’s assume that a buyer has just initiated a checkout action on your site by clicking a “Pay with PayPal” button (the Checkout Entry Point) and will choose to complete the checkout process.

Set Express Checkout

• Behind the scenes, you invoke the SetExpressCheckout API and pass along details about the order, such as how much it costs and where to redirect the user when the transaction is completed or cancelled.

• You redirect the buyer to paypal.com by constructing a URL that includes a token parameter returned in the response from SetExpressCheckout so that PayPal can identify the buyer and details of the purchase, such as its amount.

• The buyer confirms shipping and payment information for the purchase directly on paypal.com, and PayPal redirects the buyer back to your website along with token and PayerID parameters.

Get Express Checkout Details

• Behind the scenes, you invoke the GetExpressCheckoutDetails API operation using the token parameter to request details about the purchase, such as where to ship it, an email address to send an order confirmation, etc.

• The buyer performs a final review of the order, including pertinent details you may have just fetched from PayPal, and finalizes the purchase by clicking a Complete Purchase button.

Do Express Checkout Payment

• Behind the scenes, you invoke the DoExpressCheckoutPayment API using the token and PayerID parameters to identify the user and securely complete the purchase.

• You display an order confirmation and optionally take additional actions, such as sending the buyer an email confirmation or shipping a physical item.

The remainder of this section takes a closer look at each of these API operations.

Figure 2-6. Express Checkout Integration Points

Warning

A few special caveats such as additional required parameters for requests do apply for Express Checkout integrations involving digital goods purchases and some Adaptive Payments scenarios. This chapter overlooks these caveats and focuses on a typical integration. See Chapters 3 and 4 for specifics on Digital Goods purchases and using Adaptive Payments, respectively.

SetExpressCheckout

SetExpressCheckout initializes the Express Checkout session and is the same operation you executed in Making a PayPal Request with GAE to make your first API request to PayPal. It allows you to pass variables that format how the PayPal pages look and specify where to redirect the buyer’s browser based upon success of the payment transaction. Table 2-3 outlines the fields required for SetExpressCheckout requests, and Table 2-4 outlines the fields you can expect back in a response for SetExpressCheckout.

See SetExpressCheckout API Operation for full details on a litany of other optional fields that can be passed in for SetExpressCheckout.

Table 2-3. SetExpressCheckout request fields

Field	Description
METHOD	Must be SetExpressCheckout
RETURNURL	URL to which the customer’s browser is returned after choosing to pay with PayPal. PayPal recommends that the value be the final review page on which the customer confirms the order and payment or billing agreement. Limitation: Up to 2,048 characters.
CANCELURL	URL to which the customer is returned if he does not approve the use of PayPal to pay you. PayPal recommends that the value be the original page on which the customer chose to pay with PayPal or establish a billing agreement. Limitation: Up to 2,048 characters.
PAYMENTREQUEST_ n _AMT	The total cost of the transaction to the customer. If shipping and tax charges are known, include them in this value; if not, this value should be the current subtotal of the order. If the transaction includes one or more one-time purchases, this field must equal the sum of the purchases. Set this field to 0 if the transaction does not include a one-time purchase—for example, when you set up a billing agreement for a recurring payment that is not charged immediately. Purchase-specific fields will be ignored. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).

Note

If you have done any previous work with Express Checkout, you may want to take note that AMT has been deprecated in favor of PAYMENTREQUEST_ n _AMT to accommodate tallying up multiple items in a checkout. Simply use PAYMENTREQUEST_0_AMT if dealing with only one item. Additionally, PAYMENTACTION is deprecated in favor of PAYMENTREQUEST_n_PAYMENTACTION and is no longer a required field, and it now defaults to Sale.

Table 2-4. SetExpressCheckout response fields

Field	Description
TOKEN	A time-stamped token that acts as a session identifier that is used in subsequent API requests to tell PayPal that you are processing this payment with Express Checkout. The token expires after three hours. If you set the token in the SetExpressCheckout request, the value of the token in the response is identical to the value in the request.

GetExpressCheckoutDetails

GetExpressCheckoutDetails obtains information about an Express Checkout transaction. The response essentially echoes back the information and values enabled in SetExpressCheckout, although it does return a few other important fields such as PAYERID, and it is possible that the response may contain additional fields such as NOTE. For example, the response may contain a NOTE field that the buyer may have entered in if the ALLOWNOTE field was set in SetExpressCheckout. Table 2-5 describes the required GetExpressCheckoutDetails fields. As a best practice, it is recommended that you invoke GetExpressCheckoutDetails as part of an Express Checkout integration, but it is not technically required that you do so.

See GetExpressCheckoutDetails API Operation for full details on this API.

Table 2-5. GetExpressCheckoutDetails request fields

Field	Description
METHOD	Must be GetExpressCheckoutDetails
TOKEN	The same time-stamped token as returned by the SetExpressCheckout response

DoExpressCheckoutPayment

DoExpressCheckoutPayment completes the Express Checkout transaction and returns the payment response. In the case of a billing agreement that you specified in the SetExpressCheckout API call, it is officially created when you call the DoExpressCheckoutPayment API operation. For a minimal Express Checkout integration, you’d only need to properly invoke DoExpressCheckoutPayment after first setting up the transaction with SetExpressCheckout and handling the PayPal redirects. Table 2-6 lists some common DoExpressCheckoutPayment request fields. The number of fields returned from DoExpressCheckoutPayment is rather extensive. Although you may not necessarily need to use all of these values, Table 2-7 describes some of them to give you an idea of the breadth of information that’s available to you after a checkout has been completed.

Table 2-6. DoExpressCheckoutPayment request fields

Field	Description
METHOD	Must be DoExpressCheckoutPayment.
TOKEN	A time-stamped token, the value of which was returned by the SetExpressCheckout response and passed on to the GetExpressCheckoutDetails request.
PAYERID	Unique PayPal customer account identification number. This value is obtained by parsing the query string immediately after PayPal redirects the customer back to your site or by parsing the results returned from GetExpressCheckoutDetails.
PAYMENTREQUEST_ n _AMT	The total cost of the transaction to the customer. If shipping and tax charges are known, include them in this value; if not, this value should be the current subtotal of the order. If the transaction includes one or more one-time purchases, this field must equal the sum of the purchases. Set this field to 0 if the transaction does not include a one-time purchase, for example, when you set up a billing agreement for a recurring payment that is not charged immediately. Purchase-specific fields will be ignored. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
PAYMENTREQUEST_ n _PAYMENTACTION	How you want to obtain your payment. Sale indicates that this is a final sale for which you are requesting payment (this is the default). Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization and Capture. Order indicates that this payment is an order authorization subject to settlement with PayPal Authorization and Capture. If the transaction does not include a one-time purchase, this field is ignored. You cannot set this value to Sale in SetExpressCheckout request and then change this value to Authorization or Order on the final API DoExpressCheckoutPayment request. If the value is set to Authorization or Order in SetExpressCheckout, the value may be set to Sale or the same value (either Authorization or Order) in DoExpressCheckoutPayment.

Table 2-7. DoExpressCheckoutPayment response fields

Field	Description
TOKEN	A time-stamped token, the value of which was returned by the SetExpressCheckout response.
PAYMENTTYPE	Information about the payment.
SUCCESSPAGEREDIRECTREQUESTED	Flag that indicates whether you need to redirect the customer to back to PayPal after completing the transaction.
PAYMENTINFO_ n _TRANSACTIONID	Unique transaction ID of the payment. If the PaymentAction of the request was Authorization or Order, this value is your AuthorizationID for use with the Authorization and Capture APIs.
PAYMENTINFO_ n _TRANSACTIONTYPE	The type of transaction. Valid values are cart and express-checkout.
PAYMENTINFO_ n _PAYMENTTYPE	Indicates whether the payment is instant or delayed. Valid values are none, echeck, and instant.
PAYMENTINFO _ n _ORDERTIME	The time/date stamp of the payment.
PAYMENTINFO_ n _AMT	The final amount charged, including any shipping and taxes from your Merchant Profile.
PAYMENTINFO_ n _FEEAMT	PayPal fee amount charged for the transaction.
PAYMENTINFO_ n _TAXAMT	Tax charged on the transaction.
PAYMENTINFO_ n _EXCHANGERATE	Exchange rate if a currency conversion occurred. Relevant only if you are billing in the customer’s nonprimary currency. If the customer chooses to pay with a currency other than the primary currency, the conversion occurs in the customer’s account.
PAYMENTINFO_ n _PAYMENTSTATUS	The status of the payment, which will be one of the following: None: No status. Canceled-Reversal: A reversal has been canceled, for example, when you win a dispute and the funds for the reversal are returned to you. Completed: The payment has been completed and the funds have transferred successfully to your account. Denied: You denied the payment. This will occur only if the payment was previously pending for reasons described in the PendingReason field. Expired: The authorization period for the payment has expired. Failed: The payment failed. This occurs only when the payment was made from your customer’s bank draft account. In-Progress: Transaction has not terminated, most likely due to an authorization awaiting completion. Partially-Refunded: Payment has been partially refunded. Pending: Payment is still pending for reasons described in the PendingReason field. Refunded: You refunded the payment. Reversed: Payment was reversed due to a charge back or other reversal. The funds have been removed from your account balance and returned to the buyer. The reason will be described in the ReasonCode field. Processed: Payment has been accepted. Voided: Authorization for the transaction has been voided.
PAYMENTINFO_ n _ PROTECTION ELIGIBILITY	The type of seller protection in force for the transaction, which is one of the following values: Eligible: Seller is protected by PayPal’s Seller protection policy for Unauthorized Payments and Item Not Received. PartiallyEligible: Seller is protected by PayPal’s Seller Protection Policy for Item Not Received. Ineligible: Seller is not protected under the Seller Protection Policy.
PAYMENTREQUEST_ n _ PAYMENT REQUEST ID	The unique identifier of the specific payment request. The value should match the one passed in the DoExpressCheckout request.
L_PAYMENTINFO_ n _FMFfilterIDn	Filter ID, including the filter type (PENDING, REPORT, or DENY), the filter ID, and the entry number, n, starting from 0. Filter ID is one of the following values [AVS stands for Address Verification System]: 1 = AVS No Match 2 = AVS Partial Match 3 = AVS Unavailable/Unsupported 4 = Card Security Code (CSC) Mismatch 5 = Maximum Transaction Amount 6 = Unconfirmed Address 7 = Country Monitor 8 = Large Order Number 9 = Billing/Shipping Address Mismatch 10 = Risky Zip Code 11 = Suspected Freight Forwarder Check 12 = Total Purchase Price Minimum 13 = IP Address Velocity 14 = Risky Email Address Domain Check 15 = Risky Bank Identification Number (BIN) Check 16 = Risky IP Address Range 17 = PayPal Fraud Model
L_PAYMENTINFO_ n _FMFfilterNAME n	Filter name, including the filter type (PENDING, REPORT, or DENY), the filter NAME, and the entry number, n, starting from 0.
PAYMENTREQUEST_ n _SHORTMESSAGE	Payment error short message.
PAYMEMNTREQUEST_ n _LONGMESSAGE	Payment error long message.
PAYMENTREQUEST_ n _ERRORCODE	Payment error code.
PAYMENTREQUEST_ n _SEVERITYCODE	Payment error severity code.
PAYMENTREQUEST_ n _ACK	Application-specific error values indicating more about the error condition.
SHIPPINGCALCULATIONMODE	Describes how the options that were presented to the user were determined, and is one of the following values: API - Callback API - Flatrate
INSURANCEOPTIONSELECTED	The Yes/No option that you chose for insurance.
SHIPPINGOPTIONISDEFAULT	Is true if the buyer chose the default shipping option. Value will be either TRUE or FALSE.
SHIPPINGOPTIONAMOUNT	The shipping amount that was chosen by the buyer. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
SHIPPINGOPTIONNAME	This is true if the buyer chose the default shipping option.
PAYMENTREQUEST_ n _ SELLER PAYPAL ACCOUNTID	Unique identifier for the merchant. For parallel payments, this field contains either the Payer ID or the email address of the merchant.

See DoExpressCheckoutPayment API Operation for more details on this API, but do note that it’s well worth the time to peruse the full details of this lengthy table, even though it might seem a bit pedantic to at first—a misinformed understanding of this table can result in faulty logic in your implementation that can really hurt your bottom line. The sidebar explains one possible scenario involving a commonly overlooked payment type involving what’s known in PayPal lingo as an eCheck.

Instant Payments versus eChecks

Did you notice that in Table 2-7, the PAYMENTINFO_ n _PAYMENTTYPE field can return several different values, including none, echeck, and instant? Or that PAYMENTINFO_ n _PAYMENTSTATUS can have over a dozen possible values? Knowing the difference between an eCheck and an instant payment is a very important implementation detail, as is inspecting the result of the PAYMENTINFO_ n _PAYMENTSTATUS value. In short, instant payments are transferred to your merchant accounts immediately when a buyer uses funds from a PayPal account or ends up using a credit/debit card as a backup funding source that’s eligible for an instant payment by means of having available credit. eChecks are used for payment when a buyer doesn’t have available funds from a PayPal account and doesn’t have a credit/debit card that’s eligible for instant payment, which usually means that PayPal debits the funds from a linked bank account. Like an ordinary paper check, it can unfortunately take a few days for the whole process to resolve and for the check to finally clear.

eChecks introduce some additional complexity in the implementation of a payment solution because as the seller, you are essentially in limbo if you receive an eCheck with a status of “pending.” Whereas an instant payment is guaranteed money, an eCheck, just like a paper check, may “bounce” and ultimately resolve to a status such as Denied, which means that you won’t ever be receiving the funds. Thus, it’s imperative that you be prepared to handle eChecks; however, the ability to properly handle eChecks requires an understanding of Instant Payment Notifications (IPNs), a message delivery service that PayPal uses to notify you when an eCheck’s status is finalized. Since IPNs aren’t introduced until Chapter 6, the sample code for Chapters 2 through 5 is designed to process only instant payments for simplicity.

If you’d like to test an application in the sandbox using an eCheck, create a sample account with a lower bank account balance than the purchase price and do not add a credit card to the account. For non-digital goods purchases, you’ll observe that PayPal gives you the eCheck option. For digital goods purchases, however, PayPal prompts you to add a credit card since digital goods purchases require instant payments by virtue of being delivered (almost) instantly in most cases.