# Fiuu cloudECR - Laravel 12 Sale Terminal Demo

A standalone Laravel 12 application demonstrating the Fiuu cloudECR Terminal Payment API integration for processing Sale transactions.

## Features

- 🔐 **Authentication** - POS account login with JWT tokens
- 💳 **Sale Transactions** - Process payments via:
  - Bank Card (Credit/Debit cards)
  - QR Customer Scan (Merchant-presented QR)
  - QR Merchant Scan (Customer-presented QR)
- 🔄 **Void Transactions** - Cancel previous transactions
- 📱 **Terminal Management** - View connected terminal status
- 💰 **E-Wallet Channels** - Support for TnG, Boost, GrabPay, ShopeePay, DuitNow QR
- 🔑 **HMAC-SHA256 Signature** - Automatic signature generation and verification

## Demo Credentials (from Fiuu Documentation)

```
POS ID:       fiuuPos1
Merchant ID:  fiuuMerch1
Device ID:    fiuuDeviceId1
Secret Key:   75DC529B942513DFA77F43EC3451F137
MID:          603778000000001
TID:          91100033
```

> ⚠️ **Note:** These are demo credentials. Replace with your actual Fiuu credentials for production use.

## Installation

### 1. Clone/Copy the project

```bash
# If starting fresh with Laravel 12
composer create-project laravel/laravel fiuu-ecr-demo
cd fiuu-ecr-demo

# Copy the provided files to their respective directories
```

### 2. Install Dependencies

```bash
composer install
```

### 3. Configure Environment

```bash
cp .env.example .env
php artisan key:generate
```

Edit `.env` file with your Fiuu credentials:

```env
FIUU_BASE_URL=https://api.cloudecr.fiuu.com
FIUU_POS_ID=your_pos_id
FIUU_PASSWORD=your_password
FIUU_MERCHANT_ID=your_merchant_id
FIUU_DEVICE_ID=your_device_id
FIUU_SECRET_KEY=your_secret_key
```

### 4. Register Service Provider (if needed)

In `config/app.php`, ensure the service binding is registered, or add to `AppServiceProvider`:

```php
// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->singleton(\App\Services\FiuuCloudEcrService::class, function ($app) {
        return new \App\Services\FiuuCloudEcrService();
    });
}
```

### 5. Run the Application

```bash
php artisan serve
```

Visit `http://localhost:8000` in your browser.

## Project Structure

```
fiuu-ecr-demo/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── FiuuEcrController.php    # Main controller
│   └── Services/
│       └── FiuuCloudEcrService.php      # API service class
├── config/
│   └── fiuu.php                         # Fiuu configuration
├── resources/
│   └── views/
│       └── fiuu-ecr/
│           └── index.blade.php          # Main UI view
├── routes/
│   └── web.php                          # Route definitions
└── .env.example                         # Environment template
```

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | Main sale terminal page |
| POST | `/api/fiuu/login` | Authenticate with Fiuu |
| POST | `/api/fiuu/logout` | Clear session tokens |
| POST | `/api/fiuu/refresh-token` | Refresh access token |
| GET | `/api/fiuu/terminals` | List connected terminals |
| GET | `/api/fiuu/ewallet-channels` | Get e-wallet channels |
| POST | `/api/fiuu/sale` | Process sale transaction |
| POST | `/api/fiuu/void` | Void a transaction |
| GET | `/api/fiuu/get-last` | Get last transaction |

## Sale Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `amount` | number | Yes | Transaction amount (e.g., 1.00) |
| `payment_method` | string | Yes | `bankCard`, `qrCustScan`, or `qrMerchScan` |
| `payment_channel` | string | Conditional | Required for `qrCustScan` (e.g., `tng`, `boost`) |
| `reference_label` | string | No | Label on receipt (max 10 chars) |
| `note` | string | No | Receipt note (max 128 chars) |
| `print_count` | number | No | 0=none, 1=merchant, 2=both |

## Signature Generation

The signature is generated using HMAC-SHA256 with the following process:

1. **Flatten** all payload values (excluding `signature` and empty values)
2. **Sort** values alphabetically
3. **Concatenate** all values into a single string
4. **Hash** using HMAC-SHA256 with the secret key

Example:
```php
$service = new FiuuCloudEcrService();
$signature = $service->generateSignature($payload);
```

## Response Status Codes

| Code | Meaning |
|------|---------|
| `00` | Success |
| `11` | Failure |
| `22` | Pending |

## Payment Methods

### Bank Card
- Credit cards (Visa, Mastercard, etc.)
- Debit cards (MyDebit)
- Supports chip, contactless, and manual entry

### QR Customer Scan (qrCustScan)
- Merchant presents QR code on terminal
- Customer scans with e-wallet app
- Requires `paymentChannel` parameter

### QR Merchant Scan (qrMerchScan)
- Customer presents QR code on their phone
- Merchant scans with terminal
- DuitNow QR supported

## E-Wallet Channels

| Channel Code | Name |
|--------------|------|
| `tng` | Touch 'n Go eWallet |
| `boost` | Boost |
| `grabpay` | GrabPay |
| `shopeepay` | ShopeePay |
| `duitNowQr` | DuitNow QR |

## Error Handling

The service class provides detailed error responses:

```php
$result = $service->sale($amount, $paymentMethod, ...);

if ($result['success']) {
    // Transaction successful
    $transData = $result['data']['transData'];
} else {
    // Handle error
    $error = $result['error'];
}
```

## Security Considerations

1. **Never expose your secret key** in client-side code
2. **Validate all responses** using signature verification
3. **Use HTTPS** in production
4. **Store tokens securely** (session with encryption)
5. **Implement proper logging** for transaction audit

## References

- [Fiuu cloudECR Documentation](https://fiuupayment.github.io/cloudECR/docs/introduction)
- [API Reference](https://fiuupayment.github.io/cloudECR/docs/api-reference)
- [Signature Documentation](https://fiuupayment.github.io/cloudECR/docs/signature)
- [Postman Collection](https://fiuupayment.github.io/cloudECR/assets/files/cloudECR-v1.postman_collection-d793a14fac4a26e5be87973a73df395f.json)

## License

This demo is provided for educational and integration testing purposes.
