# Stripe (Checkout) Module

https://docs.wisecp.com/en/stripe-checkout-module

Collect payments on the hosted Stripe payment page and let clients start a subscription from the same flow, without card details ever reaching your site.

## Reaching the Screen

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

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

One settings form with the provider credentials, the payment method codes and the shared gateway settings every module carries.

The client picks this method, moves to the hosted payment page, pays there, and Stripe notifies your install. The notification marks the invoice paid and activates the order.

The module also opens subscriptions from the checkout, and refunds a payment from the invoice screen. It does not store cards, does not show a card form on your site, and does not offer installments.

## Before You Configure It

- A Stripe account with its key pair. Test keys and live keys are two separate pairs.
- A webhook created in the Stripe dashboard for the `checkout.session.completed` event, plus the signing secret it gives you.
- The currencies you sell in enabled on the Stripe account.

## Fields

- **API Key**: The publishable key of the pair. Required.
- **Secret Key**: The secret key of the same pair. Every request to Stripe uses it. Required.
- **Signing Secret**: The secret Stripe gives you when you create the webhook. Required: with an empty value every incoming notification is refused.
- **Payment Methods for One Time Payment**: Method codes offered on the hosted page, separated by commas. Default `card`.
- **Payment Methods for Subscriptions**: The same list for subscription payments. Leave it empty to reuse the one-time list. `giropay` and `p24` cannot be used for subscriptions: they are dropped from the list even when you write them here, so the client never sees them on the Stripe page.
- **Disable Subscription Feature**: Tick to remove the subscribe option. Every payment then becomes one-time. Off by default.
- **Payment Method Info**: The method codes you can copy into the two fields above. Information only.
- **Webhook Event Types**: The event this module expects from Stripe. Information only.
- **Test Mode**: This tick has no effect inside the product: nothing reads it. Which environment answers is decided only by the key pair you enter. On by default.

**Status**, **Commission Rate (%)**, **Converting Currency**, **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: copy them with the icon at the end of the field.

## Tasks

### Take the keys from Stripe

1. Sign in to the Stripe dashboard. For test keys switch to a sandbox from the account picker; for real payments stay in live mode.
2. Open the **Developers** menu, click **Workbench** and go to **API keys**.
3. Copy the publishable key and the secret key from **Standard keys**. Sandbox keys start with `pk_test_` and `sk_test_`, live keys with `pk_live_` and `sk_live_`.
4. In live mode a secret key you created is shown once. When it is lost, roll it from the same page and copy the new value.

### Enter the credentials

1. Open the module card and tick **Status**. The other fields stay locked until you do.
2. Fill in **API Key** and **Secret Key**. Setting **Test Mode** to match the pair is optional: it is a label and changes nothing.
3. Click **Save Changes**. The gateway is ready for the notification step below.

### Register the notification address at Stripe

1. Copy **Callback URL** from the module card.
2. In **Workbench** open the **Webhooks** tab and start a new event destination.
3. Paste the address into **Endpoint URL**, keep the scope on events from your own account and select the `checkout.session.completed` event. The module reads no other event.
4. Open the endpoint, reveal its signing secret and copy it into **Signing Secret**. Click **Save Changes**.
5. Payments now close their invoice on their own. Without this step the money reaches Stripe and the invoice stays unpaid.

### 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 first.
3. The client moves to the hosted Stripe page and pays with one of the methods you allowed.
4. Stripe notifies your install, the invoice becomes paid and the service is activated.

### Refund a payment

1. Open the paid invoice: `{admin}/invoices/detail?id={invoice}`
2. Change the invoice status to **Refunded** and keep the refund through the module ticked.
3. Each invoice is refunded for its own share of the charge, even when one payment closed several invoices. A failed refund is not retried on its own.

### Follow a subscription

1. Open **Billing → Subscriptions** to see agreements opened through this gateway.
2. Cancelling an agreement here also cancels it at Stripe, and removing a single line drops that line from the agreement.

## Things to Watch

> **An empty signing secret blocks every payment result**
> 
> Without it the module refuses the notification instead of trusting an unsigned one. The client pays, the invoice stays unpaid and no service is activated. Fill the field before you go live.

> **Stripe can show its own currency**
> 
> With adaptive pricing enabled on the Stripe account, the payment page offers the client a local currency based on their location, and the client covers the conversion fee. You still receive the invoice currency and the invoice total does not change. Switch it off in the Stripe dashboard if you want a single currency everywhere.

> **Test and live keys belong to separate accounts**
> 
> Ticking Test Mode does not change the keys. A live key pair with a test webhook secret, or the reverse, ends in refused notifications. Change the pair, the webhook and its signing secret together.

## 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)