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.
|
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]+". |
Request Example
The request is a PayPalSetExpressCheckoutRequest message.
Copy this code sample.
<?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.
Copy this code sample.
<?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.
Copy this code sample.
<?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.
Copy this code sample.
<?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.
Copy this code sample.
<?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.
Copy this code sample.
<?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.
Copy this code sample.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<XmlFaultReply xmlns="http://schema.gsicommerce.com/payments/services/1.0/"
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.