PayPal SetExpress

Overview

SetExpress is the first API call of the PayPal checkout flow. It is used to initiate the PayPal authorization process. PayPal supports Express Checkout, Express Checkout Easy Payments, and PayPal Standard Checkout payment method.

Express Checkout uses the shipping address on file at the buyer's PayPal account. Express Checkout Easy Payments leverages Express Checkout by allowing its customer to pay for a purchase with a specific amount over a specific number of months at a promotional APR. Currently Easy Payments are available to buyers with United Kingdom, Unites States, and Germany PayPal accounts only.

Standard Checkout uses the shipping address on file is overridden by the address entered by the user. The request element AddressOverride is used to distinguish between the two types of checkout. AddressOverride must be set to 0 for an Express checkout and to 1 for a Standard checkout.

The API is used with the PayPal Vault feature which you can find details on implementation and management here: PayPal Vault

The SetExpress response contains a Token element. The token value is used in the PayPal GetExpress request -- the next call in the PayPal checkout flow.

URI Description

Action URI Template URI Example Request Content Type Response Content Type
POST /vM.m/stores/{StoreID}/payments/paypal/setExpress.xml /v1.0/stores/TMSUS/payments/paypal/setExpress.xml application/xml or text/xml application/xml or text/xml

Request Elements

When preparing the request, consider the following data notes:

  • Negative Line Items Amounts are allowed in order to apply discounts, and LineItemsTotal is also allowed to have a negative value. However, the request Amount, which equals the sum of LineItemsTotal + ShippingTotal + TaxTotal, cannot be negative.
  • AddressOverride must be set to 0 if the user chooses Express checkout, or 1 if the user chooses Standard checkout.

PayPal Vault Changes

If you are using PayPal Vault, set the Recurring field to true. Along with that include the optional Customer Id in the request to link Vault Ids under the same customer. If not provided, PayPal will generate a Customer Id automatically.

If you prefer to create a vault without making a purchase, set SetExpress Request with the amount 0.

Vault creation without purchase scenario, the field ApprovalUrl will be present in response, that should be approved before making the PayPal Payment Method Create API call.

Auto-capture setup

Set AutoCapture field to true/false.

Element Required Description Type Restriction
StoreId Yes Store identifier used in the URL. String 20 Characters
OrderId Yes Order identifier. String 20 Characters
ReturnUrl Yes URL to which the customer's browser is returned after choosing to pay with PayPal. String Cannot be empty. (Minimum of 1 character)
CancelUrl Yes URL to which the customer is returned if the customer does not approve the use of PayPal. String Cannot be empty. (Minimum of 1 character)
LocaleCode Yes Locale code for the user's language in combination with a country. String Cannot be empty. (Minimum of 1 character). Example: en_US
Amount Yes The order total amount, which is the sum of LineItemsTotal + ShippingTotal + TaxTotal. Also, The Amount must be 0, when the customer is only creating the Vault. Decimal 2 precision points. (123.34)
Amount/
@currencyCode		 Yes Type of currency used for the order String 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/
wiki/ISO_4217.
AddressOverride No Identifies Express Checkout (set to 0) or Standard Checkout (set to 1). String 0, 1
NoShippingAddressDisplay No Hides shipping address on PayPal checkout review page when set to 1. Shows the shipping address when set to 0 or when not specified. When set to 2 will display the shipping address. If the shipping address is not provided it will be obtained from the buyer's account information. String 0, 1, 2
ShipToName No The name of the person shipped to String 128 Characters
ShippingAddress No Address the order will be shipped to. Complex Type Includes: Line1, Line2, Line3, Line4, City, MainDivision, CountryCode, PostalCode
ShippingAddress/
Line1		 Yes Line 1 of the address. String Between 1 and 70 Characters.
ShippingAddress/
Line2		 No Line 2 of the address. String Between 1 and 70 Characters.
ShippingAddress/
Line3		 No Line 3 of the address. String Between 1 and 70 Characters.
ShippingAddress/
Line4		 No Line 4 of the address. String Between 1 and 70 Characters.
ShippingAddress/
City		 Yes City the order will be shipped to. String Between 1 and 40 Characters.
ShippingAddress/
MainDivision		 No This is the State/Province name String Between 1 and 35 Characters. Use of the ISO 3166-2 code is recommended but not required.
ShippingAddress/
CountryCode		 Yes Country the order will be shipped to. String 2 Characters.

Two digit ISO 3166 alpha 2 code country code. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
ShippingAddress/
PostalCode		 No Postal Code the order will be shipped to. String Between 1 and 15 Characters.
ShippingOptions No Shipping options provided for the customer to choose Complex Type Includes: ShippingId and multiple ShippingOption (Applicable for PayPal Version 2 only)
ShippingOptions/
ShippingId		 No It represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the shipping String Between 1 and 127 Characters
ShippingOption No Represent a single shipping option Complex Type Includes: ShippingId, ShippingLabel, DeliveryOption and ShippingCost
ShippingOptions/
ShippingId		 No A unique ID that identifies a payer-selected shipping option. String Between 1 and 127 Characters.
ShippingOptions/
ShippingLabel		 No A description that the payer sees, which helps them choose an appropriate shipping option. For example, Free Shipping, USPS Priority Shipping, Expédition prioritaire USPS, or USPS yōuxiān fā huò. String Between 1 and 127 Characters.
ShippingOptions/
DeliveryOption		 No The method by which the payer wants to get their items. SHIPPING or PICKUP String Between 1 and 15 Characters.
ShippingOptions/
ShippingCost		 No The shipping cost for the selected option. Decimal 2 precision points. (123.34).
ShippingOptions/
@currencyCode		 No Type of currency used for the order String 3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/
wiki/ISO_4217.
LineItems No Represents the items in the Order. Complex Type Includes: LineItemsTotal, ShippingTotal, TaxTotal and multiple LineItem elements.
LineItems/
LineItemsTotal		 Yes Total amount for all line items excluding shipping and tax. Calculated as: LineItemsTotal = (First-LineItem-Quantity * First-LineItem-Amount) + other line items. Decimal 2 precision points. (123.34). Negative is allowed. However, LineItemsTotal + ShippingTotal + TaxTotal cannot be negative.
LineItems/
ShippingTotal		 Yes Total shipping amount for all line items. Decimal 2 precision points. (123.34).
LineItems/
TaxTotal		 Yes Total tax amount for all line items. Decimal 2 precision points. (123.34).
LineItems/
LineItem		 No Represents a single item on the order. Complex Type Includes: Name, SequenceNumber, Quantity, UnitAmount
LineItems/
LineItem/
Name		 Yes Line item name. String No Restrictions.
LineItems/
LineItem/
SequenceNumber		 No Sequence number of current line item in cart if available. String No Restrictions.
LineItems/
LineItem/
Quantity		 Yes Quantity for this line item. Int No Restrictions.
LineItems/
LineItem/
UnitAmount		 Yes Unit price amount for a line item. Decimal 2 precision points. (123.34). Negative is allowed.
Installment (deprecated with latest PayPal upgrade) No Indicates whether this payment will be made using PayPal's Credit installment payment. Boolean true/false
SolutionType (deprecated with latest PayPal upgrade) No Type of checkout flow.
  • Sole - Buyer does not need to create a PayPal account to check out. This is referred to as PayPal Account Optional.
  • Mark - Buyer must have a PayPal account to check out.
 Enum Mark / Sole
SchemaVersion Yes

Although marked as optional in the the schema, this element needs to be passed at all times with a value of 1.1 or greater in order to receive elements like 'ErrorMessage', ‘ShortErrorMessage’, ‘ErrorCode’ in the Response message.

String

pattern = "([0-9]+\.)*[0-9]+".
Value Example: 1.1, 1.2

Recurring No

Recurring is true to set up Vault for recurring payment, else it must be false.

 Boolean true/false
AutoCapture No

If your payment is automatically captured immediately upon authorization, Enable the AutoCapture else Disable it.

 Boolean true/false
CustomerId No

Customer ID is used to link the Vault IDs belonging to the same customer, helping to associate all Vault Ids under a single customer profile.

 String Between 1 and 22 Characters.
MerchantDescriptor No

Merchants to pass their soft description to be displayed on the shoppers PayPal statement, generally business name in short form.

 String Min 1 characters Max 127 characters.

Request Example

The request is a PayPalSetExpressCheckoutRequest message.

Copy 
<?xml version="1.0" encoding="UTF-8"?>
  <PayPalSetExpressCheckoutRequest xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
    <OrderId>12345</OrderId>
    <ReturnUrl><a href="https://urldefense.com/v3/__http://www.webstore.com/return?token=__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKrMJq26I$">http://www.webstore.com/return?token=</a></ReturnUrl>
    <CancelUrl><a href="https://urldefense.com/v3/__http://www.webstore.com/cancel__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKViE86vA$">http://www.webstore.com/cancel</a></CancelUrl>
    <LocaleCode>en_US</LocaleCode>
    <Amount currencyCode="USD">60.00</Amount>
    <MerchantDescriptor&gtPaypal*Amazon*5699 $40.00</MerchantDescriptor>
    <AddressOverride>0</AddressOverride>
    <ShipToName>John Doe</ShipToName>
    <ShippingAddress>
      <Line1>630 Allendale Road</Line1>
      <Line2>Building A</Line2>
      <Line3>2nd Floor</Line3>
      <Line4>Appartment 17</Line4>
      <City>Philadelphia</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19019</PostalCode>
    </ShippingAddress>
    <LineItems>
      <LineItemsTotal currencyCode="USD">20.00</LineItemsTotal>
      <ShippingTotal currencyCode="USD">20.00</ShippingTotal>
      <TaxTotal currencyCode="USD">20.00</TaxTotal>
      <LineItem>
        <Name>Shirt</Name>
        <SequenceNumber>1</SequenceNumber>
        <Quantity>2</Quantity>
        <UnitAmount currencyCode="USD">10.00</UnitAmount>
      </LineItem>
    </LineItems>
    <Recurring>false</Recurring>
    <AutoCapture>false</AutoCapture>
    <Installment>false</Installment>
    <SchemaVersion>1.2</SchemaVersion>
  </PayPalSetExpressCheckoutRequest>

Request Example with Multiple Line Items

The request is a PayPalSetExpressCheckoutRequest message.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>11111123</OrderId>
  <ReturnUrl><a href="https://urldefense.com/v3/__http://webstore.com/return__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKfprQMCI$">http://webstore.com/return</a></ReturnUrl>
  <CancelUrl><a href="https://urldefense.com/v3/__http://webstore.com/cancel__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnK0rNL4L8$">http://webstore.com/cancel</a></CancelUrl>
  <LocaleCode>en_US</LocaleCode>
  <Amount currencyCode="USD">80.00</Amount>
  <ShipToName>John Doe</ShipToName>
  <ShippingAddress>
    <Line1>630 Allendale Road</Line1>
    <City>King of Prussia</City>
    <MainDivision>PA</MainDivision>
    <CountryCode>US</CountryCode>
    <PostalCode>19406</PostalCode>
  </ShippingAddress>
  <LineItems>
    <LineItemsTotal currencyCode="USD">40.00</LineItemsTotal>
    <ShippingTotal currencyCode="USD">25.00</ShippingTotal>
    <TaxTotal currencyCode="USD">15.00</TaxTotal>
    <LineItem>
      <Name>Hat</Name>
      <SequenceNumber>1</SequenceNumber>
      <Quantity>2</Quantity>
      <UnitAmount currencyCode="USD">-10.00</UnitAmount>
    </LineItem>
    <LineItem>
      <Name>Shirt</Name>
      <SequenceNumber>2</SequenceNumber>
      <Quantity>3</Quantity>
      <UnitAmount currencyCode="USD">30.00</UnitAmount>
    </LineItem>
  </LineItems>
  <SchemaVersion>1.2</SchemaVersion>
</PayPalSetExpressCheckoutRequest>

Request Example with ShippingOptions

The request is a PayPalSetExpressCheckoutRequest message.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>11111123</OrderId>
  <ReturnUrl><a href="https://urldefense.com/v3/__http://webstore.com/return__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKfprQMCI$">http://webstore.com/return</a></ReturnUrl>
  <CancelUrl><a href="https://urldefense.com/v3/__http://webstore.com/cancel__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnK0rNL4L8$">http://webstore.com/cancel</a></CancelUrl>
  <LocaleCode>en_US</LocaleCode>
  <Amount currencyCode="USD">80.00</Amount>
  <ShipToName>John Doe</ShipToName>
  <ShippingAddress>
    <Line1>630 Allendale Road</Line1>
    <City>King of Prussia</City>
    <MainDivision>PA</MainDivision>
    <CountryCode>US</CountryCode>
    <PostalCode>19406</PostalCode>
  </ShippingAddress>
  <ShippingOptions>
        <ShippingId>SHIP_123</ShippingId>
        <ShippingOption>
            <ShippingId>SHIP_123</ShippingId>
            <ShippingLabel>1-Day-Shipping</ShippingLabel>
            <DeliveryOption>SHIPPING</DeliveryOption>
            <ShippingCost currencyCode="USD">8.00</ShippingCost>
        </ShippingOption>
        <ShippingOption>
            <ShippingId>SHIP_124</ShippingId>
            <ShippingLabel>Free-Shipping</ShippingLabel>
            <DeliveryOption>SHIPPING</DeliveryOption>
            <ShippingCost currencyCode="USD">0.00</ShippingCost>
        </ShippingOption>
        <ShippingOption>
            <ShippingId>SHIP_456</ShippingId>
            <ShippingLabel>Pick up in Store</ShippingLabel>
            <DeliveryOption>PICKUP</DeliveryOption>
            <ShippingCost currencyCode="USD">0.00</ShippingCost>
        </ShippingOption>
  </ShippingOptions>
  <LineItems>
    <LineItemsTotal currencyCode="USD">40.00</LineItemsTotal>
    <ShippingTotal currencyCode="USD">25.00</ShippingTotal>
    <TaxTotal currencyCode="USD">15.00</TaxTotal>
    <LineItem>
      <Name>Hat</Name>
      <SequenceNumber>1</SequenceNumber>
      <Quantity>2</Quantity>
      <UnitAmount currencyCode="USD">-10.00</UnitAmount>
    </LineItem>
    <LineItem>
      <Name>Shirt</Name>
      <SequenceNumber>2</SequenceNumber>
      <Quantity>3</Quantity>
      <UnitAmount currencyCode="USD">30.00</UnitAmount>
    </LineItem>
  </LineItems>
  <SchemaVersion>1.2</SchemaVersion>
</PayPalSetExpressCheckoutRequest>

Request Example Negative Value for LineItemsTotal

The request is a PayPalSetExpressCheckoutRequest message.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>11111123</OrderId>
  <ReturnUrl><a href="https://urldefense.com/v3/__http://webstore.com/return__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKfprQMCI$">http://webstore.com/return</a></ReturnUrl>
  <CancelUrl><a href="https://urldefense.com/v3/__http://webstore.com/cancel__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnK0rNL4L8$">http://webstore.com/cancel</a></CancelUrl>
  <LocaleCode>en_US</LocaleCode>
  <Amount currencyCode="USD">20.00</Amount>
  <ShippingAddress>
    <Line1>630 Allendale Road</Line1>
    <City>King of Prussia</City>
    <MainDivision>PA</MainDivision>
    <CountryCode>US</CountryCode>
    <PostalCode>19019</PostalCode>
  </ShippingAddress>
  <LineItems>
    <LineItemsTotal currencyCode="USD">-20.00</LineItemsTotal>
    <ShippingTotal currencyCode="USD">25.00</ShippingTotal>
    <TaxTotal currencyCode="USD">15.00</TaxTotal>
    <LineItem>
      <Name>Discount</Name>
      <SequenceNumber>1</SequenceNumber>
      <Quantity>2</Quantity>
      <UnitAmount currencyCode="USD">-10.00</UnitAmount>
    </LineItem>
  </LineItems>
  <SchemaVersion>1.2</SchemaVersion>
</PayPalSetExpressCheckoutRequest>

Vault Creation without Purchase

The request is a PayPalSetExpressCheckoutRequest message.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>11111123</OrderId>
  <ReturnUrl><a href="https://urldefense.com/v3/__http://webstore.com/return__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKfprQMCI$">http://webstore.com/return</a></ReturnUrl>
  <CancelUrl><a href="https://urldefense.com/v3/__http://webstore.com/cancel__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnK0rNL4L8$">http://webstore.com/cancel</a></CancelUrl>
  <LocaleCode>en_US</LocaleCode>
  <Amount currencyCode="USD">0.00</Amount>
  <ShipToName>John Doe</ShipToName>
  <ShippingAddress>
    <Line1>630 Allendale Road</Line1>
    <City>King of Prussia</City>
    <MainDivision>PA</MainDivision>
    <CountryCode>US</CountryCode>
    <PostalCode>19406</PostalCode>
  </ShippingAddress>
  <ShippingOptions>
        <ShippingId>SHIP_123</ShippingId>
        <ShippingOption>
            <ShippingId>SHIP_123</ShippingId>
            <ShippingLabel>1-Day-Shipping</ShippingLabel>
            <DeliveryOption>SHIPPING</DeliveryOption>
            <ShippingCost currencyCode="USD">8.00</ShippingCost>
        </ShippingOption>
        <ShippingOption>
            <ShippingId>SHIP_124</ShippingId>
            <ShippingLabel>Free-Shipping</ShippingLabel>
            <DeliveryOption>SHIPPING</DeliveryOption>
            <ShippingCost currencyCode="USD">0.00</ShippingCost>
        </ShippingOption>
        <ShippingOption>
            <ShippingId>SHIP_456</ShippingId>
            <ShippingLabel>Pick up in Store</ShippingLabel>
            <DeliveryOption>PICKUP</DeliveryOption>
            <ShippingCost currencyCode="USD">0.00</ShippingCost>
        </ShippingOption>
  </ShippingOptions>
  <Recurring>true</Recurring>
  <SchemaVersion>1.2</SchemaVersion>
</PayPalSetExpressCheckoutRequest>

Vault Creation with Purchase

The request is a PayPalSetExpressCheckoutRequest message.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>11111123</OrderId>
  <ReturnUrl><a href="https://urldefense.com/v3/__http://webstore.com/return__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKfprQMCI$">http://webstore.com/return</a></ReturnUrl>
  <CancelUrl><a href="https://urldefense.com/v3/__http://webstore.com/cancel__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnK0rNL4L8$">http://webstore.com/cancel</a></CancelUrl>
  <LocaleCode>en_US</LocaleCode>
  <Amount currencyCode="USD">20.00</Amount>
  <ShippingAddress>
    <Line1>630 Allendale Road</Line1>
    <City>King of Prussia</City>
    <MainDivision>PA</MainDivision>
    <CountryCode>US</CountryCode>
    <PostalCode>19019</PostalCode>
  </ShippingAddress>
  <LineItems>
    <LineItemsTotal currencyCode="USD">-20.00</LineItemsTotal>
    <ShippingTotal currencyCode="USD">25.00</ShippingTotal>
    <TaxTotal currencyCode="USD">15.00</TaxTotal>
    <LineItem>
      <Name>Discount</Name>
      <SequenceNumber>1</SequenceNumber>
      <Quantity>2</Quantity>
      <UnitAmount currencyCode="USD">-10.00</UnitAmount>
    </LineItem>
  </LineItems>
  <Recurring>true</Recurring>
  <SchemaVersion>1.2</SchemaVersion>
</PayPalSetExpressCheckoutRequest>

Vault Creation With Purchase and AutoCapture

The request is a PayPalSetExpressCheckoutRequest message.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>11111123</OrderId>
  <ReturnUrl><a href="https://urldefense.com/v3/__http://webstore.com/return__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKfprQMCI$">http://webstore.com/return</a></ReturnUrl>
  <CancelUrl><a href="https://urldefense.com/v3/__http://webstore.com/cancel__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnK0rNL4L8$">http://webstore.com/cancel</a></CancelUrl>
  <LocaleCode>en_US</LocaleCode>
  <Amount currencyCode="USD">20.00</Amount>
  <ShippingAddress>
    <Line1>630 Allendale Road</Line1>
    <City>King of Prussia</City>
    <MainDivision>PA</MainDivision>
    <CountryCode>US</CountryCode>
    <PostalCode>19019</PostalCode>
  </ShippingAddress>
  <LineItems>
    <LineItemsTotal currencyCode="USD">-20.00</LineItemsTotal>
    <ShippingTotal currencyCode="USD">25.00</ShippingTotal>
    <TaxTotal currencyCode="USD">15.00</TaxTotal>
    <LineItem>
      <Name>Discount</Name>
      <SequenceNumber>1</SequenceNumber>
      <Quantity>2</Quantity>
      <UnitAmount currencyCode="USD">-10.00</UnitAmount>
    </LineItem>
  </LineItems>
  <Recurring>true</Recurring>
  <AutoCapture>true</AutoCapture>
  <SchemaVersion>1.2</SchemaVersion>
</PayPalSetExpressCheckoutRequest>

Response Elements

Element Required Description Type Restriction
OrderId Yes Order identifier. String 20 Characters
ResponseCode Yes Response Code returned from Payment Service. String Success, Failure
Token Yes The timestamped token value that was returned by PayPalSetExpressCheckoutReply and passed on PayPalGetExpressCheckoutRequest. String Generated by PayPal
ErrorMessage No Full Error Description. String Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.2.
ShortErrorMessage No Short Error Description. String Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.2.
ErrorCode No Error code coming from PayPal. String Present only when the ResponseCode is Failure and SchemaVersion in the Request is equal to or greater than 1.2.

Success Response Example

The response is a PayPalSetExpressCheckoutReply message.

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<PayPalSetExpressCheckoutReply xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>12345</OrderId>
  <ResponseCode>Success</ResponseCode>
  <Token>EC-5YE59312K56892714</Token>
</PayPalSetExpressCheckoutReply>

The response is a PayPalSetExpressCheckoutReply message for Vault Creation without purchase. Which has Approval URL.

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<PayPalSetExpressCheckoutReply xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>12345</OrderId>
  <ResponseCode>Success</ResponseCode>
  <Token>EC-5YE59312K56892714</Token>
  <ApprovalUrl><a href="https://urldefense.com/v3/__https://www.sandbox.paypal.com/agreements/approve?approval_session_id=0BG166119J8265422__;!!LRF7QUM!eaCK4tkFHK6-K9bQyLx_A6BK7n8YZx-SOjxbrorR_F4L94eKbRW-fmnz05wtKePQXUnKwDf_vBk$">https://www.sandbox.paypal.com/agreements/approve?approval_session_id=0BG166119J8265422</a></ApprovalUrl>
</PayPalSetExpressCheckoutReply>

Failure Response Example

The response is a PayPalSetExpressCheckoutReply message.

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<PayPalSetExpressCheckoutReply xmlns="<a href="http://api.gsicommerce.com/schema/checkout/1.0">http://api.gsicommerce.com/schema/checkout/1.0</a>">
  <OrderId>12345</OrderId>
  <ResponseCode>Failure</ResponseCode>
  <ErrorMessage>Total Amount does not match line amounts.</ErrorMessage>
  <ShortErrorMessage>Total Amount does not match line amounts.</ShortErrorMessage>
  <ErrorCode>1234</ErrorCode>
</PayPalSetExpressCheckoutReply>

Timeout Response

The response is a XmlFaultReply message.

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <XmlFaultReply xmlns="<a href="http://schema.gsicommerce.com/payments/services/1.0/">http://schema.gsicommerce.com/payments/services/1.0/</a>"
    xmlns:payment="http://schema.gsicommerce.com/payments/types/1.0/">
    <payment:CreateTimestamp>2012-01-26T17:09:07.046Z</payment:CreateTimestamp>
    <payment:Code>SystemProcessingError</payment:Code>
    <payment:Description>A system error has occurred.</payment:Description>
  </XmlFaultReply>

Next Step

After a successful SetExpress call, the next step in the PayPal checkout flow is a GetExpress call.

or PayPal Payment Method Create