moneywave
1.0.0
Une bibliothèque PHP pour consommer les services de l'API moneywave .
Vous pouvez consulter la documentation pour voir tout ce qui est disponible : https://moneywave-doc.herokuapp.com/
Pour commencer, il vous suffit de l'installer via composer :
$ composer require emmanix2002/ moneywave
Cela l'ajoutera à votre composer.json et l'installera en tant que dépendance du projet.
Toutes les fonctionnalités et ressources disponibles sur le service moneywave sont exposées en tant que Services . Par conséquent, pour utiliser l’un des services, il doit d’abord être créé.
Toutes les fonctionnalités et ressources de l'API moneywave sont exposées en tant que services dans cette bibliothèque.
Le point d'entrée de cette bibliothèque est la classe moneywave .
$ moneywave = new moneywave ();
Nous en discuterons davantage plus tard.
Pour utiliser la bibliothèque, vous devez obtenir vos informations d'identification sur votre compte moneywave . Ils vous fournissent deux clés :
Votre compte peut être dans l'un des deux états suivants : Test ou Production . Pour chacun de ces états , vous utiliserez des clés différentes .
Ces clés sont requises par la classe moneywave (et doivent être protégées : elles sont utilisées pour authentifier le compte marchand) ; pour les utiliser avec cette bibliothèque, vous pouvez utiliser l'une des deux méthodes possibles.
L'utilisation de cette méthode stocke la clé dans un fichier spécifique sur votre serveur, ce qui signifie que les valeurs ne sont pas codées en dur dans votre code. La bibliothèque s'attend à trouver un fichier appelé .env au même niveau que le répertoire de votre vendor de compositeur .
.env
vendor/
composer.json
composer.lock
Comme vous pouvez le voir ci-dessus, le fichier de paramètres doit être au niveau décrit. Le contenu du fichier doit être le même que celui que vous pouvez trouver dans le .env.example comme ceci :
# your account moneywave API key
moneywave _API_KEY="your API key goes here"
# your account moneywave Secret key
moneywave _SECRET_KEY="your secret key goes here"
# the environment - staging | production
moneywave _ENV="staging"
Ces valeurs doivent être définies pour utiliser la bibliothèque ; Ceci fait, vous pouvez simplement appeler :
$ moneywave = new moneywave ();
La deuxième façon de configurer le client moneywave consiste à transmettre tous les paramètres au constructeur.
Contrairement à la première méthode , vous devrez stocker les clés quelque part et les fournir au client lorsque vous l'instancierez.
$ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);
Lorsque le client est instancié ( voir configuration), il démarre automatiquement le service VerifyMerchant . Ce service obtient un access token du service moneywave qui sera utilisé pour autoriser toutes les autres demandes que vous effectuez auprès de l'API.
Chaque access token a une durée de vie de 2 hours . Dans votre candidature, vous avez l'une des 2 options suivantes :
Session pour l'utiliser sur plusieurs requêtes Pour la première option, jetez un œil aux exemples de fichiers dans le répertoire examples . Vous verrez quelque chose comme ceci :
use Emmanix2002 moneywave ExceptionValidationException;
use Emmanix2002 moneywave moneywave ;
require(dirname(__DIR__).'/vendor/autoload.php');
session_start();
try {
$accessToken = !empty($_SESSION['accessToken']) ? $_SESSION['accessToken'] : null;
$mw = new moneywave ($accessToken);
$_SESSION['accessToken'] = $mw->getAccessToken();
$query = $mw->createWalletBalanceService();
$response = $query->send();
var_dump($response->getData());
var_dump($response->getMessage());
} catch (ValidationException $e) {
var_dump($e->getMessage());
}
Cela permet d'utiliser le même access token pour une autre requête provenant de la même machine.
Après avoir instancié l'objet moneywave , vous suivez ces étapes pour utiliser un service :
create*Service()send() sur l' objet de service créé. Chaque fonctionnalité et ressource est mappée à un service ; les mappages peuvent être facilement déduits du nom de la classe .
Le tableau ci-dessous décrit tous les services :
| Nom de la classe | Appel de service |
|---|---|
| Validation du numéro de compte | createAccountNumberValidationService |
| CompteVersCompte | createAccountToAccountService |
| CompteVersPortefeuille | createAccountToWalletService |
| Transfert de compte | createAccountTransferService |
| Banques | créer un service de banque |
| CarteVersCompteBanque | createCardToBankAccountService |
| CardTokenisation | createCardTokenizationService |
| Carte vers portefeuille | créer une carte vers un service de portefeuille |
| Transfert de carte | créer un service de transfert de cartes |
| Débourser | createDisburseService |
| Décaissement en vrac | createDisburseBulkService |
| InternetBankingVers Portefeuille | créerInternetBankingToWalletService |
| RequêteCardToAccountTransfer | createQueryCardToAccountTransfer |
| RequêteDéboursement | createQueryDisbursementService |
| RéessayerÉchec du transfert | createRetryFailedTransferService |
| Charge totale vers la carte | createTotalChargeToCardService |
| Valider le transfert de carte | createValidateCardTransferService |
| ValiderTransfert | createValidateTransferService |
| Vérifier le marchand | createVerifyMerchantService |
| PortefeuilleSolde | créerWalletBalanceService |
Chaque service possède une liste de propriétés qui doivent être définies avant de pouvoir être envoyé à l'API ; si une ou plusieurs de ces propriétés ne sont pas définies, l'appel de send() lève une ValidationException .
Utilisons la ressource Account Number validation API comme exemple :
D'après la documentation, les propriétés suivantes sont requises :
| Nom du champ | Description |
|---|---|
| numéro_compte | le numéro de compte de l'expéditeur |
| code_banque | le code banque du compte à résoudre |
Pour utiliser la bibliothèque, nous ferons quelque chose comme ceci :
$ moneywave = new moneywave ();
$accountValidation = $ moneywave ->createAccountNumberValidationService();
$accountValidation->account_number = '0690000004';
$accountValidation->bank_code = Banks::ACCESS_BANK;
$response = $accountValidation->send();
Si l'un de ces champs n'était pas défini sur l' objet de service , une exception ValidationException aurait été levée.
Chaque champ défini dans la documentation moneywave (pour un service) peut être défini comme propriété sur l'objet de service créé.
Certains champs sont spéciaux et n'ont pas besoin d'être définis par vous (bien que vous puissiez choisir de les définir) ; ils recevront automatiquement la valeur requise par la bibliothèque. Retrouvez-les ci-dessous :
| Champ | Description |
|---|---|
| Clé API | ceci sera défini sur la clé API utilisée pour instancier l'objet moneywave |
| secrète | cela sera défini sur la clé secrète utilisée pour l'objet moneywave |
| frais | réglé par défaut à 0 |
| destinataire | pour createCardToWalletService , ceci est défini sur wallet par défaut |
| devise | automatiquement réglé sur Naira Currency::NAIRA |
Tout comme il existe des champs spéciaux, il existe également des objets de service spéciaux, qui présentent plus que la méthode habituelle : send() .
createCardToBankAccountService() , createCardToWalletService() )Ces services de transfert sont particuliers car, la plupart du temps, ils se font à 2 pattes . Ils impliquent les étapes suivantes :
1 La jambe de transfert 2 La jambe de validation
Ces étapes fonctionnent les unes après les autres ; et les deux étapes doivent être complétées pour terminer le transfert.
Il existe 2 services qui s'occupent de la phase validation ; ils sont:
createValidateCardTransferService() : permet de valider un transfert de carte à portefeuille ou de carte à compte effectué avec une carte de débit VervecreateValidateTransferService() : permet de valider un transfert de carte vers portefeuille ou de carte vers compte effectué avec un compte. Autrement dit, le champ charge_with a été défini sur ChargeMethod::ACCOUNT .Ainsi, lorsque vous recevez une réponse positive de l'API après la première étape ; vous démarrez l'étape de validation.
REMARQUE : Pour les transferts par carte Mastercard et Visa, vous recevrez une clé authurl dans la réponse API réussie ; vous devez rediriger vers cette URL pour que le payeur valide le transfert. Après succès ou échec, le payeur sera redirigé vers l'URL définie dans le champ redirecturl de la demande de transfert.
Ce service permet de décaisser de l'argent de votre portefeuille moneywave vers plusieurs comptes bancaires. Il comporte une méthode spéciale pour ajouter les comptes beneficiary individuels.
addRecipient(string $bankCode, string $accountNumber, float $amount, string $reference = null);
Cette méthode permet d'ajouter tour à tour chaque compte bénéficiaire :
$bulkDisbursement = $ moneywave ->createDisburseBulkService();
$bulkDisbursement->lock = 'wallet password';
$bulkDisbursement->ref = 'unique reference'; # suggestion: you could use a UUID; check out ramsey/uuid package
$bulkDisbursement->senderName = ' moneywave SDK';
$bulkDisbursement->addRecipient(Banks::ACCESS_BANK, '0690000004', 1)
->addRecipient(Banks::ACCESS_BANK, '0690000005', 2);
Regardez le fichier examples/disburse_bulk.php pour l'exemple complet.
Si tous les champs obligatoires sur l' objet de service (voir services) ont été définis, l'appel à send() renverra un objet de réponse qui est une instance de la classe moneywave Response .
Pour continuer avec l'exemple de validation de compte ci-dessus :
$response = $accountValidation->send();
Une réponse JSON réussie sera de cette forme :
{
status: "success",
data: {
name: "MICHAEL JACKSON"
}
}
Alors qu'une réponse d'échec JSON sera de la forme :
{
status: "error",
message: "error message description",
code: "error code string; e.g. INVALID_ID",
data: "data string -- this is absent most of the time"
}
La variable $response présente quelques fonctions qui peuvent être utilisées pour travailler avec ces données :
# was a request successful?
if ($response->isSuccessful()) {
# do something with the returned data
$name = $response->getData()['name'];
} else {
# this was a failure
$message = $response->getMessage();
$code = $response->getCode();
$data = $response->getData();
}
REMARQUE : toutes les clés de la réponse JSON sont également accessibles depuis l' objet de réponse en tant que propriétés :
if ($response->isSuccessful()) {
$name = $response->getData()['name'];
} else {
$message = $response->message;
$code = $response->code;
}
Comme autre exemple, la réponse du service VerifyMerchant ressemble à ceci :
{
status: "success",
token: "" // a valid merchant token
}
En utilisant la réponse, vous devrez faire ceci :
$response = $verifyService->send();
if ($response->isSuccessful()) {
$token = $response->token;
} else {
# process the error response as you normally would
}
Le tableau ci-dessous décrit les méthodes définies sur l'objet moneywave Response :
| Méthode | Type de retour | Description |
|---|---|---|
| getRawResponse() | chaîne | la réponse JSON de l'API |
| estSuccessful() | bouffon | vérifie si la clé status === "success" |
| obtenirCode() | chaîne | renvoie la clé code |
| obtenirMessage() | chaîne | renvoie l'attribut message |
| getData() | tableau | renvoie la clé data |
REMARQUE : Pour les réponses où data sont une chaîne ; il renvoie ce tableau [data: string]
