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.

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

Status, Commission Rate (%), Converting Currency, Accepted Amount Range and the country lists work the same way in every gateway; see 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

Required Privileges

Payment Module Settings (MODULES_PAYMENT_SETTINGS) is required.

Related Articles

• Payment Modules
• Invoice Detail Overview
• Subscriptions