Intégration SDK PHP - OneClickDz Flexy API

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.

Type Safe

Typages complets PHP 8.1+ et types de retour

Compatible Composer

Autoloading PSR-4 et installation facile

API simple

Interface claire et intuitive

Gestion des erreurs

Exceptions personnalisées pour chaque type d’erreur

Prérequis

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

Installation

Installez via Composer :

composer require oneclickdz/ocpay-php-sdk

Ou ajoutez à votre composer.json :

{
    "require": {
        "oneclickdz/ocpay-php-sdk": "^1.0"
    }
}

Démarrage rapide

1. Initialiser le SDK

<?php

require 'vendor/autoload.php';

use OneClickDz\OCPay\OCPay;

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

Stockez votre clé API dans des variables d’environnement, jamais dans le code

# .env file
ONECLICK_API_KEY=your_api_key_here

// Load from environment
$ocpay = new OCPay(getenv('ONECLICK_API_KEY'));

2. Créer un lien de paiement

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

// 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

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

// 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 :

*/20 * * * * php /path/to/check_payments.php

Référence API

Classe OCPay

Point d’entrée principal du SDK.

Constructeur

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

new ProductInfo(
    title: string,        // Product name (1-200 chars)
    amount: int,          // Amount in DZD (500 - 500,000)
    description?: string  // Optional (max 1000 chars)
)

CreateLinkRequest

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

$response->paymentUrl     // URL to redirect customer
$response->paymentRef     // Payment reference (SAVE THIS!)
$response->paymentLink    // Full payment link object

CheckPaymentResponse

$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 :

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

Complétez la validation du marchand sur app.oneclickdz.com avant d’utiliser l’API

Limites de montant

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

Structure des frais

Frais réduits : 0% sur le solde, seulement 1% de frais de retrait

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

PENDING - Paiement en cours → Revérifier plus tard
CONFIRMED - Paiement réussi → Honorer la commande
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. 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 :

$response = $ocpay->createLink($request);

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

Tests unitaires

composer install --dev
vendor/bin/phpunit

Meilleures pratiques

Toujours sauvegarder la référence de paiement

Stockez paymentRef immédiatement après la création du lien. Vous en aurez besoin pour vérifier le statut du paiement.

Vérifier le statut du paiement

Configurez une tâche de fond pour vérifier le statut du paiement toutes les 20 minutes pour les commandes en attente.

Gérer toutes les exceptions

Capturez et gérez tous les types d’exceptions de manière appropriée. Journalisez les erreurs pour le débogage.

Sécuriser votre clé API

Stockez les clés API dans des variables d’environnement, ne les committez jamais dans le contrôle de version.

Utiliser HTTPS uniquement

Utilisez toujours HTTPS pour les URLs de redirection et les endpoints de votre application.

Support & Ressources

Dépôt GitHub

Code source, exemples et problèmes

Documentation API

Référence API détaillée

Exemple Laravel

Intégration Laravel complète

Contacter le support

Obtenez l’aide de notre équipe

Prochaines étapes

Meilleures pratiques Navio

Découvrez les conseils de production et les meilleures pratiques de sécurité

​Vue d’ensemble

Type Safe

Compatible Composer

API simple

Gestion des erreurs

​Prérequis

​Installation

​Démarrage rapide

​1. Initialiser le SDK

​2. Créer un lien de paiement

​3. Vérifier le statut du paiement

​Exemple e-commerce complet

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

​Référence API

​Classe OCPay

​Constructeur

​Méthodes

​Objets de Transfert de Données (DTOs)

​ProductInfo

​CreateLinkRequest

​CreateLinkResponse

​CheckPaymentResponse

​Gestion des exceptions

​Notes importantes

​Validation du marchand requise

​Limites de montant

​Structure des frais

​Expiration du lien de paiement

​Flux des statuts de paiement

​Intégration Laravel

​Tests

​Utilisation du Sandbox

​Tests unitaires

​Meilleures pratiques

​Support & Ressources

Dépôt GitHub

Documentation API

Exemple Laravel

Contacter le support

​Prochaines étapes

Meilleures pratiques Navio

Vue d’ensemble

Prérequis

Installation

Démarrage rapide

1. Initialiser le SDK

2. Créer un lien de paiement

3. Vérifier le statut du paiement

Exemple e-commerce complet

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

Référence API

Classe OCPay

Constructeur

Méthodes

Objets de Transfert de Données (DTOs)

ProductInfo

CreateLinkRequest

CreateLinkResponse

CheckPaymentResponse

Gestion des exceptions

Notes importantes

Validation du marchand requise

Limites de montant

Structure des frais

Expiration du lien de paiement

Flux des statuts de paiement

Intégration Laravel

Tests

Utilisation du Sandbox

Tests unitaires

Meilleures pratiques

Support & Ressources

Prochaines étapes