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

# PayPal Wallet

> Accept PayPal payments through PayNext.

To pay using PayPal, customers are redirected from your website to PayPal. They choose a funding source: PayPal wallet, linked card, or bank account.

## Payment Method Details

|                            |                                                                      |
| :------------------------- | :------------------------------------------------------------------- |
| **Customer locations**     | Worldwide                                                            |
| **Supported currencies**   | EUR, GBP, USD, CHF, CZK, DKK, NOK, PLN, SEK, AUD, CAD, HKD, NZD, SGD |
| **Recurrent payments**     | ✓                                                                    |
| **Manual capture support** | ✓                                                                    |
| **Refunds**                | ✓                                                                    |
| **Supported processors**   | <Badge>PayPal</Badge>                                                |

## Prerequisites

1. Connect and activate the [PayPal integration](/integrations/processors/paypal) in PayNext
2. Turn on PayPal in your PayNext checkout configuration

## Testing

<Steps>
  <Step title="Configure sandbox credentials">
    Use PayPal Sandbox credentials in your PayNext integration
  </Step>

  <Step title="Make a test payment">
    Complete a PayPal payment via PayNext SDK on your website
  </Step>

  <Step title="Verify payment">
    Confirm the payment appears in the PayNext dashboard and check the statement descriptor
  </Step>
</Steps>

## Dynamic Statement Descriptor <Badge>Advanced</Badge>

When enabled, PayNext generates a unique code and passes it as the PayPal soft descriptor. This helps match transactions with chargeback alert providers (Visa CDRN, Ethoca), allowing you to refund before a dispute occurs. You can also use the descriptor to retrieve payment history when a customer forgot their account details or can't access their account.

### How It Works

PayPal statement descriptors follow this format:

```
PAYPAL * + Merchant Descriptor + Soft Descriptor
```

The total is limited to **22 characters**. The `PAYPAL *` prefix takes 8 characters, leaving 14 characters for your merchant name and the dynamic code.

<Tip>
  Enable this feature in **Dashboard → Integrations → PayPal → Enable PayPal dynamic statement descriptor**.
</Tip>

### Descriptor Length Examples

Your **merchant descriptor** is configured in your PayPal account under Business Profile settings.

<AccordionGroup>
  <Accordion title="Short merchant name (recommended)">
    If your merchant descriptor is **8 characters or less** (e.g., `PRODUCT`), you get room for a 4-character dynamic code:

    ```
    PAYPAL *PRODUCT *DA3A
    ```

    The number of unique combinations depends on the code length:

    | Code Length  | Unique Combinations |
    | :----------- | :------------------ |
    | 5 characters | 60,466,176          |
    | 4 characters | 1,679,616           |
    | 3 characters | 46,656              |
  </Accordion>

  <Accordion title="Long merchant name (truncated)">
    If your merchant descriptor is longer (e.g., `CEREBRUM IQ`), the dynamic code gets truncated:

    ```
    PAYPAL *CEREBRUM IQ *D
    ```

    Only 1 character remains for the code, reducing uniqueness significantly.
  </Accordion>
</AccordionGroup>

<Warning>
  Keep your PayPal merchant descriptor to **8 characters or less** to ensure at least 3 characters are available for the dynamic code. Using fewer than 3 characters is not recommended as it significantly reduces the effectiveness of transaction matching.
</Warning>

### Card vs Wallet Payments

PayPal automatically selects the best funding source for the customer. The descriptor format tells you which was used:

| Funding Source                     | Descriptor Example      |
| :--------------------------------- | :---------------------- |
| **Credit/Debit Card**              | `PAYPAL *MYSTORE *JK0O` |
| **PayPal Balance or Bank Account** | `*9VHI6`                |

<Note>
  If you see a short descriptor like `*9VHI6` instead of the full `PAYPAL *...` format, the payment was processed from the customer's PayPal balance or linked bank account—not a card.
</Note>

### Where The Descriptor Appears

* Searchable by and available for each payment in the dashboard
* `statement_descriptor` field in the payment object

## If the customer cancels the billing agreement

A customer can cancel the PayPal billing agreement from their PayPal account. PayNext receives that from PayPal and sets the payment method `status` to `revoked`.

A revoked payment method can't be charged. Renewals stop being attempted—the aborted attempt is recorded as `INCOMPLETE` with `decline_code` `payment_method_disabled`—and the subscription stays `past_due` for 14 days before it is cancelled with reason `dead_instrument`. See [Dead payment methods](/guides/use-cases/recover-subscriptions#dead-payment-methods).

Each change is reported by [`customer.payment_method.updated`](/webhooks/introduction/event-types#payment-method-events).