# PayPal Module

https://docs.wisecp.com/de/paypal-module

Send clients to PayPal to pay with their PayPal balance or a linked card, and let recurring lines run as a PayPal subscription.

## Reaching the Screen

Go to **Settings → Financial → Payment Gateways**, open **All Modules** and click the **PayPal** card: `{admin}/modules/payment?module=PayPal`

Adding the gateway to the method list clients see is covered in [Payment Modules](https://docs.wisecp.com/en/payment-modules).

## What Is on the Screen

Two tabs. **General Settings** holds the PayPal credentials and the shared gateway settings; **Subscription Settings** holds the recurring payment options. A **Test Connection** button sits next to the save button.

The client picks this method and moves to PayPal to pay. When the client approves the payment there and returns to your site, the amount is collected, the invoice becomes paid and the order is activated.

The module also opens subscriptions. From the invoice screen it refunds only a payment that closed several invoices; see Tasks. It does not store cards, does not show a card form on your site, and does not offer installments.

## Before You Configure It

- A PayPal business account. Live credentials go to a verified business account, while the sandbox works with a developer account alone.
- An application created in the PayPal developer dashboard. It gives you a client ID and a client secret.
- Separate credentials for the sandbox and the live environment. A live client ID does not work against the sandbox.

## Fields

### General Settings

- **Client ID**: The client ID of your PayPal application. Required.
- **Client Secret**: The secret of the same application. It is hidden while you type. Required.
- **Email**: The email address of your PayPal account. Optional. Only classic payment notifications are checked against it, and this version settles payments on the client's return instead. It can stay empty.
- **Sandbox**: Tick to work against the PayPal test environment with the sandbox credentials. Off by default.

**Status**, **Commission Rate (%)**, **Accepted Amount Range** and the country lists work the same way in every gateway. See [Payment Modules](https://docs.wisecp.com/en/payment-modules). **Callback URL**, **Success URL** and **Failed URL** cannot be edited. You register nothing at PayPal: the module sends the return address with every payment.

**Converting Currency** is on the form, but this module does not apply it in the current version. Invoices in Turkish lira always reach PayPal converted to US dollars. Every other currency is sent as it is, whatever you pick there.

### Subscription Settings

- **Enable Subscription**: Has no effect in the current version. The subscribe option is offered for renewable lines whether or not it is ticked.
- **Force Subscription**: Removes the one-time payment option, so a client paying with PayPal can only subscribe. Off by default.
- **Update Subscription Fee**: Carries price changes to existing subscriptions.

## Tasks

### Take the credentials from PayPal

1. Sign in to the PayPal developer dashboard and open **Apps & Credentials**.
2. Set the **Sandbox** or **Live** toggle to the environment you will use. Each one issues its own credentials.
3. Click **Create App**, name it and pick the **Merchant** type. A new account already carries a **Default Application** you can use instead.
4. Open the application and copy **Client ID** and **Secret** from the top of its page.

### Enter the credentials and test them

1. Open the module card and tick **Status**. The other fields stay locked until you do.
2. On **General Settings** fill in **Client ID** and **Client Secret**, and set **Sandbox** to match the credentials. **Email** can stay empty.
3. Click **Test Connection**. The button asks PayPal every time, so a saved but wrong credential still reports the failure.
4. Once the test succeeds, click **Save Changes**.

### Set the subscription options

1. Every order with renewable lines offers the subscribe choice on its own; no setting turns it on. **Enable Subscription** changes nothing in the current version.
2. Open the **Subscription Settings** tab. Tick **Force Subscription** only when you want every PayPal payment to become an agreement.
3. Tick **Update Subscription Fee** to carry later price changes to running agreements.
4. Click **Save Changes**.

### What the client goes through

1. The client selects this method at checkout, on an invoice or when adding funds.
2. If the order has renewable lines, the client answers the pay once or subscribe question.
3. The client confirms the forward, approves the payment at PayPal and returns to your site.
4. The return collects the money, closes the invoice and activates the service. A client who leaves PayPal without returning is not charged, and the invoice stays open.

### Refund a payment

1. Open the paid invoice: `{admin}/invoices/detail?id={invoice}`
2. When one PayPal payment closed several invoices, change the status to **Refunded**, choose **Refund via payment gateway** and confirm. Each invoice returns its own share.
3. A payment that closed a single invoice cannot be refunded through the module in the current version. The request fails and the status does not change. Refund it from your PayPal account, then mark the invoice **Refunded** with **Add as expense**.

## Things to Watch

> **The client ID and the secret are two different values**
> 
> Copying the client ID into both fields is a common mistake. PayPal then refuses every request with an authentication error, and clients meet it on the forwarding page. Take the secret from the same application, and take both from the environment you selected.

> **Force Subscription removes the choice**
> 
> With it on, a client paying with PayPal cannot make a one-time payment, and the pay once question disappears. Use it when every recurring line should renew at PayPal.

## Required Privileges

**Payment Module Settings** (`MODULES_PAYMENT_SETTINGS`) is required.

## Related Articles

- [Payment Modules](https://docs.wisecp.com/en/payment-modules)
- [Invoice Detail Overview](https://docs.wisecp.com/en/invoice-detail-overview)
- [Subscriptions](https://docs.wisecp.com/en/subscriptions)