> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégration SDK PHP

> Guide de configuration rapide pour le SDK Navio PHP

## Vue d'ensemble

Le SDK Navio PHP fournit une interface moderne et typée pour intégrer les paiements Navio dans vos applications PHP. Conçu avec les fonctionnalités PHP 8.1+ et les meilleures pratiques.

<CardGroup cols={2}>
  <Card title="Type Safe" icon="shield-check" color="#0D9373">
    Typages complets PHP 8.1+ et types de retour
  </Card>

  <Card title="Compatible Composer" icon="box" color="#0D9373">
    Autoloading PSR-4 et installation facile
  </Card>

  <Card title="API simple" icon="code" color="#0D9373">
    Interface claire et intuitive
  </Card>

  <Card title="Gestion des erreurs" icon="circle-exclamation" color="#0D9373">
    Exceptions personnalisées pour chaque type d'erreur
  </Card>
</CardGroup>

## Prérequis

* PHP 8.1 ou supérieur
* Composer
* Extension `ext-json`
* Extension `ext-curl`

## Installation

Installez via Composer :

```bash theme={null}
composer require oneclickdz/ocpay-php-sdk
```

Ou ajoutez à votre `composer.json` :

```json theme={null}
{
    "require": {
        "oneclickdz/ocpay-php-sdk": "^1.0"
    }
}
```

## Démarrage rapide

### 1. Initialiser le SDK

```php theme={null}
<?php

require 'vendor/autoload.php';

use OneClickDz\OCPay\OCPay;

// Initialize with your API access token
$ocpay = new OCPay('your-api-access-token');
```

<Warning>
  Stockez votre clé API dans des variables d'environnement, jamais dans le code
</Warning>

```bash theme={null}
# .env file
ONECLICK_API_KEY=your_api_key_here
```

```php theme={null}
// Load from environment
$ocpay = new OCPay(getenv('ONECLICK_API_KEY'));
```

### 2. Créer un lien de paiement

```php theme={null}
use OneClickDz\OCPay\DTO\CreateLinkRequest;
use OneClickDz\OCPay\DTO\ProductInfo;

// Create product information
$productInfo = new ProductInfo(
    title: 'Premium Subscription',
    amount: 5000, // Amount in DZD (500 - 500,000)
    description: 'Monthly access to premium features'
);

// Create payment link request
$request = new CreateLinkRequest(
    productInfo: $productInfo,
    feeMode: CreateLinkRequest::FEE_MODE_NO_FEE,
    successMessage: 'Thank you for your purchase!',
    redirectUrl: 'https://yourstore.com/success?order=12345'
);

// Create the payment link
try {
    $response = $ocpay->createLink($request);
    
    // Redirect customer to payment page
    echo "Payment URL: " . $response->paymentUrl . "\n";
    
    // IMPORTANT: Save this reference!
    echo "Payment Reference: " . $response->paymentRef . "\n";
    saveOrderPaymentRef($orderId, $response->paymentRef);
    
} catch (\OneClickDz\OCPay\Exception\ValidationException $e) {
    echo "Validation error: " . $e->getMessage() . "\n";
} catch (\OneClickDz\OCPay\Exception\UnauthorizedException $e) {
    echo "Auth error: " . $e->getMessage() . "\n";
} catch (\OneClickDz\OCPay\Exception\ApiException $e) {
    echo "API error: " . $e->getMessage() . "\n";
}
```

### 3. Vérifier le statut du paiement

```php theme={null}
// Check payment status using the payment reference
try {
    $status = $ocpay->checkPayment('OCPL-A1B2C3-D4E5');
    
    if ($status->isConfirmed()) {
        // Payment successful - fulfill the order
        echo "Payment confirmed!\n";
        echo "Amount: " . $status->transactionDetails->amount . " DZD\n";
        fulfillOrder($orderId);
        
    } elseif ($status->isFailed()) {
        // Payment failed or expired
        echo "Payment failed: " . $status->message . "\n";
        markOrderFailed($orderId);
        
    } else {
        // Still pending - check again later
        echo "Payment pending...\n";
    }
    
} catch (\OneClickDz\OCPay\Exception\NotFoundException $e) {
    echo "Payment not found\n";
} catch (\OneClickDz\OCPay\Exception\PaymentExpiredException $e) {
    echo "Payment link expired\n";
} catch (\OneClickDz\OCPay\Exception\ApiException $e) {
    echo "API error: " . $e->getMessage() . "\n";
}
```

## Exemple e-commerce complet

Voici un flux complet pour un paiement e-commerce :

```php theme={null}
<?php

require 'vendor/autoload.php';

use OneClickDz\OCPay\OCPay;
use OneClickDz\OCPay\DTO\CreateLinkRequest;
use OneClickDz\OCPay\DTO\ProductInfo;

// Initialize SDK
$ocpay = new OCPay(getenv('ONECLICK_API_KEY'));

// Step 1: Create order in your system
$orderId = createOrder([
    'customer_id' => 123,
    'items' => [
        ['name' => 'Product A', 'price' => 5000],
        ['name' => 'Product B', 'price' => 3000],
    ],
    'total' => 8000,
]);

// Step 2: Create payment link
try {
    $productInfo = new ProductInfo(
        title: "Order #{$orderId}",
        amount: 8000,
        description: "Payment for order #{$orderId}"
    );
    
    $request = new CreateLinkRequest(
        productInfo: $productInfo,
        feeMode: CreateLinkRequest::FEE_MODE_NO_FEE,
        successMessage: "Thank you! Order #{$orderId} confirmed.",
        redirectUrl: "https://yourstore.com/orders/{$orderId}/success"
    );
    
    $response = $ocpay->createLink($request);
    
    // Step 3: Save payment reference
    updateOrder($orderId, [
        'payment_ref' => $response->paymentRef,
        'payment_url' => $response->paymentUrl,
        'status' => 'pending_payment',
    ]);
    
    // Step 4: Redirect customer
    header("Location: " . $response->paymentUrl);
    exit;
    
} catch (ApiException $e) {
    error_log("Payment creation failed: " . $e->getMessage());
    showErrorPage("Failed to create payment. Please try again.");
}
```

### Tâche de fond pour la vérification du statut

Configurez une tâche cron ou un worker de fond :

```php theme={null}
<?php

// check_payments.php - Run every 20 minutes

require 'vendor/autoload.php';

use OneClickDz\OCPay\OCPay;

$ocpay = new OCPay(getenv('ONECLICK_API_KEY'));

// Get all pending orders
$pendingOrders = getPendingOrders();

foreach ($pendingOrders as $order) {
    if (!$order['payment_ref']) {
        continue;
    }
    
    try {
        $status = $ocpay->checkPayment($order['payment_ref']);
        
        if ($status->isConfirmed()) {
            // Mark as paid and fulfill
            updateOrder($order['id'], [
                'status' => 'paid',
                'paid_at' => date('Y-m-d H:i:s'),
            ]);
            fulfillOrder($order['id']);
            
        } elseif ($status->isFailed()) {
            // Mark as failed
            updateOrder($order['id'], [
                'status' => 'payment_failed',
            ]);
        }
        
    } catch (ApiException $e) {
        error_log("Status check failed: " . $e->getMessage());
    }
}
```

Ajoutez au crontab :

```bash theme={null}
*/20 * * * * php /path/to/check_payments.php
```

## Référence API

### Classe OCPay

Point d'entrée principal du SDK.

#### Constructeur

```php theme={null}
public function __construct(
    string $accessToken,
    array $options = []
)
```

**Paramètres :**

* `$accessToken` : Votre token d'accès API
* `$options` : Configuration optionnelle du client Guzzle
  * `timeout` : Délai de la requête en secondes (défaut : 30)

#### Méthodes

**createLink(CreateLinkRequest \$request): CreateLinkResponse**

Crée un lien de paiement.

**checkPayment(string \$paymentRef): CheckPaymentResponse**

Vérifie le statut d'un paiement.

### Objets de Transfert de Données (DTOs)

#### ProductInfo

```php theme={null}
new ProductInfo(
    title: string,        // Product name (1-200 chars)
    amount: int,          // Amount in DZD (500 - 500,000)
    description?: string  // Optional (max 1000 chars)
)
```

#### CreateLinkRequest

```php theme={null}
new CreateLinkRequest(
    productInfo: ProductInfo,
    feeMode?: string,        // NO_FEE (default), SPLIT_FEE, CUSTOMER_FEE
    successMessage?: string, // Optional success message
    redirectUrl?: string     // Optional redirect URL
)
```

**Constantes de mode de frais :**

* `CreateLinkRequest::FEE_MODE_NO_FEE` - Le marchand paie (défaut)
* `CreateLinkRequest::FEE_MODE_SPLIT_FEE` - Partage 50/50
* `CreateLinkRequest::FEE_MODE_CUSTOMER_FEE` - Le client paie

#### CreateLinkResponse

```php theme={null}
$response->paymentUrl     // URL to redirect customer
$response->paymentRef     // Payment reference (SAVE THIS!)
$response->paymentLink    // Full payment link object
```

#### CheckPaymentResponse

```php theme={null}
$response->status                // PaymentStatus enum
$response->message               // Status message
$response->paymentRef           // Payment reference
$response->transactionDetails   // Transaction details (if confirmed)

// Helper methods
$response->isConfirmed()        // true if payment confirmed
$response->isPending()          // true if still pending
$response->isFailed()           // true if failed
```

### Gestion des exceptions

Toutes les exceptions héritent de `OCPayException` :

| Exception                 | Code HTTP | Déclenchée quand             |
| ------------------------- | --------- | ---------------------------- |
| `ValidationException`     | 400       | Données de requête invalides |
| `UnauthorizedException`   | 403       | Clé API invalide             |
| `NotFoundException`       | 404       | Paiement introuvable         |
| `PaymentExpiredException` | 410       | Lien expiré (>20 min)        |
| `ApiException`            | Divers    | Autres erreurs API           |

Toutes les exceptions fournissent :

```php theme={null}
try {
    $response = $ocpay->createLink($request);
} catch (ApiException $e) {
    echo $e->getMessage();       // Error message
    echo $e->getStatusCode();    // HTTP status code
    echo $e->getRequestId();     // Request ID for support
    var_dump($e->getErrorData()); // Full error data
}
```

## Notes importantes

### Validation du marchand requise

<Warning>
  Complétez la validation du marchand sur [app.oneclickdz.com](https://app.oneclickdz.com/profile) avant d'utiliser l'API
</Warning>

### Limites de montant

* **Minimum** : 500 DZD
* **Maximum** : 500 000 DZD
* Doit être un nombre entier

### Structure des frais

<Info>
  **Frais réduits** : 0% sur le solde, seulement 1% de frais de retrait
</Info>

### Expiration du lien de paiement

Les liens expirent **20 minutes** après leur création si le paiement n'est pas initié.

### Flux des statuts de paiement

1. **PENDING** - Paiement en cours → Revérifier plus tard
2. **CONFIRMED** - Paiement réussi → Honorer la commande
3. **FAILED** - Paiement refusé/expiré → Marquer la commande comme échouée

## Intégration Laravel

Pour les projets Laravel, consultez l'exemple d'intégration complet dans le [dépôt GitHub](https://github.com/oneclickdz/ocpay-php-sdk/tree/main/examples/laravel).

Inclut :

* Configuration du service provider
* Classe de service de paiement
* Exemples de contrôleurs
* Migrations de base de données
* Tâche de fond pour la vérification
* Gestion des erreurs

## Tests

### Utilisation du Sandbox

L'API utilise automatiquement le mode sandbox pour les comptes de test :

```php theme={null}
$response = $ocpay->createLink($request);

if ($response->paymentLink->isSandbox) {
    echo "This is a test payment\n";
}
```

### Tests unitaires

```bash theme={null}
composer install --dev
vendor/bin/phpunit
```

## Meilleures pratiques

<AccordionGroup>
  <Accordion title="Toujours sauvegarder la référence de paiement" icon="database">
    Stockez `paymentRef` immédiatement après la création du lien. Vous en aurez besoin pour vérifier le statut du paiement.
  </Accordion>

  <Accordion title="Vérifier le statut du paiement" icon="clock">
    Configurez une tâche de fond pour vérifier le statut du paiement toutes les 20 minutes pour les commandes en attente.
  </Accordion>

  <Accordion title="Gérer toutes les exceptions" icon="shield-halved">
    Capturez et gérez tous les types d'exceptions de manière appropriée. Journalisez les erreurs pour le débogage.
  </Accordion>

  <Accordion title="Sécuriser votre clé API" icon="key">
    Stockez les clés API dans des variables d'environnement, ne les committez jamais dans le contrôle de version.
  </Accordion>

  <Accordion title="Utiliser HTTPS uniquement" icon="lock">
    Utilisez toujours HTTPS pour les URLs de redirection et les endpoints de votre application.
  </Accordion>
</AccordionGroup>

## Support & Ressources

<CardGroup cols={2}>
  <Card title="Dépôt GitHub" icon="github" href="https://github.com/oneclickdz/ocpay-php-sdk">
    Code source, exemples et problèmes
  </Card>

  <Card title="Documentation API" icon="book" href="/fr/api-reference/ocpay/create-link">
    Référence API détaillée
  </Card>

  <Card title="Exemple Laravel" icon="code" href="https://github.com/oneclickdz/ocpay-php-sdk/tree/main/examples/laravel">
    Intégration Laravel complète
  </Card>

  <Card title="Contacter le support" icon="headset" href="/fr/contact">
    Obtenez l'aide de notre équipe
  </Card>
</CardGroup>

## Prochaines étapes

<Card title="Meilleures pratiques Navio" icon="star" href="/fr/ocpay-guides/4-best-practices">
  Découvrez les conseils de production et les meilleures pratiques de sécurité
</Card>