# Saleor

Accept payments through MONEI in your [Saleor](https://saleor.io/) store using the official [MONEI Payment App](https://github.com/MONEI/saleor-monei). The app follows the Saleor payment app architecture and supports Cards (Visa, Mastercard, Amex), Bizum, Apple Pay, and Google Pay.

## Features[​](#features "Direct link to 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** — Authorize, capture (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
* **PCI DSS 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[​](#supported-payment-methods "Direct link to 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[​](#requirements "Direct link to Requirements")

| Dependency | Version                      |
| ---------- | ---------------------------- |
| Node.js    | 18.17+ (LTS recommended)     |
| Saleor     | 3.13+ (Cloud or self-hosted) |

## Before you begin[​](#before-you-begin "Direct link to Before you begin")

To test your integration:

* Use your [test mode](https://docs.monei.com/testing/.md) API Key. You can find it in [MONEI Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api).
* You can check the status of a test payment in your [MONEI Dashboard → Payments](https://dashboard.monei.com/payments) (in test mode).
* See [MONEI test cards](https://docs.monei.com/testing/.md) for test card numbers.

## Install[​](#install "Direct link to Install")

### Step 1: Clone and configure[​](#step-1-clone-and-configure "Direct link to 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[​](#step-2-install-and-run "Direct link to Step 2: Install and run")

```
npm install

npm run dev
```

### Step 3: Install in Saleor[​](#step-3-install-in-saleor "Direct link to Step 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

## Configure[​](#configure "Direct link to Configure")

| Variable               | Description                                                              | Required | Default |
| ---------------------- | ------------------------------------------------------------------------ | -------- | ------- |
| `MONEI_API_KEY`        | API key from [MONEI Dashboard](https://dashboard.monei.com/settings/api) | 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[​](#how-it-works "Direct link to 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[​](#payment-flow "Direct link to Payment flow")

1. Customer initiates checkout → Saleor calls `PAYMENT_GATEWAY_INITIALIZE_SESSION`
2. App returns available MONEI payment methods and MONEI.js config
3. Customer selects a payment method → Saleor calls `TRANSACTION_INITIALIZE_SESSION`
4. App creates a MONEI payment and returns the redirect URL or MONEI.js data
5. Customer completes payment (3D Secure, Bizum redirect, etc.)
6. Saleor calls `TRANSACTION_PROCESS_SESSION` → App checks final payment status

<!-- -->

## Deployment[​](#deployment "Direct link to Deployment")

Deploy to [Vercel](https://vercel.com), [Railway](https://railway.app), or any platform that supports Next.js:

```
npm run build

npm start
```

For production multi-tenant deployments, set `APL=upstash` and configure [Upstash Redis](https://upstash.com) for auth token storage.

## Before you go live[​](#before-you-go-live "Direct link to Before you go live")

* Make sure that you are using [live (production) mode](https://docs.monei.com/testing/.md) API Key.
* Make sure that you have at least one active [payment method](https://dashboard.monei.com/settings/payment-methods).
* Set `MONEI_ENVIRONMENT=live` in your environment variables.

## Links[​](#links "Direct link to Links")

* [MONEI Saleor Payment App on GitHub](https://github.com/MONEI/saleor-monei)
* [Saleor Payment Apps documentation](https://docs.saleor.io/developer/payments/payment-apps)
* [Building a Saleor Payment App](https://docs.saleor.io/developer/extending/apps/building-payment-app)
* [MONEI JS SDK documentation](https://docs.monei.com/monei-js/overview/.md)