> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# PAYPALEXPRESS- (PayPal Express Checkout)

> Read the data that PayPal returns during Express Checkout: buyer details, order amounts, the delivery address taken over from PayPal, and the status values of the transaction.

With PayPal Express Checkout, the buyer starts the payment process while still in the basket. They log in to PayPal, and PayPal sends them back to the shop with their data: name, email address, delivery address, and the amounts the process covers. The shop system stores this response, and the `PAYPALEXPRESS-` tags retrieve individual fields from it.

Guide: PayPal Express Checkout

## When the tags work

The tags are tied to Express Checkout. They return something in exactly two cases: while the buyer is in Express Checkout, and after a completed order that went through Express Checkout. In any other case, they are treated as an invalid tag, regardless of the template.

`ST-PayPalExpressCheckout_selected` checks exactly this condition. Wrap your block with it, and it will appear on the page whenever the tags in it also have values.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{ST-PayPalExpressCheckout_selected}
   <p>Sie zahlen über PayPal als ~PAYPALEXPRESS-FIRSTNAME~ ~PAYPALEXPRESS-LASTNAME~.</p>
{/ST-PayPalExpressCheckout_selected}
```

Reference: ST- (Page states)

> [!WARNING]
>
> The tags apply exclusively to the classic PayPal Express Checkout. The newer express variants via PayPal Checkout, Google Pay, and Apple Pay run via their own states, and you cannot access their data via these tags.

## The construction principle

There is no fixed list of tags. The shop system stores the response from PayPal as a list of field names and values and, when resolving a tag, simply searches for the name after `PAYPALEXPRESS-`. Every field that PayPal returns is therefore accessible, even if it is not listed below.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{PAYPALEXPRESS-<Feldname von PayPal>}
   ~PAYPALEXPRESS-<Feldname von PayPal>~
{/PAYPALEXPRESS-<Feldname von PayPal>}
```

> [!NOTE]
>
> A field name that the response does not contain is not an error. The single tag then outputs nothing and the range tag does not apply. PayPal only returns many fields under certain circumstances, so using a range tag is worthwhile for almost every field.

> [!NOTE]
>
> Upper and lower case in the field name do not matter. The uppercase spelling on this page follows PayPal's spelling and makes it visible at a glance in the template that the value comes from outside.

> [!NOTE]
>
> The values are output HTML-encoded and have already been converted to the shop's character set. The shop system replaces line breaks within a value with spaces, so that no field breaks the layout.

## Buyer and transaction

| Tag | Returns |
| - | - |
| `PAYPALEXPRESS-FIRSTNAME` | the buyer's first name |
| `PAYPALEXPRESS-LASTNAME` | the buyer's last name |
| `PAYPALEXPRESS-EMAIL` | the email address stored at PayPal |
| `PAYPALEXPRESS-COUNTRYCODE` | the buyer's country code |
| `PAYPALEXPRESS-PAYERID` | the identifier of the PayPal account |
| `PAYPALEXPRESS-PAYERSTATUS` | the verification status of the PayPal account |
| `PAYPALEXPRESS-TOKEN` | the token of the process |
| `PAYPALEXPRESS-CORRELATIONID` | the identifier of the response from PayPal |
| `PAYPALEXPRESS-CHECKOUTSTATUS` | the status of the payment |
| `PAYPALEXPRESS-BILLINGAGREEMENTACCEPTEDSTATUS` | whether the buyer has agreed to a billing agreement |

> [!NOTE]
>
> `PAYPALEXPRESS-CORRELATIONID` is the identifier that PayPal support asks for when a process needs to be clarified. It therefore belongs in logging or in a comment in the source code of the confirmation page, not visibly on the page.

### Status values

`PAYPALEXPRESS-PAYERSTATUS` indicates whether PayPal has verified the buyer's account.

| Value | Meaning |
| - | - |
| `verified` | verified account |
| `unverified` | unverified account |

`PAYPALEXPRESS-BILLINGAGREEMENTACCEPTEDSTATUS` concerns recurring payments.

| Value | Meaning |
| - | - |
| `0` | not agreed |
| `1` | agreed |

`PAYPALEXPRESS-CHECKOUTSTATUS` indicates how far the payment has progressed.

| Value | Meaning |
| - | - |
| `PaymentActionNotInitiated` | not yet initiated |
| `PaymentActionInProgress` | in progress |
| `PaymentActionCompleted` | completed |
| `PaymentActionFailed` | failed |

## The order amounts

The amounts are found under the name component `PAYMENTREQUEST_0_`. The zero in it is the sequential number of the payment request, and in the shop system there is always exactly one.

| Tag | Returns |
| - | - |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_CURRENCYCODE` | the currency code |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_AMT` | the total amount |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_ITEMAMT` | the total of the products |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPPINGAMT` | the shipping costs |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_HANDLINGAMT` | the handling costs |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_TAXAMT` | the taxes |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_INSURANCEAMT` | the insurance costs |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPDISCAMT` | the shipping discount |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED` | whether insurance was offered |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SELLERPAYPALACCOUNTID` | the identifier of the seller |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_CUSTOM` | a freely assignable field |

> [!WARNING]
>
> Only the currency code and the total amount are reliably filled. PayPal only returns all other amounts if the shop sent them with the request. Wrap each individual line in a range tag, otherwise there will be labels without values on the page.

> [!WARNING]
>
> These amounts are the values under which PayPal manages the process. They are not the basket totals. For display to the buyer, use the shop's basket and order tags. The values here are suitable for comparison if the amount and the order seem to diverge.

## The delivery address from PayPal

With Express Checkout, the delivery address comes from PayPal. It is also found under `PAYMENTREQUEST_0_`.

| Tag | Returns |
| - | - |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTONAME` | the name of the recipient |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOSTREET` | the street |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOZIP` | the postal code |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOCITY` | the city |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOSTATE` | the federal state or state |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE` | the country code |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME` | the country name |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_ADDRESSSTATUS` | the verification status of the address at PayPal |
| `PAYPALEXPRESS-PAYMENTREQUEST_0_ADDRESSNORMALIZATIONSTATUS` | the normalization status of the address |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{ST-PayPalExpressCheckout_selected}
   {PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTONAME}
      <h3>Lieferadresse von PayPal</h3>
      <p>
         ~PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTONAME~<br>
         ~PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOSTREET~<br>
         ~PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOZIP~ ~PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOCITY~<br>
         {PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOSTATE}~PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOSTATE~<br>{/PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOSTATE}
         ~PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME~
      </p>
   {/PAYPALEXPRESS-PAYMENTREQUEST_0_SHIPTONAME}
{/ST-PayPalExpressCheckout_selected}
```

> [!NOTE]
>
> `SHIPTOSTATE` is usually empty in Germany and always filled in the United States. Wrap the line in a range tag, otherwise there will be an empty line in the middle of the block for German addresses.

### The verification status of the address

`PAYPALEXPRESS-PAYMENTREQUEST_0_ADDRESSSTATUS` indicates whether PayPal has verified the address.

| Value | Meaning |
| - | - |
| `none` | not specified |
| `Confirmed` | confirmed |
| `Unconfirmed` | not confirmed |

`PAYPALEXPRESS-PAYMENTREQUEST_0_ADDRESSNORMALIZATIONSTATUS` concerns addresses in Brazil only.

| Value | Meaning |
| - | - |
| `None` | no normalization |
| `Normalized` | normalized |
| `Unnormalized` | not normalized |
| `UserPreferred` | the buyer kept their own spelling |

## The tags at a glance

| Tag | Single tag | Range tag | Negative range tag | Loop tag |
| - | - | - | - | - |
| `PAYPALEXPRESS-<Feldname von PayPal>` | yes | yes | yes | – |

The tags are permitted on all templates, but only return a value in Express Checkout and after an order completed through it.

## Related topics

* Guide: PayPal Express Checkout
* Reference: ST- (Page states)
* Reference: PAY- (Displaying and selecting payment methods)


## Related topics

- [checkout - Order flow](https://dokumentation.websale.de/en/konfiguration/checkout-bestellablauf.md)
- [Buttons for payment methods](https://dokumentation.websale.de/en/v8s/referenz/tags/bt/zahlungsarten.md)
- [PPC- (PayPal Checkout)](https://dokumentation.websale.de/en/v8s/referenz/tags/ppc-paypal-checkout.md)
- [$wsPayPalCheckout - PayPal](https://dokumentation.websale.de/en/frontend/referenz/module/wspaypalcheckout.md)
- [payment - Payment methods](https://dokumentation.websale.de/en/konfiguration/payment-zahlungsmethoden.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.