# Onboarding Flow

The onboarding flow handles the initial setup of the Clip Redirect plugin, guiding merchants through credential configuration.

## Overview

When the plugin is activated for the first time, merchants are automatically redirected to an onboarding page that embeds Clip's hosted onboarding interface. This interface collects API credentials and validates them before saving to WordPress.

## Flow Diagram

```mermaid
sequenceDiagram
    participant Admin as WordPress Admin
    participant Plugin as ClipRedirect Plugin
    participant OnboardingPage as Onboarding Page (iframe)
    participant ClipOnboarding as Clip Onboarding Service
    participant AJAX as WordPress AJAX
    participant SDK as ClipRedirectSdk
    participant ClipAPI as Clip API

    Note over Admin,ClipAPI: Plugin Activation
    Admin->>Plugin: Activates plugin
    Plugin->>Plugin: Check WooCommerce installed
    Plugin->>Admin: Redirect to onboarding page
    Admin->>OnboardingPage: Load admin page
    OnboardingPage->>ClipOnboarding: Load iframe with params
    Note right of OnboardingPage: URL includes:<br/>- ecommerce=woo<br/>- version<br/>- wp-nonce<br/>- wp-base-url

    Note over Admin,ClipAPI: Credential Collection
    Admin->>ClipOnboarding: Enters API Key & Secret
    ClipOnboarding->>ClipOnboarding: Validates format
    ClipOnboarding->>OnboardingPage: postMessage with credentials
    
    Note over Admin,ClipAPI: Credential Storage
    OnboardingPage->>AJAX: POST clip_save_settings
    Note right of AJAX: Data sent:<br/>- apiKey<br/>- apiSecret<br/>- wpClipNonce
    
    AJAX->>AJAX: Verify nonce
    AJAX->>Plugin: SaveSettingsAction::run()
    Plugin->>Plugin: Save credentials to options
    Plugin->>SDK: Initialize SDK with credentials
    
    Note over Admin,ClipAPI: Credential Validation
    SDK->>SDK: Check if first onboarding
    
    alt First Time Setup
        SDK->>ClipAPI: POST /v2/checkout (dummy payment)
        Note right of SDK: Creates test payment<br/>to validate credentials
        ClipAPI-->>SDK: Returns CHECKOUT_CREATED
        SDK->>Plugin: Set clip_first_onboarding flag
    else Subsequent Setup
        SDK->>ClipAPI: GET /payments/receipt-no/5mUV5Dt
        ClipAPI-->>SDK: Returns receipt data
    end
    
    alt Validation Success
        SDK-->>Plugin: Credentials valid (true)
        Plugin-->>AJAX: Success response
        AJAX-->>OnboardingPage: Credentials saved
        OnboardingPage->>Admin: Show success message
    else Validation Failure
        SDK-->>Plugin: Credentials invalid (false)
        Plugin->>Plugin: Clear saved credentials
        Plugin-->>AJAX: Error response
        AJAX-->>OnboardingPage: Save failed
        OnboardingPage->>Admin: Show error message
    end
```

## Key Components

### 1. ClipRedirect::activation()
**File**: `clip-for-woocommerce.php`

Triggered on plugin activation, redirects to onboarding page.

```php
public static function activation( $plugin ) {
    if ( ! class_exists( 'WooCommerce' ) ) {
        return false;
    }
    self::redirect_to_onboarding_on_activation( $plugin );
}
```

### 2. Onboarding\Main::register_onboarding_page()
**File**: `src/onboarding/class-main.php`

Registers the onboarding submenu page under WooCommerce.

```php
add_submenu_page(
    'woocommerce',
    __( 'Clip', 'clip-for-woocommerce' ),
    __( 'Clip', 'clip-for-woocommerce' ),
    'manage_woocommerce',
    'wc-clipredirect-onboarding',
    array( __CLASS__, 'content' )
);
```

### 3. Onboarding\Main::content()
**File**: `src/onboarding/class-main.php`

Generates the onboarding page with embedded iframe.

**Key features**:
- Detects site language (English or Spanish)
- Builds iframe URL with query parameters
- Creates WordPress nonce for security
- Passes WooCommerce base URL to iframe

**URL parameters sent to iframe**:
```php
$front_url = add_query_arg( 'ecommerce', 'woo', $front_url );
$front_url = add_query_arg( 'version', \ClipRedirect::VERSION, $front_url );
$front_url = add_query_arg( 'wp-nonce', $nonce, $front_url );
$front_url = add_query_arg( 'wp-base-url', $site_url, $front_url );
```

### 4. page-onboarding.php Template
**File**: `templates/page-onboarding.php`

Renders the iframe and handles postMessage communication.

**JavaScript functionality**:
- Listens for `message` events from iframe
- Validates message data structure
- Sends credentials to WordPress via AJAX
- Handles success/error responses

**Message data structure**:
```javascript
{
    api_key: 'string',
    api_secret: 'string',
    wp_clip_nonce: 'string',
    url: 'site_url'
}
```

### 5. SaveSettingsAction::ajax_callback_wp()
**File**: `src/onboarding/class-save-settings-action.php`

AJAX handler for saving credentials.

**Steps**:
1. Validate AJAX request (nonce, required fields)
2. Sanitize and save API credentials
3. Validate credentials against Clip API
4. Return success or error response

### 6. Helper::validate_credentials()
**File**: `src/helper/class-validations-trait.php`

Validates API credentials by making a test API call.

**Validation logic**:
```php
public static function validate_credentials() {
    $sdk = new ClipRedirectSdk(
        self::get_option( 'api_key' ),
        self::get_option( 'api_secret' )
    );

    $firstOnboarding = get_option( 'clip_first_onboarding', false );

    if ( ! $firstOnboarding ) {
        // First time: create dummy payment
        $ret = $sdk->request_first_deposit();
        update_option( 'clip_first_onboarding', $ret );
        return $ret;
    } else {
        // Subsequent: validate with receipt check
        return $sdk->validate_receipt();
    }
}
```

### 7. ClipRedirectSdk::request_first_deposit()
**File**: `src/sdk/class-clip-redirect-sdk.php`

Creates a dummy payment to validate credentials on first setup.

**Test payment data**:
```php
$data_to_send = array(
    'amount'               => 3.00,
    'currency'             => 'MXN',
    'purchase_description' => 'Authenticate woocommerce',
    'redirection_url'      => array(
        'success' => get_site_url(),
        'error'   => get_site_url(),
        'default' => get_site_url(),
    ),
    'metadata'             => array(
        'me_reference_id' => 'authenticate woocommerce',
        'customer_info'   => array(
            'name'  => 'Alejandro Lee',
            'email' => 'buyer@hotmail.com',
            'phone' => 5520686868,
        ),
        'source'          => 'woocommerce',
        'source_version'  => \ClipRedirect::VERSION,
    ),
    'override_settings'    => array(
        'payment_method' => array( 'CASH', 'CARD' ),
    ),
    'webhook_url'          => get_site_url() . '/wc-api/wc-clip',
);
```

## WordPress Options

The onboarding process creates/updates the following options:

| Option Key | Description | Value Type |
|-----------|-------------|------------|
| `woocommerce_wc_clipredirect_settings` | All plugin settings including credentials | Array |
| `clip_first_onboarding` | Flag indicating first validation completed | Boolean |

## Security Measures

1. **Nonce Verification**: All AJAX requests validate WordPress nonces
2. **Data Sanitization**: User inputs are sanitized using WordPress functions
3. **Capability Check**: Onboarding page requires `manage_woocommerce` capability
4. **Credential Validation**: API credentials are validated before storage
5. **Origin Validation**: PostMessage communication can validate origin (currently commented)

## Error Handling

### Common Errors

| Error Code | Description | Action |
|-----------|-------------|---------|
| `missing nonce` | Nonce not provided in request | Request rejected |
| `invalid nonce` | Nonce verification failed | Request rejected |
| `missing apiKey` | API Key not provided | Request rejected |
| `missing apiSecret` | API Secret not provided | Request rejected |
| `invalid credentials` | API credentials validation failed | Credentials cleared |

### Error Response Example

```json
{
    "success": false,
    "data": "nonce"
}
```

## Post-Onboarding

After successful onboarding:

1. Credentials are saved to WordPress options
2. `clip_first_onboarding` flag is set to `true`
3. Plugin is ready to process payments
4. Merchant can access settings at: **WooCommerce > Settings > Payments > Clip**

## Manual Configuration

Merchants can also configure credentials manually by:

1. Going to **WooCommerce > Settings > Payments > Clip**
2. Entering API Key and Secret in the credentials section
3. Saving settings (triggers validation)

## Environment URLs

### Production
- Onboarding URL: `https://plugin-onboarding.payclip.com`
- API URL: `https://api.payclip.com`

### Development
- Onboarding URL: `https://stage-plugin-onboarding.payclip.com`
- API URL: `https://stage-api.payclip.com`

## Hooks and Filters

| Hook | Type | Description |
|------|------|-------------|
| `activated_plugin` | Action | Triggers onboarding redirect |
| `admin_menu` | Action | Registers onboarding page |
| `wp_ajax_clip_save_settings` | Action | Handles credential save AJAX |

## Related Files

- `clip-for-woocommerce.php` - Main plugin file with activation hook
- `src/onboarding/class-main.php` - Onboarding page registration and rendering
- `src/onboarding/class-save-settings-action.php` - AJAX handler for saving credentials
- `templates/page-onboarding.php` - Onboarding page template with iframe
- `src/sdk/class-clip-redirect-sdk.php` - SDK with validation methods
- `src/helper/class-validations-trait.php` - Credential validation logic