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 (deprecated with latest PayPal upgrade) | 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]+". |
| @requestId | Yes | RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request ID must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout. | String | 40 Characters |
Note: If you are opting for PayPal Version 2, the DoExpress request can be used to update ShippingAddress, ShipToName, ShippingTotal and TaxTotal.
If the shipping option selected in the setExpress call is changed in the PayPal site, then you should use the changed values from the getExpress reply and alter the shipping values in the doExpress call.
Request Example
The request is a PayPalDoExpressCheckoutRequest message.
Copy
<?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.
Copy
<?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.
Copy
<?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.
Copy
<?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.
Copy
<?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.
Copy
<?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 the successful Paypal DoExpress call, the next step is a DoAuthorize call.