Mollie Payments

Mollie is the recommended payment provider for new Userdocks integrations. This guide is written for teams using Userdocks in their own product, so it focuses on the dashboard setup and the external runtime flows your app calls.

Stripe payment endpoints are still documented for existing projects, but they are deprecated for new setups.

This guide shows the simplest path to:

• connect Mollie to an app
• set up a card for a tenant
• create a one-time payment
• create a subscription
• open billing management from your app

Before You Start

• First follow Connect Your App in Userdocks.
• Connect Mollie in the Userdocks dashboard for the app you want to bill through. This is a dashboard action, not a public API integration step.
• Make sure the app has the business details required during Mollie onboarding: owner name, business name, contact email, contact phone, address, postal code, country code, VAT ID, and website.
• Make sure your runtime integration exposes the public webhook endpoint: POST /api/v1/webhooks/mollie.
• Use paymentMethod: "card". Card is the only supported checkout method in the current Mollie integration.
• Make sure you know the tenant you want to bill. If you use the public auth flow, you can load it from GET /api/v1/users/me and then fetch the tenant with GET /api/v1/tenants/:tenantUuid.

Connect Mollie In The Userdocks Dashboard

Connect Mollie before you build the runtime payment flows in your app:

1. Open the app in the Userdocks dashboard.
2. Check that your redirect URLs and public app settings are already configured.
3. Open the payment provider settings for the app.
4. Start the Mollie connection from the dashboard and complete the Mollie onboarding flow.
5. If Userdocks asks for missing business data, add it in the dashboard and finish the connection there.

Once the dashboard shows Mollie as connected, your app can start using the external checkout and billing endpoints documented below.

One Endpoint, Three Checkout Modes

Use POST /api/v1/apps/:appUuid/payment-providers/mollie/checkout-sessions for the main end-user billing flow.

• mode: "setup" stores a reusable card mandate.
• mode: "payment" creates a one-time payment.
• mode: "subscription" creates the first payment and bootstraps the recurring subscription after the webhook confirms success.

Every successful call returns nextAction.url. Redirect the user there to complete the Mollie checkout.

Set Up A Card

Use mode: "setup" when you want to save a card before charging it for a real product.

{
  "tenantUuid": "11111111-1111-1111-1111-111111111111",
  "paymentMethod": "card",
  "quantity": 1,
  "mode": "setup",
  "currency": "EUR",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/cancel"
}

What happens next:

• Userdocks creates a small refundable card-verification payment.
• The user completes the Mollie checkout at nextAction.url.
• The Mollie webhook stores the valid card mandate as a payment method.
• Userdocks refunds the setup charge after the setup payment succeeds.

Use this when you want a card on file before starting a subscription or before charging a returning tenant again.

Create A One-Time Payment

Use mode: "payment" when you want to charge once for a product price.

{
  "tenantUuid": "11111111-1111-1111-1111-111111111111",
  "productPriceUuid": "22222222-2222-2222-2222-222222222222",
  "taxRateUuid": "33333333-3333-3333-3333-333333333333",
  "paymentMethod": "card",
  "quantity": 1,
  "mode": "payment",
  "currency": "EUR",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/cancel"
}

You can also use priceId and taxRateId if that fits your integration better.

What happens next:

• Userdocks creates a Mollie payment and returns nextAction.url.
• The user completes checkout in Mollie.
• The webhook records the payment in Userdocks as a local one-time payment.
• If a valid mandate exists already, Userdocks can charge with a recurring sequence instead of forcing a fresh first-time setup.

Create A Subscription

Use mode: "subscription" with a recurring product price.

{
  "tenantUuid": "11111111-1111-1111-1111-111111111111",
  "productPriceUuid": "22222222-2222-2222-2222-222222222222",
  "taxRateUuid": "33333333-3333-3333-3333-333333333333",
  "paymentMethod": "card",
  "quantity": 1,
  "mode": "subscription",
  "currency": "EUR",
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/cancel"
}

How the subscription flow works:

• Userdocks creates the first Mollie payment.
• If the tenant already has a valid card mandate, the payment can start as a recurring charge.
• If the tenant does not have a valid mandate yet, the first successful checkout also establishes it.
• After the payment succeeds, the webhook creates the Mollie subscription and stores the local subscription record in Userdocks.

The important detail is timing: a subscription is not complete when the checkout session is created. It becomes active after the first payment succeeds and the Mollie webhook is processed.

Open Billing Management

Use POST /api/v1/apps/:appUuid/payment-providers/mollie/billing-portals to send the user back into your billing area with Mollie context.

For Mollie, this endpoint does not create a hosted provider portal. Instead, Userdocks returns your defaultReturnUrl with these query parameters added:

• userdocksBillingProvider=mollie
• userdocksBillingManaged=true
• appUuid=<appUuid>
• tenantUuid=<tenantUuid>

Use those values in your app to decide which billing screen to show.

Webhook Responsibilities

The webhook is part of the runtime payment flow, not the Mollie connection flow.

• Connect Mollie in the Userdocks dashboard first.
• Use the public webhook endpoint so Userdocks can finalize successful setup, payment, and subscription events.
• Treat the checkout session as the user-facing step and the webhook as the system step that persists the final billing result.

Server-To-Server Alternative

If you want to create a payment or subscription from your backend without a logged-in bearer user, use the API-key billing endpoint instead:

POST /api/v1/apps/:appUuid/tenants/:tenantUuid/payment-providers/:paymentProvider/invoices

For Mollie on that endpoint:

• use paymentProvider = mollie
• use type = payment or subscription
• expect a Mollie payment object in the response
• expect the subscription to become active after the webhook confirms the first payment