Payments & Fraud

How It Works

Dashboard

This documentation site is retired and will soon be removed. Current information can be found at the new documentation portal here! Please update your bookmarks.

Radial Payments & Fraud Documentation

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 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.

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.	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.
Recurring (deprecated with latest PayPal upgrade)	No	Set up billing agreement for recurring payment when Recurring is true.	Boolean	true/false
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

Request Example

The request is a PayPalSetExpressCheckoutRequest message.

<?xml version="1.0" encoding="UTF-8"?>
  <PayPalSetExpressCheckoutRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <OrderId>12345</OrderId>
    <ReturnUrl>http://www.webstore.com/return?token=</ReturnUrl>
    <CancelUrl>http://www.webstore.com/cancel</CancelUrl>
    <LocaleCode>en_US</LocaleCode>
    <Amount currencyCode="USD">60.00</Amount>
    <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>
    <Installment>false</Installment>
    <SchemaVersion>1.2</SchemaVersion>
  </PayPalSetExpressCheckoutRequest>

Request Example with Multiple Line Items

The request is a PayPalSetExpressCheckoutRequest message.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>11111123</OrderId>
  <ReturnUrl>http://webstore.com/return</ReturnUrl>
  <CancelUrl>http://webstore.com/cancel</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.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>11111123</OrderId>
  <ReturnUrl>http://webstore.com/return</ReturnUrl>
  <CancelUrl>http://webstore.com/cancel</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.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PayPalSetExpressCheckoutRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>11111123</OrderId>
  <ReturnUrl>http://webstore.com/return</ReturnUrl>
  <CancelUrl>http://webstore.com/cancel</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>

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.

Successful Response Example

The response is a PayPalSetExpressCheckoutReply message.

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

Failure Response Example

The response is a PayPalSetExpressCheckoutReply message.

<?xml version="1.0" encoding="UTF-8"?>
<PayPalSetExpressCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <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.


<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <CreateTimestamp>2018-08-17T17:36:20.482+05:30</CreateTimestamp>
   <Code>SystemProcessingError</Code>
   <Description>A system error has occurred.</Description>
</Fault>

Next Step

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

Return to top

What are you waiting for?