@variablevic/mollie-payments-medusa
Version:
A Medusa plugin for Mollie payments.
171 lines (123 loc) • 6.65 kB
Markdown
# Mollie Payments for Medusa
A comprehensive payment provider plugin that enables [Mollie](https://www.mollie.com/gb/) payments on [Medusa](https://medusajs.com/) V2 projects.
## Table of Contents
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Configuration Options](#configuration-options)
- [Environment Variables](#environment-variables)
- [Usage](#usage)
- [Client-Side Integration](#client-side-integration)
- [Supported Payment Methods](#supported-payment-methods)
- [Extending the Plugin](#extending-the-plugin)
- [Local Development and Customization](#local-development-and-customization)
- [License](#license)
## Features
- **Multiple Payment Methods**: Supports a wide range of Mollie payment methods including:
- Mollie Hosted Checkout
- iDEAL
- Bancontact
- Credit Card
- PayPal
- Apple Pay
- Gift Card
- **Easily Extendable**: The modular architecture makes it easy to add support for additional Mollie payment methods.
- **Webhook Support**: Full support for Mollie webhooks for real-time payment status updates.
- **Automatic Capture**: Configurable automatic capture of payments.
> [!WARNING]
> _This plugin has not been tested on a live store. Please conduct thorough testing before using it in a production environment. I am not responsible for any missed or failed payments resulting from the use of this plugin. If you encounter any issues, please report them [here](https://github.com/VariableVic/mollie-payments-medusa/issues)._
## Prerequisites
- Medusa server v2.3.0 or later
- Node.js v20 or later
- A [Mollie](https://www.mollie.com/gb/) account and API key with payment methods enabled.
> [!NOTE]
> _You can get an API key from your Mollie dashboard: click Browse > Developers > API keys_
## Installation
```bash
yarn add @variablevic/mollie-payments-medusa
```
## Configuration
Add the provider to the `@medusajs/payment` module in your `medusa-config.ts` file:
```typescript
modules: [
// ... other modules
{
resolve: "@medusajs/payment",
options: {
providers: [
// ... other providers
{
resolve: "@variablevic/mollie-payments-medusa/providers/mollie",
id: "mollie",
options: {
apiKey: process.env.MOLLIE_API_KEY,
redirectUrl: process.env.MOLLIE_REDIRECT_URL,
medusaUrl: process.env.MEDUSA_URL,
},
},
],
},
}
]
```
## Configuration Options
| Option | Description | Default |
| ------------- | ----------------------------------------------------------------------------------------- | ----------------------- |
| `apiKey` | Your Mollie API key | Required |
| `redirectUrl` | The URL to redirect to after payment | Required |
| `medusaUrl` | The URL of your Medusa server | Required |
| `autoCapture` | Whether to automatically capture payments | `true` |
| `description` | The description that appears on the payment. | `Mollie payment created by Medusa` |
| `debug` | Whether to enable debug mode | `false` |
## Environment Variables
Create or update your `.env` file with the following variables:
```bash
MOLLIE_API_KEY=your_mollie_api_key
MOLLIE_REDIRECT_URL=https://your-store.com/checkout/payment
MEDUSA_URL=https://your-medusa-server.com
```
## Usage
Once installed and configured, the Mollie payment methods will be available in your Medusa admin. To enable them, log in to you Medusa Admin, browse to Settings > Regions, add or edit a region and select the desired Mollie providers from the dropdown.
Make sure that the selected payment methods are enabled in your Mollie origanization settings as well.
### Client-Side Integration
To integrate with your storefront, you'll need to implement the payment flow according to Mollie's and Medusa's documentation. Here's a basic example:
1. Create a payment session in your checkout flow
2. Redirect the customer to the Mollie payment page
3. Handle the webhook notifications to update the payment status
_Example integration using the [Medusa Next.js Starter](https://github.com/medusajs/nextjs-starter-medusa):_
https://github.com/user-attachments/assets/742ee261-5e41-4e33-9a72-faf1a424fc52
### Supported Payment Methods
The plugin currently supports the following Mollie payment methods:
| Payment Method | Provider ID |
| --------------- | ---------------------------------- |
| Hosted Checkout | `pp_mollie-hosted-checkout_mollie` |
| iDEAL | `pp_mollie-ideal_mollie` |
| Credit Card | `pp_mollie-card_mollie` |
| Bancontact | `pp_mollie-bancontact_mollie` |
| Gift Card | `pp_mollie-giftcard_mollie` |
| PayPal | `pp_mollie-paypal_mollie` |
| Apple Pay | `pp_mollie-apple-pay_mollie` |
## Extending the Plugin
To add support for additional Mollie payment methods, create a new service in `src/providers/mollie/services` that extends the `MollieBase` class:
```typescript
import { PaymentMethod } from "@mollie/api-client";
import MollieBase from "../core/mollie-base";
import { PaymentOptions, PaymentProviderKeys } from "../types";
class MollieNewMethodService extends MollieBase {
static identifier = "mollie-new-method";
get paymentCreateOptions(): PaymentOptions {
return {
method: PaymentMethod.newMethod,
};
}
}
export default MollieNewMethodService;
```
Make sure to replace `new method` with the actual Mollie payment method ID.
Export your new service from `src/providers/mollie/services/index.ts`. Then add your new service to the list of services in `src/providers/mollie/index.ts`.
## Local development and customization
In case you want to customize and test the plugin locally, refer to the [Medusa Plugin docs](https://docs.medusajs.com/learn/fundamentals/plugins/create#3-publish-plugin-locally-for-development-and-testing).
## License
TBD