API Description

GetExpress request uses the Token received in the SetExpress response message to retrieve information about the customer (referred to as Payer). The most important and useful element of the information returned in the GetExpress response is PayerId. PayerId is used to uniquely identify the customer and is used in the next call in the PayPal Checkout flow, the DoExpress request.

For Express Checkout Easy Payments, it will return additional financing information in the GetExpress reply.

URI Summary

Action URI Template URI Example Non-URI Request Response
POST /vM.m/stores/[StoreId]/payments/paypal/getExpress.xml /v1.0/stores/AStoreId/
payments/paypal/getExpress.xml
XML 200 + XML Response containing PayPal PayerId.

Request Elements

Element Required Description Type Restriction
StoreId Yes Store Identifier used in the URL. String 20 Characters
OrderId Yes Order Identifier. String 20 Characters
Token Yes The timestamped token value that was returned by PayPalSetExpressCheckoutReply and passed on PayPalGetExpressCheckoutRequest. String Generated by PayPal
CurrencyCode Yes Currency used. NMTOKEN IS-4217 three-letter code
SchemaVersion Yes

Although marked as optional in the the schema, this element needs to be passed at all times with a value of 1.2 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 PayPalGetExpressCheckoutRequest message.

Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<PayPalGetExpressCheckoutRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <Token>EC-5YE59312K56892714</Token>
  <CurrencyCode>USD</CurrencyCode>
  <SchemaVersion>1.2</SchemaVersion>
</PayPalGetExpressCheckoutRequest>

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
PayerEmail No Email address of the payer. String 127 single-byte characters.
PayerId No Unique identifier of the customer's PayPal account. Not Present in case of failure. String 127 single-byte characters.
PayerStatus No Status of payer's email address. String Status coming from PayPal.
PayerName No Name of payer. Complex Type Includes: Honorific, LastName, MiddleName, FirstName.
Honorific No Salutation for the Payer String 10 Characters.
LastName Yes Last Name of the Payer String 64 Characters.
MiddleName No Middle Name of the Payer String 40 Characters.
FirstName Yes First Name of the Payer String 64 Characters.
PayerCountry No Payment sender's country of residence. String 2 Characters.

Two digit ISO 3166 alpha 2 code country code. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.

BillingAddress No Payer's business address on file with PayPal. Complex Type Includes: Line1, Line2, Line3, Line4, City, MainDivision, CountryCode, PostalCode
Line1 Yes Line 1 of the address String Between 1 and 70 Characters.
Line2 No Line 2 of the address String Between 1 and 70 Characters.
Line3 No Line 3 of the address String Between 1 and 70 Characters.
Line4 No Line 4 of the address String Between 1 and 70 Characters.
City Yes City the order will be shipped to. String Between 1 and 40 Characters.
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.
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.

PostalCode No Postal Code the order will be shipped to. String Between 1 and 15 Characters.
AddressStatus No Indicates the status of the address String Confirmed or Unconfirmed or none
PayerPhone No Payer's business address on file with PayPal String No Restrictions.
ShippingAddress No Shipping address selected by Payer on PayPal pages. Complex Type Inner elements same as the BillingAddress elements.
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.
PaymentInfo (deprecated with latest PayPal upgrade) No Additional financing information for Express Checkout Easy Payments Complex Type Includes: FinancingApproved, FinancingFeeAmount, FinancingTerm, FinancingMonthlyPayment, FinancingTotalCost
FinancingApproved (deprecated with latest PayPal upgrade) No Indicates whether the customer was approved for and chose to make payment using Easy Payments Boolean true/false
FinancingFeeAmount (deprecated with latest PayPal upgrade) No Fee amount the customer has to pay during the lifetime of the loan Decimal 2 precision points. (123.34)
currencyCode Yes if Financing Fee Amount is present Code identifies the currency for the Amount. String IS-4217 three-letter code
FinancingTerm (deprecated with latest PayPal upgrade) No Indicates the payment term. Example values are 6, 12, 18, and 24 months. Int No Restrictions.
FinancingMonthlyPayment (deprecated with latest PayPal upgrade) No Estimated amount per month that the customer will need to pay including fees and interests. Decimal 2 precision points. (123.34)
currencyCode Yes if Financing Monthly Payment is present Code identifies the currency for the Amount. String IS-4217 three-letter code
FinancingTotalCost (deprecated with latest PayPal upgrade) No Estimated total payment amount including fees and interests the user will pay during the lifetime of the loan. Decimal 2 precision points. (123.34)
currencyCode Yes if Financing Total Cost is present Code identifies the currency for the Amount. String IS-4217 three-letter code
CartChangeTolerance (deprecated with latest PayPal upgrade) No Indicate the tolerance a cart can be changed.
Possible values are

NONE = cart cannot be changed (since financing was used and country is DE).

FLEXIBLE = cart can be changed

If this parameter does not exist, then assume cart can be modified.
String NONE, FLEXIBLE
ShipToName No Name associated with the shipping address. String Present only when SchemaVersion in the Request is greater than or equal to 1.2
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 Identifier represents the shipping option that the payer selected in the PayPal site among the shipping options sent in SetExpress call. String Between 1 and 127 Characters
ShippingOption No Represents 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.

Successful Response Example

The response is a PayPalGetExpressCheckoutReply message.

Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<PayPalGetExpressCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Success</ResponseCode>
  <PayerEmail>payer@gmail.com</PayerEmail>
  <PayerId>CNQNHXX9RCE9S</PayerId>
  <PayerStatus>Verified</PayerStatus>
  <PayerName>
    <Honorific>Mr.</Honorific>
    <LastName>Smith</LastName>
    <MiddleName>Michael</MiddleName>
    <FirstName>John</FirstName>
  </PayerName>
  <PayerCountry>US</PayerCountry>
  <BillingAddress>
    <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>
    <AddressStatus>Confirmed</AddressStatus>
  </BillingAddress>
  <PayerPhone>2152221111</PayerPhone>
  <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>
  <ShipToName>John Doe</ShipToName>
  <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>
  </ShippingOptions>
</PayPalGetExpressCheckoutReply>

Successful Response Example with Different Billing and Shipping Address

The response is a PayPalGetExpressCheckoutReply message.

Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<PayPalGetExpressCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>559749</OrderId>
  <ResponseCode>Success</ResponseCode>
  <PayerEmail>chopuk_1326139738_per@gsicommerce.com</PayerEmail>
  <PayerId>CNQNHXX9RCE9S</PayerId>
  <PayerStatus>verified</PayerStatus>
  <PayerName>
    <LastName>User</LastName>
    <FirstName>Test</FirstName>
  </PayerName>
  <PayerCountry>GB</PayerCountry>
  <BillingAddress>
    <Line1>49 Featherstone Street</Line1>
    <Line2/>
    <City>LONDON</City>
    <MainDivision>London</MainDivision>
    <CountryCode>GB</CountryCode>
    <PostalCode>EC1Y 8SY</PostalCode>
    <AddressStatus>Confirmed</AddressStatus>
  </BillingAddress>
  <PayerPhone>+44 3565606206</PayerPhone>
  <ShippingAddress>
    <Line1>49 Queen Blvd</Line1>
    <Line2/>
    <City>Manchester</City>
    <MainDivision>Manchester</MainDivision>
    <CountryCode>GB</CountryCode>
    <PostalCode>MU1Y 8SY</PostalCode>
  </ShippingAddress>
  <ShipToName>John Doe</ShipToName>
</PayPalGetExpressCheckoutReply>

Successful Response Example with Express Checkout Easy Payments

The response is a PayPalGetExpressCheckoutReply message.

Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<PayPalGetExpressCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Success</ResponseCode>
  <PayerEmail>payer@gmail.com</PayerEmail>
  <PayerId>CNQNHXX9RCE9S</PayerId>
  <PayerStatus>Verified</PayerStatus>
  <PayerName>
    <Honorific>Mr.</Honorific>
    <LastName>Smith</LastName>
    <MiddleName>Michael</MiddleName>
    <FirstName>John</FirstName>
  </PayerName>
  <PayerCountry>US</PayerCountry>
  <BillingAddress>
    <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>
    <AddressStatus>Confirmed</AddressStatus>
  </BillingAddress>
  <PayerPhone>2152221111</PayerPhone>
  <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>
  <PaymentInfo>
    <FinancingApproved>true</FinancingApproved>
    <FinancingFeeAmount currencyCode=USD>26.79</FinancingFeeAmount>
    <FinancingTerm>24</FinancingTerm>
    <FinancingMonthlyPayment currencyCode=USD>426.89</FinancingMonthlyPayment>
    <FinancingTotalCost currencyCode=USD>485.35.79</FinancingTotalCost>
  </PaymentInfo>
  <CartChangeTolerance>NONE</CartChangeTolerance>
  <ShipToName>John Doe</ShipToName>
</PayPalGetExpressCheckoutReply>

Failure Response Example

The response is a PayPalGetExpressCheckoutReply message.

Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<PayPalGetExpressCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Failure</ResponseCode>
  <PayerEmail></PayerEmail>
  <PayerId></PayerId>
  <PayerStatus>Unverified</PayerStatus>
  <PayerName>
    <Honorific></Honorific>
    <LastName></LastName>
    <MiddleName></MiddleName>
    <FirstName></FirstName>
  </PayerName>
  <ErrorMessage>Invalid Token.</ErrorMessage>
  <ShortErrorMessage>Invalid Token.</ShortErrorMessage>
  <ErrorCode>1234</ErrorCode>
</PayPalGetExpressCheckoutReply>

Timeout Response Example

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 GetExpress call, the next step is a DoExpress call.