Most of the flow is the same as Stripe and OPP: payway calls the same functions (`payment_url`, `process_payments`, `refund`, `process_cancel`, `onboard`) and gets the same response shapes. The differences are below.
Mollie's webhook has no signature or hash, and its body contains only the payment id. Instead of checking a signature like Stripe does, the module re-fetches the payment from Mollie's API with the merchant's token and compares it with the record it created: amount, currency, profile, and the `company_id`, `shop_id`, `order_id` and `payment_id` in the payment's metadata. If anything doesn't match, nothing is updated and a Telegram alert is sent.
The order ids travel in the webhook URL's query string (`/v1/webhooks/mollie/payments?company_id=…&shop_id=…&order_id=…`), because payway only forwards a JSON body and Mollie sends a form body.
`onboard` only registers the company, without a merchant id. The merchant connects their own Mollie account through the "Connect with Mollie" link returned by the new `session` endpoint. After they approve, Mollie sends them back to `process_oauth` through payway's `/v1/webhooks/mollie/oauth`.
`process_oauth` then stores the tokens and sets `provider_id` and `provider_identifier` (the Mollie organization id) on the company. If the company is already live on another provider, it leaves those alone and returns `switch_required: true`.
The Connect with Mollie button itself only shows once the company's `provider_id` already points to Mollie, see "Putting a company on Mollie" below.
Every call uses the merchant's own OAuth token, not a platform key, and every payment is created on the merchant's own Mollie profile. Both tokens are stored encrypted in the new `companies.metadata` column (payments DB), since Mollie requires the refresh token to be stored encrypted. The access token is refreshed automatically when it expires.
OAuth tokens have no test or live mode of their own, so the mode is set by `testmode` in the config. Without it, payments are live. Use `true` on test and stage, `false` on production.
Returns the merchant's Mollie onboarding status and capabilities, plus `reauthorization_required: true` when the merchant connected before a permission the module now needs and has to reconnect.
"orderlemon_config": {
"use_composer": true,
"use_dbal": true,
"init_classes": true,
"environment": "prod",
"master_token": "...",
"locales_storage": "/path/to/locales/",
"db": { "host": "...", "port": 3306, "name": "...", "user": "...", "password": "..." },
"db_payments": { "host": "...", "port": 3306, "name": "...", "user": "...", "password": "..." },
"servers": { "orderlemon_servers": { "payway_url": "https://payway.orderlemon.dev/v1" } },
"nizu": { "token": "..." },
"payments": {
"mollie": {
"testmode": true,
"provider_name": "mollie",
"oauth": {
"client_id": "app_xxx",
"client_secret": "xxx",
"encryption": {
"key_id": "v1",
"keys": { "v1": "<output of openssl rand -base64 32>" }
},
"onboarding_forward_url": "https://test.myshop.orderlemon.dev/settings/company/#payment"
}
}
}
}
- `client_id` and `client_secret` come from the OAuth app in the Mollie dashboard (OrderLemon account, Developers → Your apps). Its redirect URL must be exactly `<payway_url>/webhooks/mollie/oauth`, e.g. `https://payway.orderlemon.dev/v1/webhooks/mollie/oauth` on dev. An app has a single redirect URL, so every environment has its own app.
- The encryption key is generated by us and never sent to Mollie. Every environment that shares the same payments database must use the same key. Don't change it once merchants have connected: their stored tokens can no longer be decrypted and they have to connect again.
- `environment`: the environment name, `prod` only on production. The top-level `env` key of the config must say the same: the module's `prod` checks read `env`, and on anything else it logs request data.
- `provider_name`: must equal `providers.name` and the name of the node in payway's `universe`.
- `onboarding_forward_url`: the MyShop payment settings page the merchant is sent back to after connecting. Different per environment (test: `https://test.myshop.orderlemon.dev/settings/company/#payment`).
- `master_token`: the same master token the other microservices use. Without it the `payments.completed` and `payments.refunded` events are not created.
- `locales_storage`: directory with `<lang>_custom.json` files containing the `txt_order` key. `refund` uses it for the refund description and fails without it.
Every endpoint must be listed in `allowed_functions` in the Mollie microservice's config, or the call returns 405:
"allowed_functions": {
"GET": ["payment_url", "embed", "expire_payment", "payouts_list", "account_info", "session_token", "session"],
"POST": ["onboard", "process_payments", "refund", "process_cancel", "process_oauth"],
"PUT": [],
"DELETE": []
}
New compared to the other providers: `session`, `session_token`, `process_oauth` and `account_info`.
payway's own config also needs `session` under `GET`, because the panel calls payway, which forwards it to this microservice. Without it the Connect with Mollie button opens a blank tab.
- The Mollie microservice needs a `telegram` node (with a `payments` chat) for the support alerts, and an `events` node.
- payway needs a node pointing to the Mollie microservice of the same environment. Its `name` must equal `providers.name`. Without it payway's `embed` gets nothing back and MyShop shows an empty Payment details screen.
"universe": [
{ "name": "mollie", "ip": "...", "port": ..., "ssl": ..., "token": "<ms_server_token of the Mollie microservice>" }
]payway picks the module from `companies.provider_id`, so the Connect with Mollie button only shows once `provider_id` already points to Mollie. Set it by hand, with `provider_identifier` empty. Connecting then fills `provider_identifier` with the organization id:
UPDATE `companies` SET `provider_id` = <mollie provider id>, `provider_identifier` = NULL WHERE `id` = <company_id>;
The `providers` row for Mollie has `countries = []`: a company is never put on Mollie by its country.
The methods (e.g. iDEAL, Bancontact) must be enabled in the merchant's own Mollie account: Settings → Online payments. `payment_methods.provider_code_name` is sent to Mollie as is (`ideal`, `bancontact`).
The "Connect with Mollie" link asks the merchant for these permissions:
| Scope | Used for |
| organizations.read | Reading the merchant's organization id when they connect, and `account_info` |
| profiles.read | Reading the profile the payments are created on |
| payments.read | Re-fetching a payment in the webhook (`process_payments`), and before cancelling it |
| payments.write | Creating payments (`payment_url`) and cancelling them (`process_cancel`, `expire_payment`) |
| refunds.read | Not used yet; requested together with `refunds.write` |
| refunds.write | Creating refunds (`refund`) |
| settlements.read | Listing payouts (`payouts_list`) |
| onboarding.read | Onboarding status and capabilities (`account_info`) |
They are set in code (`mollieOAuthScopes()` in `v1/general/ms_functions.php`). A `scopes` list under `orderlemon_config.payments.mollie.oauth` replaces the default completely, so only set it if you need a different list.
Mollie doesn't add new permissions to an existing connection. When a scope is added, merchants who are already connected have to go through "Connect with Mollie" again.