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

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# PayPal Express Flow

> Offer PayPal Express, an accelerated checkout that pulls the buyer's name, email, and shipping address from PayPal.

## PayPal Express

PayPal Express is an accelerated checkout experience that lets buyers quickly complete a purchase using stored PayPal account information. It enables faster checkout flows by retrieving buyer details—such as name, email, and shipping address—directly from PayPal, reducing the need for manual entry and improving conversion.

### Benefits of PayPal Express

* **Streamlined checkout**: Buyer details are pre-filled, avoiding redundant data entry.
* **Improved conversion**: Especially effective on mobile, where users often drop off during form entry.
* **Earlier placement**: Can be embedded on product and cart pages, enabling direct checkout without visiting the full checkout page.
* **Reduced technical complexity**: Shipping address comes from PayPal, minimizing form handling and validation.
* **Supports saved PayPal shipping addresses**: Buyers can reuse previously selected addresses from their PayPal wallet.

### Provider Configuration

Payrails supports two flow types for PayPal, configurable at the provider level. You can change this setting from the integration instance page in the merchant portal for PayPal integrations

| Flow Type | Description |
| - | - |
| **Normal** | Full checkout flow with buyer redirection to PayPal. Includes standard form steps. |
| **Express** | Accelerated checkout. Buyer is redirected to PayPal early, and shipping address can be collected directly from PayPal and returned via notification from Payrails. |

### Handle the shipping address

Shipping address behavior is controlled via the `deliveryAddressPreference` field inside order `meta` object in your Payrails integration.

<Note>
  Note that shipping address can only be collected from PayPal if Express mode as used as described above.
</Note>

| Value | Behavior |
| - | - |
| `"userPreSpecified"` | Buyer selects from saved PayPal addresses **(Default behavior if no other value is sent)** |
| `"noShipping"` | No address is collected or required (e.g., digital goods) |
| `"allowProviderOverride"` | Merchant-supplied address is used and updated on PayPal. Note: if you wish for us to send a merchant-provided shipping address, this value must be specified. |

### Notifications

For all PayPal flows, the selected or provided shipping address is returned in the merchant notification payload as in the below example:

```json theme={null}
"providerResponseAdditionalFields": {
  "purchase_units": [
    {
      "reference_id": "tp_3a8e9555-aa5b-408d-a519-c36e1dd907f1",
      "shipping": {
        "name": {
          "full_name": "John Doe"
        },
        "address": {
          "address_line_1": "Strassburger Strasse",
          "address_line_2": "1",
          "admin_area_2": "Berlin",
          "postal_code": "10405",
          "country_code": "DE"
        }
      }
    }
  ]
}
```


## Related topics

- [PayPal](/docs/orchestration/integrations/paypal.md)
- [How to Accept PayPal Payments](/docs/orchestration/checkout-sdks/android/how-to-accept-paypal-payments.md)
- [API References](/docs/orchestration/checkout-sdks/react-native/api-references.md)