POST /api/v1/apps/:appUuid/payment-providers/mollie/checkout-sessions

Creates a new checkout sessions resource.

This endpoint documentation is generated from the current Fastify route implementation and should be treated as the implementation-level contract for this version of the API.

Source route file: src/api/routes/external/private/bearer/apps/payment-providers/mollie/checkout-sessions/post.ts

Request Method

POST

Base URL

https://api.userdocks.local:5000

Endpoint

/api/v1/apps/:appUuid/payment-providers/mollie/checkout-sessions

Path Variables

Variable	Type	Required	Description
appUuid	string	true	Path variable from route pattern.

Query Parameters

No query parameters.

HTTP Headers

Variable	Type	Required	Description
Authorization	string	true	Bearer token in the form Bearer <jwt>.
Content-Type	string	true	Use application/json for JSON request bodies.

Request Body

Schema reference: createCheckoutSessionSchema

{
  "tenantUuid": "11111111-1111-1111-1111-111111111111",
  "productUuid": "22222222-2222-2222-2222-222222222222",
  "unitAmount": 1300,
  "currency": "EUR",
  "taxRateUuid": "33333333-3333-3333-3333-333333333333",
  "paymentMethod": "card",
  "quantity": 1,
  "mode": "subscription",
  "recurringInterval": "month",
  "recurringIntervalCount": 1,
  "billingAddressCollection": false,
  "shippingAddressCollection": false,
  "successUrl": "https://app.example.com/billing/success",
  "cancelUrl": "https://app.example.com/billing/cancel",
  "termsOfServiceUrl": "https://app.example.com/terms",
  "collectTermsOfServiceConsent": true,
  "isTaxIdCollectionEnabled": false,
  "isTaxIdCollectionRequired": false
}

Mode Notes

• setup: creates a small refundable card-verification payment and stores the resulting mandate after the webhook succeeds.
• payment: creates a one-time payment.
• subscription: creates the first payment and bootstraps the recurring subscription after the Mollie webhook succeeds.
• paymentMethod currently supports card only.
• Inline amounts are positive minor-unit integers (1300 is EUR 13.00). Currencies are normalized to uppercase, and subscription cadence is explicit.
• Deprecated productPriceUuid and provider priceId remain supported.

Successful Response

Success status code(s): 200.

{
  "kind": "checkoutSessions",
  "totalItems": 1,
  "itemsLength": 1,
  "items": [
    {
      "createdCheckoutSession": {
        "id": 1,
        "uuid": "csrow_11111111-1111-1111-1111-111111111111",
        "appUuid": "app_11111111-1111-1111-1111-111111111111",
        "paymentProviderUuid": "pp_11111111-1111-1111-1111-111111111111",
        "sessionId": "tr_12345",
        "nextActionUrl": "https://www.mollie.com/checkout/select-method/abc123",
        "userUuid": "user_11111111-1111-1111-1111-111111111111",
        "tenantUuid": "tenant_11111111-1111-1111-1111-111111111111",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z",
        "deletedAt": null
      },
      "nextAction": {
        "url": "https://www.mollie.com/checkout/select-method/abc123"
      }
    }
  ]
}

Error Responses

HTTP Status	Example Error
401	{"errors":[{"validation":"error","code":"[E4010]","message":"Unauthorized Token"}]}
403	{"errors":[{"validation":"error","code":"[E4030]","message":"App Is Disabled"}]}
404	{"errors":[{"validation":"error","code":"[E4040]","message":"Not Found"}]}
400	{"errors":[{"validation":"error","code":"[E4000]","message":"Bad Request / validation error"}]}
500	{"errors":[{"validation":"error","code":"[E0000]","message":"Internal Server Error"}]}

Example

const url = `https://api.userdocks.local:5000/api/v1/apps/appUuid-value/payment-providers/mollie/checkout-sessions`;

const response = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <jwt>',
    'Content-Type': 'application/json',
  },
  body: '{"tenantUuid":"11111111-1111-1111-1111-111111111111","productUuid":"22222222-2222-2222-2222-222222222222","unitAmount":1300,"currency":"EUR","taxRateUuid":"33333333-3333-3333-3333-333333333333","paymentMethod":"card","quantity":1,"mode":"subscription","recurringInterval":"month","recurringIntervalCount":1,"successUrl":"https://app.example.com/billing/success","cancelUrl":"https://app.example.com/billing/cancel"}',
});
const data = await response.json();
console.log(response.status, data);

Named discounts

Supply the root-level discount with { "name": "Partner deal", "amount": 1000, "duration": "once" } or duration "forever". Amounts use the price currency's minor units and reduce the product line once, regardless of quantity. The original price and named reduction remain visible on the invoice. Discounts must be smaller than the product line subtotal; setup sessions and charges below the provider minimum are rejected.

See Named billing discounts for renewal behavior, per-line invoice examples, tax handling, and midterm upgrade calculations.