# Simply.IN Payment — Magento 2 Module

**Module:** `Simplyin_Payment`  
**Version:** 1.1.0  
**Compatibility:** Magento 2.4.x  
**Author:** Simply.IN  
**Support:** support@simplyin.app

---

## Table of Contents

1. [What is Simply.IN?](#what-is-simplyin)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Configuration](#configuration)
5. [How It Works](#how-it-works)
6. [GraphQL API](#graphql-api)
7. [Troubleshooting](#troubleshooting)

---

## What is Simply.IN?

Simply.IN is a Polish 1-click checkout add-on that provides:

- **One-click checkout** — customers authenticate once with OTP (SMS, push notification, or email) and their details are pre-filled on future visits
- **Multiple payment methods** — BLIK (PLN only), credit/debit cards with 3D Secure, saved cards
- **Parcel locker selection** — InPost, Orlen, DPD, DHL, UPS pickup points directly in checkout
- **Order history** — customers can view all their purchases across Simply.IN stores in one place

---

## Requirements

- Magento 2.4.x
- PHP 8.1+
- A Simply.IN merchant account and API key
- HTTPS enabled on your store

---

## Installation

### 1. Copy module files

Place the module in `app/code/Simplyin/Payment/`.

### 2. Run Magento setup commands

```bash
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
```

### 3. Verify installation

```bash
php bin/magento module:status Simplyin_Payment
```

The output should show `Module is enabled`.

---

## Configuration

Go to **Stores → Configuration → Sales → Payment Methods → Simply.IN Payment**.

### Required Settings

| Field | Description |
|-------|-------------|
| **Enabled** | Set to `Yes` to activate the payment method |
| **API Key** | Your Simply.IN merchant API key (stored encrypted) |
| **API Base URL** | Simply.IN API endpoint (default: `https://preprod.backend.simplyin.app/api`) |
| **Shop Name** | Your store name as registered in Simply.IN |
| **Domain Origin** | Your store domain (e.g., `https://yourstore.com`) — sent as `Origin` header in API requests |

### Optional Settings

| Field | Default | Description |
|-------|---------|-------------|
| **Title** | `Simple and Safe payments` | Payment method label shown at checkout |
| **Default "Remember details" checked** | No | Pre-check the account creation checkbox |
| **Transaction History Days** | `180` | How many days of order history to sync to Simply.IN |
| **Sync Batch Size** | `50` | Number of orders processed per cron run |

### Shipping Method Mapping

Map your Magento shipping methods to Simply.IN parcel locker providers so the correct pickup point is applied when a customer selects a locker:

| Setting | Example Value |
|---------|--------------|
| DPD Pickup | `dpdpoland_dpdshippingpickup` |
| DHL BOX i POP | `dhl_dhl24pl` |
| InPost Paczkomat | `inpostpaczkomat_inpostpaczkomat` |
| ORLEN Punkty | `macopedia_orlenshipping` |
| UPS Pickup | `ups_ups` |
| Default Courier | `flatrate_flatrate` |

---

## How It Works

### Customer Checkout Flow

1. **Email step** — Customer enters their email. The module checks if they have a Simply.IN account.
   - **Existing user** → OTP sent via SMS, push notification, or email
   - **New user** → Registration form shown (name, phone number)

2. **Authentication** — Customer enters the 4-digit OTP code. On success, their saved addresses and payment methods are loaded automatically.

3. **Payment step** — Customer selects a payment method:
   - **BLIK** (PLN only) — Enter 6-digit code from banking app
   - **New card** — Enter card details securely via CCIframe (PCI compliant)
   - **Saved card** — One-click payment with a previously saved card

4. **Payment processing** — Payment is processed **before** the Magento order is created. If payment fails, the customer can retry without losing their cart.

5. **Order creation** — Once payment succeeds (or 3D Secure is completed), the Magento order is created and the customer is redirected to the success page.

### "Remember your details" Section

For customers using **other payment methods** (PayPal, Stripe, etc.), a "Remember your details with Simply.IN" section appears below the payment methods. If the customer checks this box and enters their phone number, a Simply.IN account is created for them when the order is placed.

This section:
- Only shows for **new** Simply.IN users (not for already authenticated users)
- Hides automatically when the customer logs in via the Simply.IN popup
- Updates dynamically when the email address is changed

### Order Status Sync

When an order status changes in Magento (e.g., to `complete` or `shipped`), the module automatically notifies Simply.IN so the customer can see the updated status in their Simply.IN account.

### Tracking Number Sync

When a shipment with a tracking number is created in Magento, the tracking information is automatically sent to Simply.IN.

---

## GraphQL API

The module exposes a GraphQL API at `POST /graphql`.

> **Note:** Before testing, ensure the GraphQL schema cache is clear:
> ```bash
> php bin/magento cache:clean
> ```

### Testing with Postman

1. Create a new request in Postman
2. Method: `POST`
3. URL: `https://yourstore.com/graphql`
4. Headers: `Content-Type: application/json`
5. Body → **raw** → **JSON**

### Authentication Flow

**Step 1 — Check email and send OTP:**

```json
{
  "query": "mutation { simplyinCheckEmail(email: \"customer@example.com\") { success message user_exists user_used_push_notifications notification_token_id masked_data } }"
}
```

**Step 2 — Verify OTP:**

```json
{
  "query": "mutation { simplyinVerifyOtp(email: \"customer@example.com\", code: \"1234\") { success message auth_token user_data { email name surname phone } } }"
}
```

**Step 3 — Get user data** (use `auth_token` from Step 2):

```json
{
  "query": "{ simplyinGetUserData(auth_token: \"YOUR_TOKEN_HERE\") { success message user_data { email name surname phone raw_json } } }"
}
```

### Account Creation

```json
{
  "query": "mutation { simplyinCreateAccount(email: \"new@example.com\", first_name: \"Jan\", last_name: \"Kowalski\", phone: \"+48123456789\") { success message auth_token requires_otp } }"
}
```

### Resend OTP

```json
{
  "query": "mutation { simplyinResendOtp(email: \"customer@example.com\", method: \"sms\") { success message method } }"
}
```

Available `method` values: `sms`, `email`

### Check Push Notification Status

```json
{
  "query": "mutation { simplyinCheckPushStatus(email: \"customer@example.com\", notification_token_id: \"TOKEN_ID\") { success approved auth_token user_data { email name } } }"
}
```

### Get Payment Methods

```json
{
  "query": "{ simplyinGetPaymentMethods { success message payment_methods { payment_method_id type name } } }"
}
```

### Check Payment Status

```json
{
  "query": "{ simplyinCheckPaymentStatus(payment_id: \"PAYMENT_ID\", auth_token: \"AUTH_TOKEN\") { success status order_id simplyin_status } }"
}
```

### Address Management

**Add address:**

```json
{
  "query": "mutation { simplyinAddAddress(auth_token: \"TOKEN\", address: { name: \"Jan\", surname: \"Kowalski\", street: \"ul. Przykładowa 1\", city: \"Kraków\", postal_code: \"30-001\", country: \"PL\" }) { success message address { id name street city } } }"
}
```

**Search address:**

```json
{
  "query": "{ simplyinSearchAddress(auth_token: \"TOKEN\", query: \"Kraków Floriańska\") { success addresses_raw_json } }"
}
```

### Parcel Lockers

**Find nearby lockers:**

```json
{
  "query": "{ simplyinGetParcelLockers(auth_token: \"TOKEN\", action: \"closest\", coordinates: { lat: 50.0614, lng: 19.9366 }, limit: 10, radius: 5000) { success parcel_machines { locker_id provider_name name address } pickup_points { locker_id provider_name name address } } }"
}
```

### Place Magento Order

```json
{
  "query": "mutation { simplyinPlaceMagentoOrder(quote_id: \"QUOTE_ID\", simplyin_order_id: \"SIMPLYIN_ORDER_ID\", simplyin_payment_id: \"PAYMENT_ID\", payment_status: \"PAID\", payment_type: \"card\", auth_token: \"TOKEN\") { success message order_id increment_id } }"
}
```

### Update Order Payment Info

```json
{
  "query": "mutation { simplyinUpdateOrderPayment(order_id: 123, simplyin_order_id: \"SIMPLYIN_ORDER_ID\", payment_info: { simplyin_payment_id: \"PAY_ID\", simplyin_payment_status: \"PAID\" }) { success message } }"
}
```

---

## Troubleshooting

### GraphQL returns "Syntax Error: Unexpected Name Input"

This is caused by a conflicting `input` type definition in another module's `schema.graphqls`. Check for modules that redefine core Magento types like `ProductAttributeFilterInput`. Remove the duplicate definition and clear cache:

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

### Payment section not showing at checkout

1. Check that the module is enabled: `php bin/magento module:status Simplyin_Payment`
2. Verify the API Key is configured in admin
3. Clear static content and cache:
   ```bash
   rm -rf pub/static/frontend/
   php bin/magento cache:flush
   php bin/magento setup:static-content:deploy -f
   ```

### BLIK not showing as a payment option

BLIK is only available when the store currency is **PLN**. Check your store currency in Stores → Configuration → General → Currency Setup.

### Account creation section not hiding after SimplyIN login

Clear browser cache and static content. The section uses JavaScript observables that react to the `simplyin:auth_successful` event fired when the user authenticates via the popup.

### Order status not syncing to Simply.IN

Check `var/log/simplyin_payment.log` for errors. Common causes:
- Order not in `simplyin_order_sync` table (only orders placed via Simply.IN payment are tracked)
- API key not configured or expired
- Status is in the stop list (e.g., `processing` is not synced by design)

### Cron jobs not running

Verify the `simplyin` cron group is configured:

```bash
php bin/magento cron:run --group simplyin
```

Check `var/log/simplyin_payment.log` for cron output.

### Logs

| Log File | What to check |
|----------|--------------|
| `var/log/simplyin_payment.log` | General module activity |
| `var/log/simplyin_webhook.log` | Webhook payloads received |
| `var/log/simplyin_checkemail.log` | Email check API calls |
| `var/log/system.log` | PHP errors and exceptions |

---

## Support

- **Email:** support@simplyin.app
- **API Docs:** https://preprod.backend.simplyin.app/api-docs
- **Simply.IN Website:** https://www.simply.in
