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

# Stripe

> Send overdue Stripe invoices to paywise — for one account, several brands or a whole Stripe organisation

# paywise for Stripe

<div style={{width: '64px', height: '64px', background: '#ffffff', borderRadius: '10px', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '10px', boxSizing: 'border-box'}}>
  <img src="https://mintcdn.com/paywisegmbh/wAdTkukMeudh23V7/images/integrations/stripe-icon.png?fit=max&auto=format&n=wAdTkukMeudh23V7&q=85&s=12728de25e438b6d0215d7829ace3a3a" alt="Stripe" style={{width: '100%', height: '100%', objectFit: 'contain', display: 'block'}} noZoom width="128" height="128" data-path="images/integrations/stripe-icon.png" />
</div>

The Stripe integration hands overdue invoices from Stripe Billing straight to paywise
for collection. Typical case: a subscription or invoice payment where the card on
file can no longer be charged and Stripe leaves the invoice open.

<Note>
  paywise reads from Stripe and never writes back. Nothing in your Stripe account is
  changed, cancelled or marked as paid.
</Note>

## Before you start

* A Stripe account in which you may create API keys.
* A paywise account.
* At least one **open invoice** in Stripe.

<Note>
  If a DATEV import is active for the same company, deactivate it under **DATEV
  Einstellungen → Gefahrenzone → Integration deaktivieren** before using the Stripe
  invoice picker. This makes it clear which source should supply new claims.
</Note>

### Permissions paywise needs

paywise reads only what is needed for debt collection:

| Permission           | Access | Why paywise needs it                               |
| -------------------- | ------ | -------------------------------------------------- |
| `Connect › Accounts` | Read   | Recognises which Stripe account the key belongs to |
| `Core › Customers`   | Read   | The debtors' names and addresses                   |
| `Billing › Invoices` | Read   | The open invoices you submit                       |

These three rights are enough — **paywise writes nothing to your Stripe account**. A
standard key (`sk_…`) of your account or an organisation key (`sk_org_…`) already
carries them; nothing needs configuring there.

## Creating the Stripe key

Inside paywise this guide is available at any time via **„Was ist das?“** on the
Stripe page.

<Steps>
  <Step title="Sign in to Stripe">
    Sign in at [dashboard.stripe.com](https://dashboard.stripe.com/).
  </Step>

  <Step title="Open API keys">
    In the menu, go to **Entwickler → API-Schlüssel** (*Developers → API keys*).
  </Step>

  <Step title="Create a restricted key">
    We recommend a **restricted key** that grants access only to the resources
    needed. In the **Eingeschränkte Schlüssel** section, choose **Eingeschränkten
    Schlüssel erstellen** (*create restricted key*).
  </Step>

  <Step title="Grant the three read permissions">
    In the key configuration, grant the three read permissions from the table above:
    **Connect › Accounts**, **Core › Customers** and **Billing › Invoices**.
  </Step>

  <Step title="Copy the key">
    Copy the newly created key and paste it into paywise.
  </Step>
</Steps>

## 1. Connect Stripe

<Steps>
  <Step title="Open the connection page">
    Go to [app.paywise.de/connect/stripe/](https://app.paywise.de/connect/stripe/).
  </Step>

  <Step title="Paste the key">
    In the **Stripe-Schlüssel verbinden** section, paste any Stripe API key. paywise
    automatically detects whether it is an organisation key (`sk_org_…`), the key of
    your **main account**, or the key of an **additional Stripe account (brand)**.
  </Step>

  <Step title="Accept the terms and connect">
    Tick **Ich akzeptiere die Nutzungsbedingungen** and choose **Schlüssel
    verbinden** (*connect key*).
  </Step>

  <Step title="For additional accounts: give it a display name">
    If the key belongs to an additional Stripe account, paywise asks for an
    **Anzeigename der Marke** (brand display name). Confirm with **Als Marke
    hinzufügen** (*add as brand*).
  </Step>
</Steps>

### Multiple Stripe accounts

The **Stripe-Konten** section manages all connected accounts. Each shows its **type**
and **status**:

| Type                                             | Meaning                                                  |
| ------------------------------------------------ | -------------------------------------------------------- |
| **Eigener Schlüssel** (own key)                  | A dedicated key is stored for this account               |
| **Organisations-Kontext** (organisation context) | The account uses the organisation key and has no own key |

Use **Konto hinzufügen** to connect another account, **Ersetzen** to replace a key
(the new one takes effect immediately; claims already imported are unaffected), and
**Konto entfernen** to stop importing from that account.

## 2. Submit invoices for collection

<Steps>
  <Step title="Open the invoice picker">
    On the Stripe page in paywise, choose **Rechnungen einreichen**.
  </Step>

  <Step title="Pick the invoices">
    The invoice picker shows invoices with the Stripe status `open` — with invoice number,
    customer, invoice date, due date and open amount.

    The **due date comes straight from Stripe**; paywise calculates nothing here.
  </Step>

  <Step title="Check the debtor data">
    Name and address come from the Stripe customer, and the invoice PDF is attached
    from Stripe. Carefully check the due date, currency, open amount and recipient
    data, and complete anything missing.
  </Step>

  <Step title="Record your payment reminder">
    Stripe has no reminders in the sense of German dunning practice. Enter how and
    when you asked the debtor to pay — in writing or verbally, the date, and any
    payment deadline you set.

    This matters legally: for consumers a reminder is normally required before
    default interest and collection costs can be claimed.
  </Step>

  <Step title="Send the order">
    Confirm how collection should start, answer the legal questions, accept the terms
    and choose **Auftrag absenden**.
  </Step>
</Steps>

### What the invoice picker shows

The standard Stripe invoice picker filters on the status `open`. Before displaying
an invoice, it does **not additionally check** whether it is already due,
denominated in euros, or has complete recipient and PDF data. `open` therefore does
not automatically mean that the claim should already be submitted.

You can complete missing address and contact details in the paywise draft after
adding the invoice. A customer name must already be stored in Stripe. If a usable
invoice PDF is missing, paywise cannot add the invoice either; provide the PDF in
Stripe and try again.

<Warning>
  Review and complete the claim in paywise before sending the order. In particular,
  do not submit a claim that is not yet due or has already been paid.
</Warning>

## Mahnservice: importing invoices continuously

This integration feeds more than the one-off collection handover — it can also supply
the **paywise Mahnservice**, the pre-collection dunning service. paywise then fetches
your open invoices regularly and sends payment reminders on your behalf, before a case
becomes a collection matter. You set the Mahnservice up at
[app.paywise.de/mahnservice/](https://app.paywise.de/mahnservice/).

### Prerequisites

All of the following must be in place before the recurring sync starts:

* An **active Stripe connection**.
* A **Mahnservice subscription** and the **accepted Mahnservice terms**.
* A decided **import scope** — you determine once which invoices should be taken over.
* The **opt-in per Stripe account**: you decide for each connected account or brand
  whether its invoices flow into the Mahnservice.

### Which invoices the Mahnservice imports

The Mahnservice applies a stricter automatic check. A Stripe invoice is imported
only if **all** of the following hold:

* Its status is `open`.
* Its due date is in the past and its remaining balance is greater than zero.
* Its currency is euro.
* A customer with a name and postal address is attached.
* An invoice PDF exists.
* The invoice has not already been handed to collection or the Mahnservice.

### What paywise checks before every reminder

<Steps>
  <Step title="Regular sync">
    paywise fetches your open invoices from Stripe at fixed intervals. Newly opened
    invoices are picked up automatically.
  </Step>

  <Step title="Status check immediately before sending">
    Right before a reminder goes out, paywise queries the current invoice status in
    Stripe once more. If the invoice has been paid or cancelled in the meantime, no
    reminder is sent.
  </Step>

  <Step title="When in doubt, nothing is sent">
    If the status cannot be established beyond doubt — because Stripe is temporarily
    unreachable, for instance — paywise holds the reminder back. That is deliberate: a
    reminder sent late is better than one sent to somebody who has already paid.
  </Step>
</Steps>

Payments paywise finds in Stripe during a sync end the dunning process
automatically.

## 3. Disconnect

On the Stripe page, choose **Konto entfernen** for the account in question — or
**Verbindung löschen** for the whole connection, confirming with **Löschen**.

The stored key is removed and the import from that account stops. Claims already
imported remain. You can store the key again at any time. If the account supplies
the Mahnservice, no further reminders are sent while paywise cannot verify invoice
status through an active connection.

## Troubleshooting

<AccordionGroup>
  <Accordion title="„Der Schlüssel wurde von Stripe abgelehnt“">
    Check that you copied the complete key and that it belongs to the right Stripe
    account and environment.
  </Accordion>

  <Accordion title="„Diesem Schlüssel fehlen Berechtigungen, die paywise benötigt“">
    paywise names the missing rights. Add them in Stripe under **Eingeschränkten
    Schlüssel bearbeiten** and paste the key again.
  </Accordion>

  <Accordion title="„Ihr API-Schlüssel ist nicht mehr gültig“">
    The key was revoked or rotated in Stripe. Store a current key via **Ersetzen**.
  </Accordion>

  <Accordion title="An overdue invoice is missing from the list">
    Work through the list under *Invoices that cannot be submitted*. Most often the
    customer has no postal address, or the invoice is not denominated in euros.
  </Accordion>

  <Accordion title="An account shows „Kein Schlüssel“ (no key)">
    No key is stored for that account and it does not use an organisation key. Add a
    key via **Ersetzen**.
  </Accordion>
</AccordionGroup>

## Questions

Write to [info@paywise.de](mailto:info@paywise.de).