Getting Started With Express Checkout

To implement Express Checkout, start with the simplest Express Checkout integration and test it. Then you can decide the kind of payment settlement actions you want to support.

Implementing the Simplest Express Checkout Integration

The simplest Express Checkout integration requires the following PayPal API operations: SetExpressCheckout, DoExpressCheckoutPayment, and optionally, GetExpressCheckoutDetails.

Setting Up the Express Checkout Transaction

To set up an Express Checkout transaction, you must invoke the SetExpressCheckout API operation to provide sufficient information to initiate the payment flow and redirect to PayPal if the operation was successful.

This example assumes that you have set up the mechanism you will use to communicate with the PayPal server and have a PayPal Business account with API credentials. It also assumes that the payment action is a final sale.

When you set up an Express Checkout transaction, you specify values in the SetExpressCheckout request and then call the API. The values you specify control the PayPal page flow and the options available to you and your buyers. You should start by setting up a standard Express Checkout transaction, which can be modified to include additional options.

To set up the simplest standard Express Checkout transaction:

  1. Specify that you want to execute the SetExpressCheckout API operation and the version you want to use.
    METHOD=SetExpressCheckout
    VERSION=XX.0
    
  2. Specify your API credentials.

    Use the following parameters for a signature:

    USER=API_username
    PWD=API_password
    SIGNATURE=API_signature
    

    In the Sandbox, you can always use the following signature:

    USER=sdk-three_api1.sdk.com
    PWD=QFZCWN5HZM8VBG7Q
    SIGNATURE=A-IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU
    
  3. Specify the amount of the transaction; include the currency if it is not in US dollars.

    Specify the total amount of the transaction if it is known; otherwise, specify the subtotal. Regardless of the specified currency, the format must have a decimal point with exactly two digits to the right and an optional thousands separator to the left, which must be a comma.

    For example, EUR 2.000,00 must be specified as 2000.00 or 2,000.00. The specified amount cannot exceed USD $10,000.00, regardless of the currency used.

    PAYMENTREQUEST_0_AMT=amount
    PAYMENTREQUEST_0_CURRENCYCODE=currencyID
    
  4. Specify the return URL.

    The return URL is the page to which PayPal redirects your buyer's browser after the buyer logs into PayPal and approves the payment. Typically, this is a secure page (https://...) on your site.

    Note: You can use the return URL to piggyback parameters between pages on your site. For example, you can set your Return URL to specify additional parameters using the https://www.yourcompany.com/page.html?param=value... syntax. The parameters become available as request parameters on the page specified by the Return URL.
    RETURNURL=return_url
    
  5. Specify the cancel URL.

    The cancel URL is the page to which PayPal redirects your buyer's browser if the buyer does not approve the payment. Typically, this is the secure page (https://...) on your site from which you redirected the buyer to PayPal.

    Note: You can pass SetExpressCheckout request values as parameters in your URL to have the values available, if necessary, after PayPal redirects to your URL.
    CANCELURL=cancel_url
    
  6. Specify the payment action.

    Although the default payment action is a Sale, it is a best practice to explicitly specify the payment action as one of the following values:

    PAYMENTREQUEST_0_PAYMENTACTION=Sale
    

If calling the SetExpressCheckout API was successful, redirect the buyer's browser to PayPal and execute the _express-checkout command using the token returned in the SetExpressCheckout response.

Note: The following example uses the PayPal Sandbox server:
https://www.sandbox.paypal.com/cgi-bin/webscr
?cmd=_express-checkout&token=tokenValue

Obtaining Express Checkout Transaction Details

To obtain details about an Express Checkout transaction, you can invoke the GetExpressCheckoutDetails API operation.

This example assumes that PayPal redirects to your buyer's browser with a valid token after the buyer reviews the transaction on PayPal.

Although you are not required to invoke the GetExpressCheckoutDetails API operation, most Express Checkout implementations take this action to obtain information about the buyer. You invoke the GetExpressCheckoutDetails API operation from the page specified by return URL, which you set in your call to the SetExpressCheckout API. Typically, you invoke this operation as soon as the redirect occurs and use the information in the response to populate your review page.

To obtain a buyer's shipping address and Payer ID:

  1. Specify that you want to execute the GetExpressCheckoutDetails API operation and the version you want to use.
    METHOD=GetExpressCheckoutDetails
    VERSION=XX.0
    
  2. Specify your API credentials.

    Use the following parameters for a signature:

    USER=API_username
    PWD=API_password
    SIGNATURE=API_signature
    
  3. Specify the token returned by PayPal when it redirects the buyer's browser to your site.

    PayPal returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API.

    TOKEN=tokenValue
    
  4. Execute the GetExpressCheckoutDetails API to obtain information about the buyer.
  5. Access the fields in the GetExpressCheckoutDetails API response.
    Note: Only populated fields are returned in the response.

Completing the Express Checkout Transaction

To complete an Express Checkout transaction, you must invoke the DoExpressCheckoutPayment API operation.

This example assumes that PayPal redirects your buyer's browser to your website with a valid token after you call the SetExpressCheckout API. Optionally, you may call the GetExpressCheckoutDetails API before calling the DoExpressCheckoutPayment API.

In the simplest case, you set the total amount of the order when you call the SetExpressCheckout API. However, you can change the amount before calling the DoExpressCheckoutPayment API if you did not know the total amount when you called the SetExpressCheckout API.

This example assumes the simplest case, in which the total amount was specified in the return URL when calling the SetExpressCheckout API. Although you can specify additional options, this example does not use any additional options.

To execute an Express Checkout transaction:

  1. Specify that you want to execute the DoExpressCheckoutPayment API operation and the version you want to use.
    METHOD=DoExpressCheckoutPayment
    VERSION=XX.0
    
  2. Specify your API credentials.

    Use the following parameters for a signature:

    USER=API_username
    PWD=API_password
    SIGNATURE=API_signature
    
  3. Specify the token returned by PayPal when it redirects the buyer's browser to your site.

    PayPal returns the token to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API.

    TOKEN=tokenValue
    
  4. Specify the Payer ID returned by PayPal when it redirects the buyer's browser to your site.

    PayPal returns the Payer ID to use in the token HTTP request parameter when redirecting to the URL you specified in your call to the SetExpressCheckout API. Optionally, you can obtain the Payer ID by calling the GetExpressCheckoutDetails API.

    PAYERID=id
    
  5. Specify the amount of the order including shipping, handling, and tax; include the currency if it is not in US dollars.

    Most of the time, this will be the same amount as you specified in your SetExpressCheckout call, adjusted for shipping and taxes.

    PAYMENTREQUEST_0_AMT=amount
    PAYMENTREQUEST_0_CURRENCYCODE=currencyID
    
  6. Specify the same payment action that you specified in SetExpressCheckout.
    PAYMENTREQUEST_0_PAYMENTACTION=Sale
    

Testing an Express Checkout Integration

You can test your Express Checkout integration in the Sandbox.

This example shows how to simulate your web pages using HTTP forms and supplying the values for API operations from these forms. You can use this strategy for your initial testing; however, for more complete testing, you need to replace these forms with your web pages containing your actual code.

The following diagram shows the Express Checkout execution flow, which uses the Sandbox as the API server. The pages on the left represent your site.



The following steps match the circled numbers in the diagram. Perform the actions in each step to test Express Checkout.

  1. Invoke a form on your site that calls the SetExpressCheckout API on the Sandbox.

    To invoke the API, set form fields whose names match the NVP names of the fields you want to set, specify their corresponding values, and then post the form to a PayPal Sandbox server, such as https://api-3t.sandbox.paypal.com/nvp, as shown in the following example:

    <form method=post action=https://api-3t.sandbox.paypal.com/nvp>
    <input type=hidden name=USER value=API_username>
    <input type=hidden name=PWD value=API_password>
    <input type=hidden name=SIGNATURE value=API_signature>
    <input type=hidden name=VERSION value=XX.0>
    <input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION
    value=Sale>
    <input name=PAYMENTREQUEST_0_AMT value=19.95>
    <input type=hidden name=RETURNURL
    value=https://www.YourReturnURL.com>
    <input type=hidden name=CANCELURL
    value=https://www.YourCancelURL.com>
    <input type=submit name=METHOD value=SetExpressCheckout>
    </form>
    
    Note: Use an API username from a Sandbox business test account for which a signature exists. See the Test Certificates tab of the Sandbox to obtain a signature. If you are not using a signature, you must use a different Sandbox server.
  2. Review the response string from the SetExpressCheckout API operation.

    PayPal responds with a message, such as the one shown below. Note the status, which should include ACK set to Success, and a token that is used in subsequent steps.

    TIMESTAMP=2007%2d04%2d05T23%3a23%3a07Z
    &CORRELATIONID=63cdac0b67b50
    &ACK=Success
    &VERSION=XX%2e000000
    &BUILD=1%2e0006
    &TOKEN=EC%2d1NK66318YB717835M
    
  3. If the operation was successful, use the token and redirect your browser to the Sandbox to log in, as follows:
    https://www.sandbox.paypal.com/cgi-bin/webscr?
    cmd=_express-checkout
    &token=EC-1NK66318YB717835M
    

    You may need to decode the URL, which is the opposite of URL encoding, by replacing hexadecimal codes with ASCII codes; for example, you may need to replace %2d in the token with a hyphen ( - ).

    You must log in to https://developer.paypal.com before you log in to a Sandbox test account. You then log in to the test account that represents the buyer, not the seller's business test account that represents you as the merchant.

  4. After logging into the buyer test account, confirm the details.

    When you confirm, the Sandbox redirects your browser to the return URL you specified when invoking the SetExpressCheckout API operation, as in the following example:

    http://www.YourReturnURL.com/
    			?token=EC-1NK66318YB717835M&PayerID=7AKUSARZ7SAT8
    
  5. Invoke a form on your site that calls the GetExpressCheckoutDetails API operation on the Sandbox:
    <form method=post action=https://api-3t.sandbox.paypal.com/nvp
    <input type=hidden name=USER value=API_username>
    <input type=hidden name=PWD value=API_password>
    <input type=hidden name=SIGNATURE value=API_signature>
    <input type=hidden name=VERSION value=XX.0>
    <input name=TOKEN value=EC-1NK66318YB717835M>
    <input type=submit name=METHOD value=GetExpressCheckoutDetails>
    </form>
    

    If the operation was successful, the GetExpressCheckoutDetails API returns information about the payer, such as the following information:

    TIMESTAMP=2007%2d04%2d05T23%3a44%3a11Z
    &CORRELATIONID=6b174e9bac3b3
    &ACK=Success
    &VERSION=XX%2e000000
    &BUILD=1%2e0006
    &TOKEN=EC%2d1NK66318YB717835M
    &EMAIL=YourSandboxBuyerAccountEmail
    &PAYERID=7AKUSARZ7SAT8
    &PAYERSTATUS=verified
    &FIRSTNAME=...
    &LASTNAME=...
    &COUNTRYCODE=US
    &BUSINESS=...
    &PAYMENTREQUEST_0_SHIPTONAME=...
    &PAYMENTREQUEST_0_SHIPTOSTREET=...
    &PAYMENTREQUEST_0_SHIPTOCITY=...
    &PAYMENTREQUEST_0_SHIPTOSTATE=CA
    &PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE=US
    &PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME=United%20States
    &PAYMENTREQUEST_0_SHIPTOZIP=94666
    &PAYMENTREQUEST_0_ADDRESSID=...
    &PAYMENTREQUEST_0_ADDRESSSTATUS=Confirmed
    
  6. Invoke a form on your site that invokes the DoExpressCheckoutPayment API operation on the Sandbox:
    <form method=post action=https://api-3t.sandbox.paypal.com/nvp>
    <input type=hidden name=USER value=API_username>
    <input type=hidden name=PWD value=API_password>
    <input type=hidden name=SIGNATURE value=API_signature>
    <input type=hidden name=VERSION value=XX.0>
    <input type=hidden name=PAYMENTREQUEST_0_PAYMENTACTION
    value=Authorization>
    <input type=hidden name=PAYERID value=7AKUSARZ7SAT8>
    <input type=hidden name=TOKEN value= EC%2d1NK66318YB717835M>
    <input type=hidden name=PAYMENTREQUEST_0_AMT value= 19.95>
    <input type=submit name=METHOD value=DoExpressCheckoutPayment>
    </form>
    
  7. Review the response string from the DoExpressCheckoutPayment API operation.

    If the operation was successful, the response should include ACK set to Success, as follows:

    TIMESTAMP=2007%2d04%2d05T23%3a30%3a16Z
    &CORRELATIONID=333fb808bb23
    ACK=Success
    &VERSION=XX%2e000000
    &BUILD=1%2e0006
    &TOKEN=EC%2d1NK66318YB717835M
    &PAYMENTREQUEST_0_TRANSACTIONID=043144440L487742J
    &PAYMENTREQUEST_0_TRANSACTIONTYPE=expresscheckout
    &PAYMENTREQUEST_0_PAYMENTTYPE=instant
    &PAYMENTREQUEST_0_ORDERTIME=2007%2d04%2d05T23%3a30%3a14Z
    &PAYMENTREQUEST_0_AMT=19%2e95
    &PAYMENTREQUEST_0_CURRENCYCODE=USD
    &PAYMENTREQUEST_0_TAXAMT=0%2e00
    &PAYMENTREQUEST_0_PAYMENTSTATUS=Pending
    &PAYMENTREQUEST_0_PENDINGREASON=authorization
    &PAYMENTREQUEST_0_REASONCODE=None
    

Handling Payment Settlements With Express Checkout

You can use PayPal API operations to handle the capture of payments authorized using Express Checkout and manage Express Checkout authorization and order payment actions.

Sale Payment Action for Express Checkout

A sale payment action represents a single payment that completes a purchase for a specified amount.

A sale is the default Express Checkout payment action; however, you can also specify the following action in your SetExpressCheckout and DoExpressCheckoutPayment requests:

PAYMENTREQUEST_n_PAYMENTACTION=Sale

A sale is the most straightforward payment action. Choose this payment action if the transaction, including shipping of goods, can be completed immediately. To use this payment action:

  • The final amount of the payment must be known when you invoke the DoExpressCheckoutPayment API operation
  • You should intend to fulfill the order immediately, such as would be the case for digital goods or for items you have in stock for immediate shipment

After you execute the DoExpressCheckoutPayment API operation, the payment is complete and further action is unnecessary. You cannot capture a further payment or void any part of the payment when you use this payment action.

Authorization Payment Action for Express Checkout

An authorization payment action represents an agreement to pay and places the buyer's funds on hold for up to three days.

To set up an authorization, specify the following payment action in your SetExpressCheckout and DoExpressCheckoutPayment requests:

PAYMENTREQUEST_n_PAYMENTACTION=Authorization

An authorization enables you to capture multiple payments up to 115% of, or USD $75 more than, the amount you specify in the DoExpressCheckoutPayment request. Choose this payment action if you need to ship the goods before capturing the payment or if there is some reason not to accept the payment immediately.

The honor period, for which funds can be held, is three days. The valid period, for which the authorization is valid, is 29 days. You can reauthorize the 3-day honor period at most once within the 29-day valid period.

You can void an authorization, in which case the uncaptured part of the amount specified in the DoExpressCheckoutPayment request becomes void and can no longer be captured. If no part of the payment has been captured, the entire payment becomes void and nothing can be captured.

Table 1. API operations associated with Authorization payment action in Express Checkout
API Operation Description
DoCapture Capture an authorized payment.
DoReauthorization Reauthorize a payment.
DoVoid Void an order or an authorization.

Order Payment Action for Express Checkout

An order payment action represents an agreement to pay one or more authorized amounts up to the specified total over a maximum of 29 days.

To set up an order, specify the following payment action in your SetExpressCheckout and DoExpressCheckoutPayment requests:

PAYMENTREQUEST_n_PAYMENTACTION=Order

An order enables you to create multiple authorizations over the 29 days; each authorization you create places the buyer's funds on hold for up to three days. You can capture multiple payments for each authorization, up to 115% of, or USD $75 more than, the amount you specify in the DoExpressCheckoutPayment request.

Note: The default number of child authorizations in your PayPal account is 1. To do multiple authorizations please contact PayPal to request an increase.

This payment action provides the most flexibility and should be used when either a sale does not meet, or one authorization plus one reauthorization, do not meet your needs. Situations in which orders are appropriate include the handling of:

  • Back orders, in which available merchandise is sent immediately and the remaining merchandise is sent when available, which may include more than two shipments
  • Split orders, in which merchandise is sent in more than one shipment, perhaps to different addresses, and you want to collect a payment for each shipment
  • Drop shipments, which are shipments from other vendors for which you accept the payment

You cannot reauthorize an authorization. You handle the need to reauthorize, for example when the hold period or valid period of an authorization expires, simply by creating another authorization.

You can void an order or an authorization created from the order. If you void an order, the uncaptured part of the amount specified in the DoExpressCheckoutPayment request becomes void and can no longer be captured. If no part of the payment has been captured, the entire payment becomes void and nothing can be captured.

If you void an authorization associated with the order, the uncaptured part of the amount specified in the authorization becomes void and can no longer be captured. If no part of the authorization has been captured, the entire authorized payment becomes void.

Table 2. API operations associated with Order payment action in Express Checkout
API Operation Description
DoAuthorization Authorize a payment.
DoCapture Capture an authorized payment.
DoVoid Void an order or an authorization.

Issuing Refunds

You can use the RefundTransaction PayPal API operation to issue refunds.

Use the RefundTransaction API to issue one or more refunds associated with a transaction, such as a transaction created by a capture of a payment. The transaction is identified by a transaction ID that PayPal assigns when the payment is captured.

Note: You cannot make a refund if the transaction occurred after the refund period has passed; typically, the refund period is 60 days.

You can refund amounts up to the total amount of the original transaction. If you specify a full refund, the entire amount is refunded. If you specify a partial refund, you must specify the amount to refund, the currency, and a description of the refund, which is called a memo.

When you call the RefundTransaction API, PayPal responds with another transaction ID, which is associated with the refund (not the original transaction), and additional information about the refund. This information identifies:

  • The gross amount of the refund, which is returned to the payer
  • The amount of the refund associated with the original transaction fee, which is returned to you
  • The net amount of the refund, which is deducted from your balance

To issue a refund:

  1. In the RefundTransaction request, specify the transaction ID of the transaction whose payment you want to refund.
    TRANSACTIONID=transaction_id
    
  2. Specify the kind of refund, which is either Full or Partial.
    REFUNDTYPE=Full
    

    or

    REFUNDTYPE=Partial
    
  3. For a partial refund, specify the refund amount, including the currency.
    AMT=amount
    CURRENCYCODE=currencyID
    
  4. For a partial refund, specify the memo description.
    NOTE=description
    
  5. Execute the RefundTransaction operation.
  6. Check the acknowledgement status in the RefundTransaction response to ensure that the operation was successful.