# PHP SDK

[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge\&logo=github\&logoColor=white)](https://github.com/MonerooHQ/moneroo-php) [![Star on GitHub](https://img.shields.io/badge/Star-GitHub-blue?style=for-the-badge\&logo=github)](https://github.com/MonerooHQ/moneroo-php/stargazers)\
[![PHP Version](https://img.shields.io/packagist/php-v/moneroo/moneroo-php.svg)](https://packagist.org/packages/moneroo/moneroo-php) [![Build Status](https://github.com/monerooHQ/moneroo-php/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/moneroo/moneroo-php/actions?query=branch%3Amain) [![Latest Stable Version](https://poser.pugx.org/moneroo/moneroo-php/v/stable.svg)](https://packagist.org/packages/moneroo/moneroo-php) [![Total Downloads](https://poser.pugx.org/moneroo/moneroo-php/downloads.svg)](https://packagist.org/packages/moneroo/moneroo-php) [![License](https://poser.pugx.org/moneroo/moneroo-php/license.svg)](https://packagist.org/packages/moneroo/moneroo-php)

Le SDK Moneroo PHP est une bibliothèque complète qui permet aux développeurs PHP d'interagir avec le service d'orchestration des paiements Moneroo.

### Besoins

*PHP 7.4 et versions ultérieures.*

### Installation

Vous pouvez installer le paquet via `composer` :

```bash
composer require moneroo/moneroo-php
```

### Paiement

La classe `Moneroo\Payment` fournit des méthodes pour initialiser, vérifier, récupérer et marquer les paiements comme traités. Vous pouvez l'utiliser comme suit :

#### Initier le paiement

Pour créer un paiement, vous devez transmettre un tableau de données de paiement à la méthode de création. Le tableau doit contenir les clés suivantes :

Voici les champs obligatoires sous forme de tableau :

<table><thead><tr><th width="240">Nom des champs</th><th width="97">Type</th><th width="117">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>amount</code></td><td>integer</td><td>Oui</td><td>Le montant du paiement.</td></tr><tr><td><code>currency</code></td><td>string</td><td>Oui</td><td>La devise du paiement.</td></tr><tr><td><code>description</code></td><td>string</td><td>Non</td><td>Description du paiement.</td></tr><tr><td><code>return_url</code></td><td>string</td><td>Oui</td><td>URL de retour où votre client sera redirigé après le paiement.</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Oui</td><td>Adresse e-mail du client.</td></tr><tr><td><code>customer.first_name</code></td><td>string</td><td>Oui</td><td>Prénom du client.</td></tr><tr><td><code>customer.last_name</code></td><td>string</td><td>Oui</td><td>Nom du client.</td></tr><tr><td><code>customer.phone</code></td><td>string</td><td>Non<strong>¹</strong></td><td>Numéro de téléphone du client dans le format <a href="https://en.wikipedia.org/wiki/E.164">E164</a>.</td></tr><tr><td><code>customer.address</code></td><td>string</td><td>Non<strong>¹</strong></td><td>Adresse du client.</td></tr><tr><td><code>customer.city</code></td><td>string</td><td>Non<strong>¹</strong></td><td>Ville du client.</td></tr><tr><td><code>customer.state</code></td><td>string</td><td>Non<strong>¹</strong></td><td>État du client.</td></tr><tr><td><code>customer.country</code></td><td>string</td><td>Non<strong>¹</strong></td><td>Pays du client. Il s'agir du code du pays au format <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-1 alpha-2</a> valide.</td></tr><tr><td><code>customer.zip</code></td><td>string</td><td>Non<strong>¹</strong></td><td>Code postal du client.</td></tr><tr><td><code>metadata</code></td><td>array</td><td>Non<strong>²</strong></td><td>Données supplémentaires pour le paiement.</td></tr><tr><td><code>methods</code></td><td>array</td><td>Non<strong>³</strong></td><td>Méthodes de paiement autorisées.</td></tr></tbody></table>

1. Si ces informations ne sont pas fournies, le client peut être invité à les saisir au cours de la procédure de paiement, en fonction de la méthode de paiement sélectionnée.
2. Il s'agit d'un tableau de paires clé-valeur. Seules les chaînes de caractères sont autorisées.
3. S'il n'est pas fourni, tous les modes de paiement disponibles seront autorisés. Le tableau ne doit contenir que les méthodes de paiement prises en charge.

**Exemple d'utilisation**

```php
$paymentData = [
    'amount' => 100,
    'currency' => 'USD',
    'customer' => [
        'email' => 'john.doe@example.com',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'phone' => '123456789',
        'address' => '123 Main St',
        'city' => 'Los Angeles',
        'state' => 'CA',
        'country' => 'USA',
        'zip' => '90001',
    ],
    'description' => 'Payment for order #123',
    'return_url' => 'https://yourwebsite.com/thanks',
    'metadata' => [
        'order_id' => '123',
        'customer_id' => '456',
    ],
    'methods' => ['card', 'orange_ci'],
];
$monerooPayment = new \Moneroo\Payment($publicKey, $secretKey);
$payment = $monerooPayment->init($paymentData);

// Redirect the customer to the Checkout URL
header('Location: ' . $payment->checkout_url);

```

La méthode `create` renvoie un objet contenant les détails du paiement, y compris l'identifiant de la transaction et l'URL de paiement vers laquelle vous devez rediriger le client pour qu'il effectue le paiement. Vous pouvez utiliser cet identifiant de transaction pour vérifier le paiement ultérieurement.

#### Vérifier le paiement

Vous pouvez vérifier un paiement à l'aide de son `id`. Cette fonction est utile lorsque vous souhaitez vérifier l'état d'un paiement avant de traiter une commande de votre côté.

```php
$transactionId = 'your-payment-transaction-id';

$monerooPayment = new \Moneroo\Payment();
$payment = $monerooPayment->verify($transactionId);
```

#### Récupération du paiement

Pour obtenir les détails d'un paiement, utilisez la méthode `get` avec l'id de la transaction.

```php
$transactionId = 'your-payment-transaction-id';

$monerooPayment = new \Moneroo\Payment($publicKey, $secretKey);
$payment = $monerooPayment->get($transactionId);
```

#### Marquer le paiement comme traité

Il s'agit actuellement d'une fonctionnalité expérimentale. Veuillez l'utiliser avec prudence et signaler tout problème que vous rencontrez.

Cette méthode est utile lorsque vous souhaitez marquer un paiement comme étant traité après avoir reçu un rappel de l'API Moneroo et avoir traité la commande de votre côté. Cela vous permet également d'éviter les commandes en double ou de stocker les identifiants des transactions dans votre base de données pour référence ultérieure.

Pour marquer un paiement comme traité, utilisez la méthode `makeAsProcessed` avec l'id de la transaction.

Exemple d'usage :

```php
$transactionId = 'your-payment-transaction-id';

$monerooPayment = new \Moneroo\Payment($publicKey, $secretKey);
$payment = $monerooPayment->makeAsProcessed($transactionId);
```

### Transfert

La classe `Moneroo\Payout` fournit des méthodes d'initialisation, de vérification et de récupération des paiements.

#### Initier le paiement

Pour initialiser un tranfert, vous devez transmettre un tableau de données répondant aux règles de validation spécifiées. Le tableau doit contenir les clés suivantes :

Voici les champs obligatoires sous forme de tableau :

<table><thead><tr><th width="257">Nom des champs</th><th width="91">Type</th><th width="120">Obligatoire</th><th>Description</th></tr></thead><tbody><tr><td><code>amount</code></td><td>integer</td><td>Oui</td><td>Le montant du transfert.</td></tr><tr><td><code>currency</code></td><td>string</td><td>Oui</td><td>La devise du transfert. La devise doit être une devise prise en charge dans un format <a href="https://en.wikipedia.org/wiki/ISO_4217">ISO 4217</a> valide.</td></tr><tr><td><code>description</code></td><td>string</td><td>Oui</td><td>Description du transfert.</td></tr><tr><td><code>customer.email</code></td><td>string</td><td>Oui</td><td>Adresse e-mail du client.</td></tr><tr><td><code>customer.first_name</code></td><td>string</td><td>Oui</td><td>Prénom du client.</td></tr><tr><td><code>customer.last_name</code></td><td>string</td><td>Oui</td><td>Nom du client.</td></tr><tr><td><code>return_url</code></td><td>string</td><td>Oui</td><td>URL de retour où votre client sera redirigé après le transfert.</td></tr><tr><td><code>customer.phone</code></td><td>string</td><td>Non</td><td>Numéro de téléphone du client dans le format <a href="https://en.wikipedia.org/wiki/E.164">E164</a>.</td></tr><tr><td><code>customer.address</code></td><td>string</td><td>Non</td><td>Adresse du client.</td></tr><tr><td><code>customer.city</code></td><td>string</td><td>Non</td><td>Ville du client.</td></tr><tr><td><code>customer.state</code></td><td>string</td><td>Non</td><td>État du client.</td></tr><tr><td><code>customer.country</code></td><td>string</td><td>Non</td><td>Pays du client. Il s'agir du code du pays au format <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-1 alpha-2</a> valide.</td></tr><tr><td><code>customer.zip</code></td><td>string</td><td>Non</td><td>Code postal du client.</td></tr><tr><td><code>metadata</code></td><td>array</td><td>Non</td><td>Données supplémentaires pour le transfert.</td></tr><tr><td><code>method</code></td><td>string</td><td>Oui<strong>¹</strong></td><td>Méthodes de transfert autorisées </td></tr><tr><td><code>request_confirmation</code><strong>²</strong></td><td>bool</td><td>Non</td><td>Si vous souhaitez demander une confirmation au client.</td></tr></tbody></table>

{% hint style="info" %}

1. &#x20;Il s'agit d'une [méthode de transfert](https://docs.moneroo.io/fr/payouts/methodes-disponibles) supportée par Moneroo
2. Cette fonctionnalité est actuellement en phase expérimentale et n'est pas disponible pour tous les utilisateurs/applications. Elle vous permet de demander une confirmation à un client avant de procéder au transfert. Moneroo enverra un e-mail au client contenant un code de confirmation. Le client est alors dirigé vers une page de confirmation où il peut vérifier le montant du paiement et les détails de son compte. Si les informations sont correctes, le client peut saisir le code de confirmation pour approuver ou rejeter la demande de paiement. Cette fonction est un outil précieux pour éviter les informations incorrectes ou les transactions frauduleuses. Si l'utilisateur ne répond pas dans les 15 minutes, la demande de paiement sera automatiquement annulée.
   {% endhint %}

En plus des informations ci-dessus, vous devez ajouter des champs obligatoires pour les méthodes de tranfert dans les détails du compte. Par exemple, si le mode de paiement est `mtn_bj`, vous devez fournir les champs `msisdn.`

Il s'agit d'une information différente de celle de l'utilisateur, qui indique où l'argent sera versé. Pour plus d'informations, veuillez consulter les champs obligatoires pour chaque méthode de transfert.

```php
$payoutData = [
    'amount' => 100,
    'currency' => 'USD',
    'customer' => [
        'email' => 'john.doe@example.com',
        'first_name' => 'John',
        'last_name' => 'Doe',
        // other customer details...
    ],
    'description' => 'Salary payment',
    'method' => 'mtn_bj',
    'msisdn' => '22912345678', // required field for mtn_bj payout method
    // other data...
];

$monerooPayout = new Moneroo\Payout($publicKey, $secretKey);
$payout = $monerooPayout->init($payoutData);
```

La méthode `create` renvoie un objet contenant les détails du paiement, y compris l'id de la transaction et le statut du paiement. Vous pouvez utiliser cet identifiant de transaction pour vérifier le paiement ultérieurement.

#### Vérifier le transfert

Vous pouvez vérifier un tranfert grâce à l'id de la transaction.

```php
$transactionId = 'your-payout-transaction-id';

$monerooPayout = new Moneroo\Payout($publicKey, $secretKey);
$payout = $monerooPayout->verify($transactionId);
```

#### Récupérer le tranfert

Pour obtenir les détails d'un tranfert, utilisez la méthode `get` avec l'id de la transaction.

```php
$transactionId = 'your-payout-transaction-id';

$payout = new \Moneroo\Payout($publicKey, $secretKey);
$payout = $payout->get($transactionId);
```

### Traitement des exceptions

Le SDK est livré avec un certain nombre d'exceptions personnalisées pour vous aider à gérer les erreurs potentielles qui peuvent survenir lors de l'utilisation de l'API Moneroo. Ces exceptions sont les suivantes :

* **InvalidPayloadException** : Cette exception est déclenchée lorsque la charge utile envoyée à l'API ne répond pas aux critères attendus.
* **ForbiddenException** : Cette exception est déclenchée lorsque l'utilisateur authentifié tente d'effectuer une action pour laquelle il ne dispose pas des autorisations nécessaires.
* **InvalidResourceException** : Cette exception est déclenchée lorsqu'une requête est adressée à une ressource inexistante ou invalide.
* **ServerErrorException** : Cette exception est déclenchée en cas d'erreur du côté du serveur.
* **NotAcceptableException** : Cette exception est déclenchée lorsque les caractéristiques du contenu de la demande du client ne sont pas acceptables selon les en-têtes Accept envoyés dans la demande.
* **ServiceUnavailableException** : Cette exception est déclenchée lorsque le service est actuellement indisponible, peut-être en raison de problèmes de maintenance ou de charge sur le serveur.
* **UnauthorizedException** : Cette exception est levée lorsque la demande ne comporte pas d'informations d'authentification valides pour la ressource cible.

Pour chaque exception, vous pouvez accéder au message d'erreur en appelant`$exception->getMessage()`, et au code d'erreur (s'il est disponible) en appelant`$exception->getCode()`.

### Support

Si vous avez des questions ou besoin d'aide, n'hésitez pas à [nous contacter](https://moneroo.io/contact). Nous sommes toujours heureux de répondre à vos questions.

### Vulnérabilités sécuritaires

Si vous découvrez une faille de sécurité dans le SDK PHP de Moneroo, veuillez envoyer un e-mail à Moneroo Security via <security@moneroo.io>. Toutes les failles de sécurité seront traitées rapidement.

### Licence

Le SDK Moneroo PHP est un logiciel libre sous licence MIT.