PayPal GetExpress
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]+". |
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.