> ## 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 via Braintree

> Set up PayPal payments through Braintree in Payrails, including the PayPal approval redirect and saved PayPal accounts.

<picture noZoom>
  ![PayPal logo](https://assets.payrails.io/img/logos/paypal/logo-full-bleed.svg)
</picture>

<picture noZoom>
  ![Braintree logo](https://assets.payrails.io/img/logos/braintree/logo-full-bleed.svg)
</picture>

Accept [PayPal](https://docs.payrails.com/docs/integrations/payment-methods/paypal) payments with [Braintree](https://www.paypal.com/us/braintree) as the payment service provider (PSP). The customer approves the payment on PayPal and returns to your site, and Payrails completes the payment with Braintree.

## Supported workflows

<table>
  <thead>
    <tr><th>Workflow</th><th>Supported</th></tr>
  </thead>

  <tbody>
    <tr><td>Payrails SDK</td><td>✔</td></tr>
    <tr><td>Payrails API</td><td>✔</td></tr>
    <tr><td>[Delayed / Manual Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Instant Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Cancel / Void](https://docs.payrails.com/docs/orchestration/payment-acceptance/cancel-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Refund / Reverse](https://docs.payrails.com/docs/orchestration/payment-acceptance/refund-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Save Instruments](https://docs.payrails.com/docs/resources/manage-instruments.md)</td><td>✔</td></tr>
    <tr><td>[Merchant Initiated Transaction (MIT)](https://docs.payrails.com/docs/resources/payments/authorization-flags.md)</td><td>✔</td></tr>
    <tr><td>Interoperability</td><td>PSP tokens</td></tr>
  </tbody>
</table>

## Before you begin

Complete these steps before you send your first PayPal payment through Braintree:

1. Set up a Braintree integration in your workspace. Follow the [Braintree integration setup guide](https://docs.payrails.com/docs/integrations/payment-providers/braintree.md) if you don't have one yet.
2. In the Braintree Control Panel, link your PayPal business account to your Braintree account.
3. Add the Payrails domain `api.payrails.io` to the PayPal domain names in Braintree, so that PayPal can return the customer to Payrails.
4. In your Braintree integration in Payrails, set the **Merchant Account ID** to the Braintree merchant account in the currency of your PayPal payments. To accept PayPal in more than one currency, create one Braintree integration per merchant account.
5. To save PayPal accounts for later payments, ask PayPal to enable billing agreements (reference transactions) on your PayPal account.
6. In the Payrails Portal, go to **Settings → Integrations**, open your Braintree integration, select **PayPal** under **Payment methods**, and save.
7. Add PayPal as a [payment option](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md) in your workflow.

## Request fields for Braintree

Send these fields in the authorize request, in addition to the standard [authorize fields](https://docs.payrails.com/reference/authorizeaction.md). **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to the PSP when you include them.

| Field | Status | Description |
| - | - | - |
| `amount` | Required | Sent to PayPal as the payment amount and currency. Use the currency of your Braintree merchant account. An amount of `0` saves the PayPal account without charging it. |
| `meta.order.lines` | Optional | Sent as the line items. When you send lines, include `name`, `quantity` and `unitPrice` on each one. |
| `meta.order.reference` | Optional | Sent as the order ID. Use a new value for every payment: PayPal rejects an order ID it has seen before. |
| `meta.order.description` | Optional | Sent as the billing agreement description when you save the PayPal account. |
| `meta.order.deliveryAddress` | Optional | Sent as the shipping address. Include `country.code` and `street`. |
| `meta.order.softDescriptor` | Optional | Sent as the descriptor name. |
| `meta.order.totalTax`, `meta.order.totalDiscount` | Optional | Sent as the tax and discount amounts. |
| `meta.customer.email` | Optional | Sent as the payer email. |
| `meta.customer.phone` | Optional | Sent as the descriptor phone. |
| `meta.clientContext.ipAddress`, `userAgent`, `deviceFingerprint` | Optional | Sent as risk data for PayPal fraud checks. |
| `instrument.storeInstrument` | Optional | Saves the PayPal account for later payments, including merchant-initiated transactions (MIT). |
| `instrument.data.paymentToken` | Optional | A PayPal nonce from Braintree's client SDK. When you send it, Payrails charges it directly, with no redirect. |

## Authorize a PayPal payment

Call [authorize a payment](https://docs.payrails.com/reference/authorizeaction.md) with `payPal` as the `paymentMethodCode`.

```json Authorize request theme={null}
{
  "amount": {
    "value": "100.00",
    "currency": "USD"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "payPal",
      "amount": {
        "value": "100.00",
        "currency": "USD"
      },
      "storeInstrument": true
    }
  ],
  "meta": {
    "customer": {
      "email": "jane.doe@example.com"
    },
    "order": {
      "reference": "order-1234",
      "description": "Monthly subscription"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}
```

The response includes a redirect to the PayPal approval page. After the customer approves the payment, PayPal returns them to Payrails, and Payrails charges or authorizes the payment with Braintree, depending on your capture mode. If the customer cancels on PayPal, the payment is canceled. Confirm the result through [webhook notifications](https://docs.payrails.com/docs/orchestration/payment-acceptance/receive-notifications.md) or the execution status before you fulfill the order.

## How Braintree handles PayPal

* With instant capture, Payrails charges the payment when the customer returns. With manual capture, Payrails authorizes it, and you capture it later in full or in parts.
* You can refund the full amount or part of it, and cancel an authorized payment.
* When you save the PayPal account, Braintree stores it as a billing agreement and Payrails returns it as a payment instrument. Use it for later subscription or unscheduled payments.
* Braintree doesn't send payment status webhooks for PayPal, so Payrails gets the result when the customer returns from PayPal.


## Related topics

- [PayPal](https://docs.payrails.com/docs/integrations/payment-methods/paypal.md)
- [Braintree (PayPal)](https://docs.payrails.com/docs/integrations/payment-providers/braintree.md)
- [PayPal Express](https://docs.payrails.com/docs/integrations/payment-methods/paypal/paypal-express-flow.md)


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