MONEI Payment App for Saleor

Accept Bizum, card payments, Apple Pay, and Google Pay in your Saleor store.
Documentation →

---

Overview

MONEI is a Payment Institution licensed by the Banco de España (reg. #6911), providing API-first payment infrastructure for online and in-store commerce across Spain and Europe.

This Saleor App integrates MONEI as a payment gateway, following the Saleor payment app architecture and communicating via synchronous webhooks.

Supported payment methods

Method	Integration	Capture	Refund	Cancel
Card (Visa, Mastercard, Amex)	MONEI.js secure iframe	Manual / Auto	✓	✓
Bizum	Redirect	Auto	✓	✓
Apple Pay	MONEI.js component	Auto	✓	✓
Google Pay	MONEI.js component	Auto	✓	✓

Why MONEI?

• Multi-acquirer routing — intelligent routing across multiple acquirers for optimal authorization rates
• Scheme tokenization — network tokens via Visa and Mastercard for higher approval rates and lower fraud
• Native Bizum — the only Saleor payment app offering direct Bizum acquiring, Spain's dominant mobile payment method (28M+ users)
• PCI DSS compliant — card data handled via MONEI.js secure iframes, keeping your store out of PCI scope
• One integration, multiple methods — cards, Bizum, Apple Pay, and Google Pay through a single app

---

Architecture

Storefront                Saleor                   This App                 MONEI API
    |                       |                         |                        |
    |-- paymentGatewayInit ->|                         |                        |
    |                       |-- GATEWAY_INIT_SESSION ->|                        |
    |                       |<- payment methods -------|                        |
    |<- methods ------------|                         |                        |
    |                       |                         |                        |
    |-- transactionInit ---->|                         |                        |
    |                       |-- TX_INIT_SESSION ------>|-- create payment ----->|
    |                       |                         |<- payment + redirect --|
    |                       |<- result + redirect ----|                        |
    |<- redirect ------------|                         |                        |
    |                       |                         |                        |
    |-- transactionProcess ->|                         |                        |
    |                       |-- TX_PROCESS_SESSION --->|-- get payment -------->|
    |                       |                         |<- final status --------|
    |                       |<- final result ---------|                        |
    |<- confirmation --------|                         |                        |

The app handles three Saleor synchronous webhooks:

Webhook	Purpose
PAYMENT_GATEWAY_INITIALIZE_SESSION	Returns available payment methods and MONEI.js configuration
TRANSACTION_INITIALIZE_SESSION	Creates a MONEI payment and returns the result or redirect URL
TRANSACTION_PROCESS_SESSION	Checks payment status after customer action (3D Secure, Bizum)

---

Quick start

Prerequisites

• Node.js 18.17+ (LTS recommended)
• MONEI account — sign up at monei.com and get your API Key from Dashboard → Settings → API Access
• Saleor 3.13+ (Cloud or self-hosted)

1. Clone and configure

git clone https://github.com/MONEI/saleor-monei.git
cd saleor-monei
cp .env.example .env

Edit .env with your MONEI credentials:

MONEI_API_KEY=your_api_key
MONEI_ACCOUNT_ID=your_account_id
NEXT_PUBLIC_APP_URL=http://localhost:3000

2. Install and run

npm install
npm run dev

3. Install in Saleor

1. Open Saleor Dashboard → Apps → Install External App
2. Enter your manifest URL: http://localhost:3000/api/manifest
3. The app registers its webhooks automatically

---

Configuration

Variable	Description	Required	Default
MONEI_API_KEY	API key from MONEI Dashboard	Yes	—
MONEI_ACCOUNT_ID	Merchant account ID	Yes	—
MONEI_WEBHOOK_SECRET	HMAC key for webhook signature verification	No	—
MONEI_ENVIRONMENT	test or live	No	test
APL	Auth persistence layer: file (dev) or upstash (prod)	No	file
NEXT_PUBLIC_APP_URL	Public URL where this app is hosted	Yes	—

---

Deployment

Deploy to Vercel, Railway, or any platform that supports Next.js.

npm run build
npm start

For production multi-tenant deployments, set APL=upstash and configure Upstash Redis for auth token storage.

---

Development

npm run dev       # Start dev server
npm run lint      # Lint with ESLint
npm run build     # Production build
npm test          # Run tests

Project structure

src/
  lib/
    monei-client.ts          # MONEI Payments API client
    monei-status-mapping.ts  # MONEI -> Saleor status mapping
    config.ts                # Environment config with Zod validation
    saleor-app.ts            # Saleor auth persistence layer
  pages/
    api/
      manifest.ts            # App manifest (metadata + webhooks)
      register.ts            # App installation handler
      webhooks/
        payment-gateway-initialize-session.ts
        transaction-initialize-session.ts
        transaction-process-session.ts
    index.tsx                # Dashboard configuration page

---

Documentation

Resource	Link
MONEI API Reference	docs.monei.com/api
MONEI.js Overview	docs.monei.com/docs/monei-js/overview
Saleor Payment Apps	docs.saleor.io/developer/payments/payment-apps
Building a Payment App	docs.saleor.io/developer/extending/apps/building-payment-app

---

MONEI Digital Payments, S.L.
Passeig de Gràcia, 19, 08007 Barcelona, Spain
Banco de España reg. #6911

Website · API Docs · Support · LinkedIn

MIT License © 2026 MONEI