PHP SDK

Le SDK PHP officiel de Kobara permet d’intégrer facilement :

• les paiements MonCash ;
• les liens de paiement ;
• les retraits ;
• les webhooks ;
• les notifications temps réel ;

dans vos applications PHP.

Le SDK est optimisé pour :

• PHP natif ;
• Laravel ;
• Symfony ;
• CodeIgniter ;
• APIs REST ;
• applications ecommerce.

Installation

Installez le SDK avec Composer :

BASH
content_copy
composer require kobara/php-sdk

Compatibilité

Initialisation

Le SDK doit être initialisé avec votre Secret Key.

⚠️ Toujours côté serveur.

PHP
content_copy
<?php

require 'vendor/autoload.php';

use Kobara\KobaraClient;

$kobara = new KobaraClient(
    getenv('KOBARA_SECRET_KEY')
);

Variables d’environnement

ENV
content_copy
KOBARA_SECRET_KEY=kbr_sk_live_xxxxxxxxx

Important

⚠️ Ne jamais exposer votre Secret Key :

• dans JavaScript ;
• dans le frontend ;
• dans React ;
• dans une application mobile ;
• dans du HTML public.

Premier paiement

Exemple PHP natif

PHP
content_copy
<?php

require 'vendor/autoload.php';

use Kobara\KobaraClient;

$kobara = new KobaraClient(
    getenv('KOBARA_SECRET_KEY')
);

$payment = $kobara->payments->create([

    "amount" => 1000,

    "currency" => "HTG",

    "description" => "Achat Laravel",

    "customer" => [

        "name" => "Marie Exemple",

        "phone" => "50900000000"

    ]

]);

header("Location: " . $payment->url);

exit();

Explication du flux

1. Le client clique “Payer”

Votre frontend appelle :

Terminal
content_copy
POST /checkout

2. Votre backend PHP crée le paiement

Le SDK :

• contacte l’API Kobara ;
• sécurise la requête ;
• communique avec MonCash ;
• prépare le checkout MonCash.

3. Kobara retourne une URL

JSON
content_copy
{
  "url":
  "https://checkout.kobara.app/pay/abc123"
}

4. Redirection utilisateur

PHP
content_copy
header("Location: " . $payment->url);
exit();

Pourquoi utiliser le SDK PHP

Le SDK :

• simplifie les intégrations ;
• évite les requêtes HTTP manuelles ;
• gère l’authentification ;
• valide les réponses ;
• simplifie les webhooks ;
• réduit les erreurs.

Créer un paiement

Exemple complet

PHP
content_copy
$payment = $kobara->payments->create([

    "amount" => 2500,

    "currency" => "HTG",

    "description" => "Commande Kobara",

    "customer" => [

        "name" => "Jean Pierre",

        "email" => "client@email.com",

        "phone" => "50937000000"

    ],

    "metadata" => [

        "order_id" => "ORDER_001"

    ]

]);

Paramètres disponibles

Réponse paiement

JSON
content_copy
{
  "id": "pay_123",
  "status": "pending",
  "url": "https://checkout.kobara.app/pay/123",
  "amount": 2500,
  "currency": "HTG"
}

Vérifier un paiement

PHP
content_copy
$payment = $kobara->payments->retrieve(
    "pay_123"
);

Exemple réponse

JSON
content_copy
{
  "id": "pay_123",
  "status": "succeeded",
  "amount": 2500
}

Lister les paiements

PHP
content_copy
$payments = $kobara->payments->list();

Payment Links

Créer des liens de paiement partageables.

PHP
content_copy
$link = $kobara->paymentLinks->create([

    "amount" => 1500,

    "currency" => "HTG",

    "title" => "Paiement Boutique"

]);

Réponse

JSON
content_copy
{
  "url":
  "https://pay.kobara.app/link/abc123"
}

Retraits

Créer un retrait MonCash.

PHP
content_copy
$withdrawal = $kobara->withdrawals->create([

    "amount" => 5000,

    "phone" => "50937000000"

]);

Réponse retrait

JSON
content_copy
{
  "id": "wd_001",
  "status": "processing"
}

Webhooks

Le SDK PHP aide à vérifier les signatures webhooks.

PHP
content_copy
$event = $kobara->webhooks->constructEvent(

    $payload,

    $signature,

    getenv("KOBARA_WEBHOOK_SECRET")

);

Exemple webhook PHP

PHP
content_copy
<?php

$payload = file_get_contents("php://input");

$signature =
    $_SERVER["HTTP_KOBARA_SIGNATURE"];

try {

    $event =
        $kobara->webhooks->constructEvent(

            $payload,

            $signature,

            getenv("KOBARA_WEBHOOK_SECRET")
        );

    http_response_code(200);

} catch (Exception $e) {

    http_response_code(400);

    echo $e->getMessage();
}

Types d’événements

Gestion des erreurs

Le SDK retourne des erreurs propres.

PHP
content_copy
try {

    $payment =
        $kobara->payments->create([...]);

} catch (Exception $error) {

    echo $error->getMessage();

}

Exemple erreur

JSON
content_copy
{
  "error": {
    "code": "invalid_amount",
    "message": "Amount is required"
  }
}

Architecture recommandée

Correct

Terminal
content_copy
Frontend
↓
Backend PHP
↓
Kobara SDK
↓
API Kobara
↓
MonCash / MonCash

Architecture incorrecte

Terminal
content_copy
Frontend
↓
MonCash directement

ou :

Terminal
content_copy
Frontend
↓
Secret Key Kobara

Bonnes pratiques

À faire

✅ utiliser .env ✅ utiliser HTTPS ✅ vérifier les webhooks ✅ sécuriser le backend ✅ logger les erreurs

À éviter

❌ exposer Secret Key ❌ utiliser le SDK côté frontend ❌ appeler MonCash directement ❌ hardcoder les secrets

Exemple Laravel

PHP
content_copy
use Kobara\KobaraClient;

$kobara = new KobaraClient(
    env("KOBARA_SECRET_KEY")
);

$payment = $kobara->payments->create([

    "amount" => 1000,

    "currency" => "HTG"

]);

return redirect($payment->url);

Exemple Symfony

PHP
content_copy
$kobara = new KobaraClient(
    $_ENV["KOBARA_SECRET_KEY"]
);

$payment = $kobara->payments->create([

    "amount" => 1000,

    "currency" => "HTG"

]);