Mollie

You are integrating Mollie as a Payment Service Provider into a [Django / Next.js / etc.] application.

## Key Concept: Mollie is a PSP, not a Merchant of Record
Mollie is a regulated European Payment Service Provider (not an MoR). That means:
- YOU are legally the seller — you collect and remit VAT/GST/sales tax yourself (use OSS/MOSS for EU digital goods).
- YOU issue invoices to your customers (Mollie has invoicing helpers but you own the liability).
- YOU must be a company registered in the EEA, UK, or Switzerland with a business IBAN — US/CA/AU/etc. merchants cannot sign up.
- Your buyers, however, can be anywhere in the world.

## Setup
1. Sign up at mollie.com, complete business verification, and obtain:
   - `MOLLIE_API_KEY` — profile-scoped. Starts with `test_` (sandbox) or `live_` (production). Pulled from the dashboard under Developers > API keys.
   - `MOLLIE_PROFILE_ID` — the profile the key belongs to.
2. Store in environment variables — NEVER commit keys or hardcode.
3. Install the official SDK: `pip install mollie-api-python` (or `npm i @mollie/api-client`, `composer require mollie/mollie-api-php`, etc.).

## Recommended Integration: Hosted Checkout Redirect
The simplest and most robust flow. Your server creates a payment, redirects the user to Mollie's hosted page, then confirms via webhook.

```python
from mollie.api.client import Client

mollie_client = Client()
mollie_client.set_api_key(os.environ['MOLLIE_API_KEY'])

payment = mollie_client.payments.create({
    'amount': {'currency': 'EUR', 'value': '29.00'},   # always a string, two decimals
    'description': 'Pro Plan - April 2026',
    'redirectUrl': f'https://yourdomain.com/orders/{order.id}/return',
    'webhookUrl':  'https://yourdomain.com/webhooks/mollie',
    'metadata':    {'order_id': str(order.id), 'user_id': str(user.id)},
    # Optional: restrict to one method
    # 'method': 'ideal',
})

# Save payment['id'] on your Order; then redirect:
return redirect(payment.checkout_url)
```

When the buyer returns to `redirectUrl`, do NOT trust the return as payment confirmation — the user may have closed the tab, refreshed, or been redirected before payment completed. Always confirm via the webhook.

## Webhook Handling (CRITICAL — Mollie-specific gotcha)
Mollie's webhook POSTs **only the payment ID** — no status, no amount, no signature. Your server MUST re-fetch the payment over HTTPS using your API key to get the real status. This is deliberate: it prevents anyone from faking webhooks to mark orders paid.

```python
# Django example
@csrf_exempt
@require_POST
def mollie_webhook(request):
    payment_id = request.POST.get('id')
    if not payment_id:
        return HttpResponseBadRequest()

    # Fetch the authoritative status from Mollie
    payment = mollie_client.payments.get(payment_id)

    order = Order.objects.get(mollie_payment_id=payment_id)

    if payment.is_paid():
        # Idempotent — safe to call multiple times
        fulfill_order(order)
    elif payment.is_failed() or payment.is_canceled() or payment.is_expired():
        mark_order_failed(order)
    # 'open' and 'pending' -> nothing yet, Mollie will ping again

    return HttpResponse(status=200)   # Always 200 or Mollie retries
```

### Webhook rules
- Webhook URL must be publicly reachable over HTTPS. Localhost requires a tunnel (ngrok, cloudflared) — Mollie does NOT retry indefinitely.
- Mollie retries failed webhook deliveries, so your handler MUST be idempotent. Check payment status before fulfilling; never assume this is the first call.
- Do not rely on the buyer hitting `redirectUrl` — always trust the webhook + API fetch as the source of truth.
- Return 200 fast (under 15s). Offload heavy work to a queue.

## Subscriptions / Recurring
Mollie subscriptions require a "first payment" to capture the mandate. Sequence:

```python
# 1. Create a Customer
customer = mollie_client.customers.create({
    'name': user.name,
    'email': user.email,
})

# 2. First payment with sequenceType='first' — customer completes checkout
first_payment = mollie_client.payments.create({
    'amount': {'currency': 'EUR', 'value': '29.00'},
    'customerId': customer.id,
    'sequenceType': 'first',
    'description': 'First payment to authorise monthly subscription',
    'redirectUrl': 'https://yourdomain.com/subscribe/confirm',
    'webhookUrl':  'https://yourdomain.com/webhooks/mollie',
})

# 3. After first payment is paid, create the subscription
subscription = mollie_client.customer_subscriptions.on(customer).create({
    'amount':      {'currency': 'EUR', 'value': '29.00'},
    'interval':    '1 month',
    'description': 'Pro Plan - monthly',
    'webhookUrl':  'https://yourdomain.com/webhooks/mollie',
})
```

Recurring payment methods are limited to SEPA Direct Debit and credit card. iDEAL cannot recur directly — Mollie converts the iDEAL mandate into a SEPA Direct Debit for subsequent charges.

## Payment Methods — Mollie's Strength
Mollie's biggest selling point is native European method support. With one integration you accept:
- **Cards**: Visa, Mastercard, Amex, Cartes Bancaires
- **Bank-based**: iDEAL (NL), Bancontact (BE), SEPA DD, SEPA Bank Transfer, Bacs (UK), Pay by Bank (open banking)
- **Wallets**: Apple Pay, Google Pay, PayPal
- **BNPL**: Klarna (Pay Later, Slice It, Pay Now)
- **Local**: BLIK + Przelewy24 (PL), EPS (AT), TWINT (CH), Trustly (Nordics), Wero

You can let Mollie display all enabled methods (default), or force a specific one via `method: 'ideal'`.

## Security Best Practices
- Never handle raw card data — use Mollie Components or the hosted checkout so card fields render inside Mollie's PCI scope.
- Store `payment.id` and `subscription.id` alongside your internal records, never card details.
- Enforce HTTPS for your webhook endpoint.
- Use idempotent webhook handlers. Mollie retries.
- Re-fetch payment status from the API inside the webhook — never trust the POST body for authoritative status.
- Keep API keys in env vars; rotate if leaked.
- Use `test_` keys for all development; test webhook flow with a tunnel.

## Testing
- Use the test mode API key (`test_...`) — test mode has a separate dashboard and doesn't touch real money.
- Force specific payment statuses with the test-mode Webhook Simulator (Dashboard > Developers > Simulator).
- Test the full subscription lifecycle: first payment → webhook → subscription create → recurring charge → failed renewal → cancellation.
- Test with a tunnel (ngrok) so Mollie can reach your local webhook.

## Common Gotchas
- **Webhook ID-only payload**: ALWAYS fetch via API to read status. Forgetting this is the #1 Mollie bug.
- **Amounts are strings** in Mollie JSON (`'29.00'` not `29.00`). They must be a string with exactly two decimals for most currencies.
- **Refunds don't return the transaction fee** — bake that into your refund cost model.
- **Chargeback fee is non-refundable** (€19 for cards, €10 for SEPA DD) even if you win the dispute.
- **Split payments (Connect) are EUR/GBP only** — no multicurrency splits.
- **iDEAL can't directly recur** — it converts to SEPA DD for subsequent charges, so the mandate UX differs from cards.
- **Test vs live** — each mode has a separate API key and data. You cannot migrate test payments to live.
- **If your account is placed under review, payouts freeze** — keep KYC docs current and diversify providers early.