{"id":49457149,"url":"https://github.com/monei/medusa-payment-monei","last_synced_at":"2026-04-30T07:04:50.374Z","repository":{"id":350772590,"uuid":"1208208632","full_name":"MONEI/medusa-payment-monei","owner":"MONEI","description":"MONEI payment provider for Medusa v2 — Cards, Bizum, PayPal, Google Pay, Apple Pay and more","archived":false,"fork":false,"pushed_at":"2026-04-12T01:46:03.000Z","size":87,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T03:08:39.839Z","etag":null,"topics":["ecommerce","medusa","medusajs","monei","monei-api","monei-payments","payment-provider","payments","typescript"],"latest_commit_sha":null,"homepage":"https://docs.monei.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MONEI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T00:58:40.000Z","updated_at":"2026-04-12T01:46:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MONEI/medusa-payment-monei","commit_stats":null,"previous_names":["monei/medusa-payment-monei"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/MONEI/medusa-payment-monei","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MONEI%2Fmedusa-payment-monei","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MONEI%2Fmedusa-payment-monei/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MONEI%2Fmedusa-payment-monei/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MONEI%2Fmedusa-payment-monei/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MONEI","download_url":"https://codeload.github.com/MONEI/medusa-payment-monei/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MONEI%2Fmedusa-payment-monei/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32457121,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecommerce","medusa","medusajs","monei","monei-api","monei-payments","payment-provider","payments","typescript"],"created_at":"2026-04-30T07:04:49.460Z","updated_at":"2026-04-30T07:04:50.364Z","avatar_url":"https://github.com/MONEI.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# medusa-payment-monei\n\nMONEI payment provider for **Medusa v2**. Accept Cards, Bizum, PayPal, Google Pay, Apple Pay, BNPL, MB Way, SEPA Direct Debit and more through [MONEI](https://monei.com) — a licensed European Payment Institution (Banco de España #6911).\n\n## Features\n\n- **Full payment lifecycle**: initiate → authorize → capture → refund → cancel\n- **Auth + Capture flow**: pre-authorize and capture when ready (default), or auto-capture on authorization\n- **Webhook support**: real-time payment status updates with HMAC signature verification\n- **Multi-payment methods**: all MONEI payment methods available automatically (Cards, Bizum, PayPal, Google Pay, Apple Pay, etc.)\n- **Hosted Payment Page**: redirect customers to MONEI's secure PCI-compliant payment page\n- **monei.js integration**: storefront can use MONEI JS SDK for embedded payment components\n- **Partial capture \u0026 refund**: supported via MONEI API\n\n## Prerequisites\n\n- Medusa v2 application\n- MONEI account ([sign up](https://dashboard.monei.com/signup))\n- API Key from MONEI Dashboard → Settings → API Access\n\n## Installation\n\n```bash\nnpm install medusa-payment-monei\n# or\nyarn add medusa-payment-monei\n```\n\n## Configuration\n\n### 1. Add to `medusa-config.ts`\n\n```ts\nimport { defineConfig } from \"@medusajs/framework/utils\"\n\nexport default defineConfig({\n  // ...\n  modules: [\n    {\n      resolve: \"@medusajs/medusa/payment\",\n      options: {\n        providers: [\n          {\n            resolve: \"medusa-payment-monei\",\n            id: \"monei\",\n            options: {\n              apiKey: process.env.MONEI_API_KEY,\n              // Optional: auto-capture payments (default: false)\n              // When false, payments use AUTH + manual capture flow\n              // When true, payments use SALE flow (captured immediately)\n              capture: false,\n            },\n          },\n        ],\n      },\n    },\n  ],\n})\n```\n\n### 2. Set environment variables\n\n```bash\n# .env\nMONEI_API_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx\n```\n\n### 3. Enable in Medusa Admin\n\nGo to **Settings → Regions** and enable the MONEI payment provider for your region(s).\n\nThe provider registers as `pp_monei_monei` (format: `pp_{identifier}_{id}`).\n\n## Payment Flows\n\n### Default: Auth + Capture (recommended)\n\n1. **Customer selects MONEI** → `initiatePayment` creates a MONEI payment with `transactionType: AUTH`\n2. **Customer completes payment** → redirected to MONEI hosted page or uses monei.js component, completes 3DS if needed\n3. **MONEI webhook** → `getWebhookActionAndData` receives `AUTHORIZED` status, completes the cart\n4. **Admin captures** → `capturePayment` calls MONEI capture API\n\n\u003e ⏰ **Capture window**: Card payments must be captured within **7 days**, Bizum within **30 days**.\n\n### Auto-capture (set `capture: true`)\n\n1. Customer selects MONEI → payment created with `transactionType: SALE`\n2. Customer completes payment → funds are captured immediately\n3. Webhook receives `SUCCEEDED` status → order is created\n\n## Webhooks\n\nMONEI sends asynchronous webhook notifications to your Medusa server. Medusa provides a built-in webhook endpoint:\n\n```\n{your_server_url}/hooks/payment/monei_monei\n```\n\n### Setting up webhooks\n\nConfigure the callback URL in MONEI Dashboard → Settings → Webhooks, or pass it dynamically via `callbackUrl` in the payment creation.\n\nThe plugin verifies the `MONEI-Signature` header using the MONEI Node SDK's built-in signature verification.\n\n## Storefront Integration\n\n### Option A: Hosted Payment Page (simplest)\n\nAfter `initiatePayment`, the session data contains `redirect_url`. Redirect the customer:\n\n```tsx\n// In your checkout component\nconst paymentSession = cart.payment_collection?.payment_sessions?.[0]\n\nif (paymentSession?.data?.redirect_url) {\n  window.location.href = paymentSession.data.redirect_url\n}\n```\n\n### Option B: monei.js Embedded Components\n\nUse the MONEI JS SDK to embed payment components directly in your checkout:\n\n```tsx\nimport monei from \"@monei-js/components\"\n\n// The payment ID from the session data serves as the client reference\nconst paymentId = paymentSession.data.id\n\n// Render card input\nconst cardInput = monei.CardInput({\n  paymentId,\n  onChange: (event) =\u003e {\n    // Handle validation\n  },\n})\ncardInput.render(\"#card-input\")\n\n// Confirm payment\nconst result = await monei.confirmPayment({\n  paymentId,\n  paymentToken: token, // from cardInput.getToken()\n})\n```\n\n## Payment Methods\n\nAll payment methods enabled in your MONEI Dashboard are automatically available:\n\n| Method | Description |\n|--------|-------------|\n| **Cards** | Visa, Mastercard, Amex via 3D Secure |\n| **Bizum** | Spain's #1 mobile payment (direct acquiring) |\n| **PayPal** | Global digital wallet |\n| **Google Pay** | Android/Chrome payments |\n| **Apple Pay** | iOS/Safari payments |\n| **Click to Pay** | Visa/Mastercard secure remote commerce |\n| **BNPL** | Buy now, pay later (Cofidis, Klarna) |\n| **MB Way** | Portuguese mobile payments |\n| **Multibanco** | Portuguese bank transfers |\n| **SEPA DD** | Euro direct debit |\n\n## API Reference\n\n### Provider Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `apiKey` | `string` | *required* | MONEI API Key |\n| `capture` | `boolean` | `false` | Auto-capture payments on authorization |\n| `webhookSecret` | `string` | - | Optional webhook signing secret |\n\n### Session Data\n\nThe `data` object stored in the payment session contains:\n\n| Field | Description |\n|-------|-------------|\n| `id` | MONEI payment ID |\n| `status` | Current MONEI payment status |\n| `redirect_url` | URL for hosted payment page |\n| `client_secret` | Reference for monei.js (same as payment ID) |\n| `session_id` | Medusa session tracking ID |\n\n## Testing\n\nUse test mode credentials from MONEI Dashboard. Test card numbers and Bizum phone numbers are available in the [MONEI Testing documentation](https://docs.monei.com/testing/).\n\nCommon test cards:\n- **Success**: `4111 1111 1111 1111`\n- **3DS Required**: `4000 0000 0000 3220`\n- **Declined**: `4000 0000 0000 0002`\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/MONEI/medusa-payment-monei.git\ncd medusa-payment-monei\nnpm install\n\n# Build\nnpm run build\n\n# Watch mode\nnpm run watch\n```\n\n### Using as a local module in Medusa\n\nDuring development, you can place the plugin source directly in your Medusa app:\n\n```\nyour-medusa-app/\n  src/\n    modules/\n      monei-payment/\n        service.ts   ← copy from src/service.ts\n        index.ts     ← copy from src/index.ts\n```\n\nThen in `medusa-config.ts`:\n\n```ts\n{\n  resolve: \"@medusajs/medusa/payment\",\n  options: {\n    providers: [\n      {\n        resolve: \"./src/modules/monei-payment\",\n        id: \"monei\",\n        options: {\n          apiKey: process.env.MONEI_API_KEY,\n        },\n      },\n    ],\n  },\n}\n```\n\n## About MONEI\n\n[MONEI](https://monei.com) is a licensed Payment Institution regulated by Banco de España (#6911) and a SWIFT member (BIC: MDIPES22). MONEI provides a unified payments platform for European merchants with direct acquiring for Bizum and multi-acquirer card processing.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonei%2Fmedusa-payment-monei","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonei%2Fmedusa-payment-monei","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonei%2Fmedusa-payment-monei/lists"}