Radial Integration | 2016

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

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.

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>USA</CountryCode>
      <PostalCode>19001</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.1</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.1</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>19406</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.1</SchemaVersion>
</PayPalSetExpressCheckoutRequest>

Response Elements

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" 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>SocketTimeoutException</payment:Code>
    <payment:Description>Read timed out</payment:Description>
  </XmlFaultReply>

Next Step

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

Copyright © 2017 Radial. All rights reserved.