Saleor
Accept payments through MONEI in your Saleor store using the official MONEI Payment App. The app follows the Saleor payment app architecture and supports Cards (Visa, Mastercard, Amex), Bizum, Apple Pay, and Google Pay.
Features
- Supported payment methods — Cards via MONEI.js secure iframe, Bizum via redirect, Apple Pay and Google Pay via MONEI.js components
- Full lifecycle support — , (manual or auto), refund, and cancel
- Multi-acquirer routing — Intelligent routing for optimal authorization rates
- Native Bizum — Direct Bizum acquiring, Spain's dominant mobile payment method
- compliant — Card data handled via MONEI.js secure iframes, keeping your store out of PCI scope
- Webhook-driven — Payment status updates via signed MONEI webhooks
Supported payment methods
| Method | Integration | Capture | Refund | Cancel |
|---|---|---|---|---|
| Cards (Visa, Mastercard, Amex) | MONEI.js secure iframe | Manual / Auto | Yes | Yes |
| Bizum | Redirect | Auto | Yes | Yes |
| Apple Pay | MONEI.js component | Auto | Yes | Yes |
| Google Pay | MONEI.js component | Auto | Yes | Yes |
Requirements
| Dependency | Version |
|---|---|
| Node.js | 18.17+ (LTS recommended) |
| Saleor | 3.13+ (Cloud or self-hosted) |
Before you begin
To test your integration:
- Use your test mode API Key. You can find it in MONEI Dashboard → Settings → API Access.
- You can check the status of a test payment in your MONEI Dashboard → Payments (in test mode).
- See MONEI test cards for test card numbers.
Install
Step 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
Step 2: Install and run
npm install
npm run dev
Step 3: Install in Saleor
- Open Saleor Dashboard → Apps → Install External App
- Enter your manifest URL:
http://localhost:3000/api/manifest - The app registers its webhooks automatically
Configure
| 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 | — |
How it works
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) |
Payment flow
- Customer initiates checkout → Saleor calls
PAYMENT_GATEWAY_INITIALIZE_SESSION - App returns available MONEI payment methods and MONEI.js config
- Customer selects a payment method → Saleor calls
TRANSACTION_INITIALIZE_SESSION - App creates a MONEI payment and returns the redirect URL or MONEI.js data
- Customer completes payment (3D Secure, Bizum redirect, etc.)
- Saleor calls
TRANSACTION_PROCESS_SESSION→ App checks final payment status
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.
Before you go live
- Make sure that you are using live (production) mode API Key.
- Make sure that you have at least one active payment method.
- Set
MONEI_ENVIRONMENT=livein your environment variables.
Links
Was this page helpful?