<!-- canonical: https://docs.costplus.io/docs/plugins/magento -->

> Integrate Cost+ with your Magento store (2.x and 1.9 / OpenMage LTS)
<div style={{background: 'white', borderRadius: '8px', padding: '1rem', display: 'inline-block', marginBottom: '1rem'}}>
  <img src="/images/logos/magento.png" alt="Magento" style={{height: '48px', width: 'auto'}} />
</div>

Integrate Cost+ as a payment method in your Magento store. The Cost+ extension is available for **Magento 2** (2.4.6 – 2.4.8) and **Magento 1.9** (including OpenMage LTS 20+).

## Prerequisites

#### Magento 2

- Active Cost+ merchant account
- Magento 2.4.6 – 2.4.8 installation
- PHP 8.2 – 8.4
- Admin access to your Magento admin panel
- SSH access to your server (for Composer installation)

#### Magento 1.9

- Active Cost+ merchant account
- Magento 1.9.x or OpenMage LTS 20+
- PHP 7.4 or later
- Admin access to your Magento admin panel
- SSH or FTP access to your server

## 1. Install the Extension

#### Magento 2

### Method A: Installation via Composer (Recommended)

Connect to your Magento server via SSH and navigate to your Magento root directory.

Install the plugin:

```bash
composer require nopayn/nopayn-magento-2
```

Run Magento setup commands:

```bash
php bin/magento setup:upgrade
php bin/magento module:enable GingerPay_Payment
php bin/magento cache:clean
```

If you are in **production mode**, also run:

```bash
php bin/magento setup:static-content:deploy
```

### Method B: Manual Installation

1. Navigate to your `app/code` directory
2. Download and unzip the [Cost+ release from GitHub](https://github.com/NoPayn/nopayn-magento-2)
3. Run the setup commands:

```bash
php bin/magento setup:upgrade
php bin/magento cache:clean
```

If in production mode:

```bash
php bin/magento setup:static-content:deploy
```

#### Magento 1.9

Download or clone the module from [GitHub](https://github.com/NoPayn/magento1_9).

Copy the contents of `app/` into your Magento root `app/` directory:

```bash
cp -r app/* /path/to/magento/app/
```

Clear the Magento cache:

```bash
rm -rf var/cache/*
```

Log in to the Magento admin panel and navigate to **System → Configuration → Sales → Payment Methods** to verify the **NoPayn Payment Gateway** section appears.

> [!NOTE]
> The module creates a `nopayn_transactions` table in your database to track payment transactions. This is created automatically on first use.

## 2. Configure the Plugin

#### Magento 2

1. Go to **Stores → Configuration → Sales → Payment Methods → Cost+ Payments**
2. Enter your API key (see step 3 below)
3. Enable the payment methods you have been approved for
4. Save changes

#### Magento 1.9

1. Go to **System → Configuration → Sales → Payment Methods**
2. Locate the **NoPayn Payment Gateway** section
3. Enter your API key (see step 3 below)
4. Enable individual payment methods (Credit / Debit Card, Apple Pay, Google Pay, Vipps MobilePay)
5. Optionally restrict by country
6. Save configuration

## 3. Enter API Credentials

Log into the [Merchant Portal](https://dashboard.costplus.io/) and navigate to **Websites**, then click on the website you want to connect. Click on **Integration** where you will find your API key.

![Cost+ Merchant Portal showing API key](/images/plugins/shared/merchant-portal-api-key.png)

Paste the API key into the configuration field and save.

> [!WARNING]
> Only activate the payment methods you have been approved for and received confirmation for.

## Supported Payment Methods

| Checkout Name | NoPayn Identifier |
|---|---|
| Credit / Debit Card | `credit-card` |
| Apple Pay | `apple-pay` |
| Google Pay | `google-pay` |
| Vipps MobilePay | `vipps-mobilepay` |

## Payment Flow

#### Magento 2

1. Customer selects a payment method at checkout and places the order
2. Customer is redirected to the NoPayn Hosted Payment Page
3. After payment, the customer returns and the order status is updated automatically
4. NoPayn sends a webhook for asynchronous status confirmation

#### Magento 1.9

1. Customer selects a payment method at checkout and places the order
2. Order is created with status **Pending Payment**
3. Customer is redirected to the NoPayn secure payment page
4. After payment:
   - **Success** — customer returns, status verified via API, order set to **Processing**
   - **Cancelled** — customer returns, order set to **Canceled**
   - **Expired** (5-minute timeout) — webhook fires, order set to **Canceled**
5. NoPayn sends a webhook for asynchronous status confirmation

### Order Status Mapping

| NoPayn Status | Magento Order State | Magento Order Status |
|---|---|---|
| `new` | pending_payment | Pending Payment |
| `processing` | pending_payment | Pending Payment |
| `completed` | processing | Processing |
| `cancelled` | canceled | Canceled |
| `expired` | canceled | Canceled |
| `error` | canceled | Canceled |

### Webhooks

The module registers a webhook endpoint at `/nopayn/payment/webhook`. This URL is automatically sent to NoPayn when creating orders. The webhook always verifies the order status via the NoPayn API before updating the Magento order.

> [!NOTE]
> No manual webhook configuration is required — the module handles registration automatically.

## 4. Test Your Setup

1. Place a few test transactions — both successful and failed
2. Verify all enabled payment methods appear at checkout
3. Configure capture behavior (auto-capture vs. manual) based on your fulfillment process

## Support

Need help? Reach out to our support team at **support@costplus.io**.