PayPal DoExpress

Overview

The PayPal DoExpress request uses the Token and PayerId elements retrieved from the SetExpress and GetExpress responses. DoExpress is used to place a PayPal order and return a TransactionId which is the identifier for the PayPal order. The TransactionId is also used as the as the Billing Agreement Id if this order is part of a recurring order (Recurring flag is set to true in the SetExpress request).

URI Summary

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

Request Elements

When preparing the request, consider the following data notes:

  • Negative Line Items Amounts are allowed and can be used to apply discounts, and LineItemsTotal can also be negative. However, the sum of LineItemsTotal + ShippingTotal + TaxTotal, which equals the request Amount, cannot be negative.
  • PickUpStoreId should be sent only if the intent is to ship to the store.
  • TransactionId serves as the Billing Agreement Id if the Recurring flag is set to true in the SetExpress request.
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
PayerId No Unique identifier of the customer's PayPal account. Not Present in case of failure. String 127 single-byte characters.
Amount Yes Represents order total amount, which is the sum of LineItemsTotal + ShippingTotal + TaxTotal. Decimal 2 precision points. (123.34)
currencyCode Yes Code identifies the currency for the Amount. String IS-4217 three-letter code
PickUpStoreId No PickUpStoreId refers to store name and number for ship-to-store or in-store-pickup. Formatted like "StoreName StoreNumber". String No restrictions.
ShipToName No The name of the person shipped to. Formatted like "FirsName LastName". String No restrictions.
ShippingAddress No Address the order will be shipped to. 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 The State or Province of the address. 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.
LineItems No Represents the items in the Order. Complex Type Includes: LineItemsTotal, ShippingTotal, TaxTotal and Multiple LineItem elements.
LineItemsTotal Yes Total amount for all line items excluding shipping and tax. Calculation works as follows 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.
ShippingTotal Yes Total shipping amount for all line items. Decimal 2 precision points. (123.34).
TaxTotal Yes Total tax amount for all line items. Decimal 2 precision points. (123.34).
LineItem No/Can be multiple Represents a single item on the order. Complex Type Includes: Name, SequenceNumber, Quantity, UnitAmount
Name Yes Line item name. String No Restrictions.
SequenceNumber No Sequence number of current line item in cart if available. String No Restrictions.
Quantity Yes Quantity for this line item. Int No Restrictions.
UnitAmount Yes Unit price amount for a line item. Decimal 2 precision points. (123.34). Negative is allowed.
Recurring No Set up billing agreement for recurring payment when Recurring is true. Boolean true/false
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

@requestId Yes The requestId value globally identifies a request message and is used to protect against duplicate request processing. String 40 Characters

Request Example

The request is a PayPalDoExpressCheckoutRequest message.

<?xml version="1.0" encoding="UTF-8"?>
  <PayPalDoExpressCheckoutRequest
       xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567">
    <OrderId>12345</OrderId>
    <Token>EC-5YE59312K56892714</Token>
    <PayerId>CNQNHXX9RCE9S</PayerId>
    <Amount currencyCode="USD">60.00</Amount>
    <PickUpStoreId>AStoreId</PickUpStoreId>
    <ShipToName>John Smith</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>
    <SchemaVersion>1.1</SchemaVersion>
  </PayPalDoExpressCheckoutRequest>    

Request Example with Multiple Line Items

The request is a PayPalDoExpressCheckoutRequest message.

<?xml version="1.0" encoding="UTF-8"?>
  <PayPalDoExpressCheckoutRequest
       xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567">
    <OrderId>1234567</OrderId>
    <Token>EC-5YE59312K56892714</Token>
    <PayerId>PayerId0</PayerId>
    <Amount currencyCode="USD">115.00</Amount>
    <ShipToName>John Smith</ShipToName>
    <ShippingAddress>
      <Line1>123 Main St.</Line1>
      <City>Philadelphia</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19019</PostalCode>
    </ShippingAddress>
    <LineItems>
      <LineItemsTotal currencyCode="USD">100.00</LineItemsTotal>
      <ShippingTotal currencyCode="USD">10.00</ShippingTotal>
      <TaxTotal currencyCode="USD">5.00</TaxTotal>
      <LineItem>
        <Name>Product A</Name>
        <SequenceNumber>1</SequenceNumber>
        <Quantity>1</Quantity>
        <UnitAmount currencyCode="USD">50.00</UnitAmount>
      </LineItem>
      <LineItem>
        <Name>Product B</Name>
        <SequenceNumber>2</SequenceNumber>
        <Quantity>1</Quantity>
        <UnitAmount currencyCode="USD">50.00</UnitAmount>
      </LineItem>
    </LineItems>
  </PayPalDoExpressCheckoutRequest>

Request Example with Negative Line Item Amount

The request is a PayPalDoExpressCheckoutRequest message.

<?xml version="1.0" encoding="UTF-8"?>
  <PayPalDoExpressCheckoutRequest
      xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567">
    <OrderId>1234567</OrderId>
    <Token>EC-5YE59312K56892714</Token>
    <PayerId>PayerId0</PayerId>
    <Amount currencyCode="USD">55.00</Amount>
    <ShipToName>John Smith</ShipToName>
    <ShippingAddress>
      <Line1>123 Main St.</Line1>
      <City>Philadelphia</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19019</PostalCode>
    </ShippingAddress>
    <LineItems>
      <LineItemsTotal currencyCode="USD">40.00</LineItemsTotal>
      <ShippingTotal currencyCode="USD">10.00</ShippingTotal>
      <TaxTotal currencyCode="USD">5.00</TaxTotal>
      <LineItem>
        <Name>Product A</Name>
        <SequenceNumber>1</SequenceNumber>
        <Quantity>1</Quantity>
        <UnitAmount currencyCode="USD">50.00</UnitAmount>
      </LineItem>
      <LineItem>
        <Name>Discount</Name>
        <SequenceNumber>2</SequenceNumber>
        <Quantity>1</Quantity>
        <UnitAmount currencyCode="USD">-10.00</UnitAmount>
      </LineItem>
    </LineItems>
  </PayPalDoExpressCheckoutRequest>

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
TransactionID Yes A transaction identification number. Identifies the Order on PayPal's site. It also serves as Billing Agreement Id in the case of a Recurring Payment. String Length: 19 Characters.
PaymentInfo No Details of the transaction. PayPalPaymentInfoType Includes: PaymentStatus, PaymentReason, PaymentCode
PaymentStatus No Status on the transaction on PayPal's site. String 64 Characters
PaymentReason No Reason the transaction's status on PayPal's site. String 64 Characters
PaymentCode No Code associated with the transaction on PayPal's site. String 64 Characters
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.1.
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.1.
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.1.

Successful Response Example

The response is a PayPalDoExpressCheckoutReply message.

<?xml version="1.0" encoding="UTF-8"?>
<PayPalDoExpressCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Success</ResponseCode>
  <TransactionID>O-3A919253XG323924A</TransactionID>
  <PaymentInfo>
    <PaymentStatus>Pending</PaymentStatus>
    <PendingReason>Order</PendingReason>
    <ReasonCode>12345</ReasonCode>
  </PaymentInfo>
</PayPalDoExpressCheckoutReply>

Failure Response Example

The response is a PayPalDoExpressCheckoutReply message.

<?xml version="1.0" encoding="UTF-8"?>
<PayPalDoExpressCheckoutReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <OrderId>12345</OrderId>
  <ResponseCode>Failure</ResponseCode>
  <PaymentInfo>
    <PaymentStatus>None</PaymentStatus>
    <PendingReason>None</PendingReason>
    <ReasonCode>None</ReasonCode>
  </PaymentInfo>
  <ErrorMessage>Invalid Token.</ErrorMessage>
  <ShortErrorMessage>Invalid Token.</ShortErrorMessage>
  <ErrorCode>1234</ErrorCode>
</PayPalDoExpressCheckoutReply>

Timeout Response Example

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