moneywave
1.0.0
Eine PHP-Bibliothek zur Nutzung der moneywave -API-Dienste.
Sie können sich die Dokumentation ansehen, um alles zu sehen, was verfügbar ist: https://moneywave-doc.herokuapp.com/
Um zu beginnen, müssen Sie es lediglich über composer installieren:
$ composer require emmanix2002/ moneywave
Dadurch wird es zu Ihrer composer.json hinzugefügt und als Projektabhängigkeit installiert.
Alle im moneywave -Dienst verfügbaren Funktionen und Ressourcen werden als Dienste bereitgestellt. Um einen der Dienste nutzen zu können, muss er daher zunächst erstellt werden.
Alle Funktionen und Ressourcen der moneywave -API werden als Dienste in dieser Bibliothek bereitgestellt.
Der Einstiegspunkt zu dieser Bibliothek ist die moneywave -Klasse.
$ moneywave = new moneywave ();
Wir werden später mehr darüber besprechen.
Um die Bibliothek nutzen zu können, müssen Sie Ihre Zugangsdaten von Ihrem moneywave -Konto abrufen. Sie stellen Ihnen zwei Schlüssel zur Verfügung:
Ihr Konto kann einen von zwei Status haben: Test oder Production . Für jeden dieser Zustände verwenden Sie unterschiedliche Schlüssel .
Diese Schlüssel werden von der moneywave -Klasse benötigt (und müssen geschützt werden – sie werden zur Authentifizierung des Händlerkontos verwendet); Um sie mit dieser Bibliothek zu verwenden, können Sie eine von zwei möglichen Methoden verwenden.
Mit dieser Methode wird der Schlüssel in einer bestimmten Datei auf Ihrem Server gespeichert, was bedeutet, dass die Werte nicht fest in Ihrem Code codiert sind. Die Bibliothek erwartet, eine Datei namens .env auf derselben Ebene wie Ihr Composer- vendor zu finden.
.env
vendor/
composer.json
composer.lock
Wie Sie oben sehen können, sollte sich die Einstellungsdatei auf der beschriebenen Ebene befinden. Der Inhalt der Datei sollte derselbe sein, den Sie im .env.example finden, etwa so:
# 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"
Diese Werte müssen festgelegt werden, um die Bibliothek verwenden zu können. Wenn dies erledigt ist, können Sie einfach Folgendes aufrufen:
$ moneywave = new moneywave ();
Die zweite Möglichkeit, den moneywave -Client zu konfigurieren, besteht darin, alle Einstellungen an den Konstruktor zu übergeben.
Im Gegensatz zur ersten Methode müssen Sie die Schlüssel irgendwo speichern und sie dem Client bereitstellen, wenn Sie sie instanziieren.
$ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);
Wenn der Client instanziiert wird ( siehe Konfiguration), startet er automatisch den VerifyMerchant -Dienst. Dieser Dienst erhält vom moneywave -Dienst ein access token , das zur Autorisierung jeder anderen Anfrage verwendet wird, die Sie an die API stellen.
Jedes access token hat eine Lebensdauer von 2 hours . Bei Ihrer Bewerbung haben Sie eine von 2 Möglichkeiten:
Session um es für mehrere Anfragen zu verwenden Schauen Sie sich für die erste Option die Beispieldateien im examples an. Sie werden etwa Folgendes sehen:
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());
}
Dadurch ist es möglich, dasselbe access token für eine andere Anfrage von derselben Maschine zu verwenden.
Nachdem Sie das moneywave -Objekt instanziiert haben, führen Sie die folgenden Schritte aus, um einen Dienst zu nutzen:
create*Service() -Methoden aufrufensend() Methode für das erstellte Serviceobjekt auf. Jede Funktion und Ressource ist einem Dienst zugeordnet. Die Zuordnungen können leicht aus dem Klassennamen abgeleitet werden.
In der folgenden Tabelle werden alle Dienste beschrieben:
| Klassenname | Serviceanruf |
|---|---|
| AccountNumberValidation | createAccountNumberValidationService |
| AccountToAccount | createAccountToAccountService |
| AccountToWallet | createAccountToWalletService |
| Kontoübertragung | createAccountTransferService |
| Banken | createBanksService |
| CardToBankAccount | createCardToBankAccountService |
| CardTokenization | createCardTokenizationService |
| CardToWallet | createCardToWalletService |
| CardTransfer | createCardTransferService |
| Auszahlen | createDisburseService |
| DisburseBulk | createDisburseBulkService |
| InternetBankingToWallet | createInternetBankingToWalletService |
| QueryCardToAccountTransfer | createQueryCardToAccountTransfer |
| AbfrageAuszahlung | createQueryDisbursementService |
| RetryFailedTransfer | createRetryFailedTransferService |
| TotalChargeToCard | createTotalChargeToCardService |
| ValidateCardTransfer | createValidateCardTransferService |
| ValidateTransfer | createValidateTransferService |
| VerifyMerchant | createVerifyMerchantService |
| WalletBalance | createWalletBalanceService |
Jeder Dienst verfügt über eine Liste von Eigenschaften, die festgelegt werden müssen, bevor er an die API gesendet werden kann. Wenn eine oder mehrere dieser Eigenschaften nicht festgelegt sind, löst der Aufruf von send() eine ValidationException aus.
Nehmen wir als Beispiel die API- Ressource Account Number validation API :
Aus der Dokumentation sind folgende Eigenschaften erforderlich:
| Feldname | Beschreibung |
|---|---|
| Kontonummer | die Kontonummer des Absenders |
| Bankleitzahl | die Bankleitzahl des Kontos, das aufgelöst werden soll |
Um die Bibliothek zu nutzen, machen wir etwa Folgendes:
$ moneywave = new moneywave ();
$accountValidation = $ moneywave ->createAccountNumberValidationService();
$accountValidation->account_number = '0690000004';
$accountValidation->bank_code = Banks::ACCESS_BANK;
$response = $accountValidation->send();
Wenn eines dieser Felder nicht für das Dienstobjekt festgelegt wäre, wäre eine ValidationException Ausnahme ausgelöst worden.
Jedes in der moneywave -Dokumentation definierte Feld (für einen Dienst) kann als Eigenschaft für das erstellte Dienstobjekt festgelegt werden.
Es gibt bestimmte Felder, die speziell sind und nicht von Ihnen festgelegt werden müssen (Sie können sie jedoch festlegen). Sie erhalten von der Bibliothek automatisch den erforderlichen Wert. Finden Sie sie unten aufgeführt:
| Feld | Beschreibung |
|---|---|
| apiKey | Dies wird auf den API-Schlüssel gesetzt, der zum Instanziieren des moneywave Objekts verwendet wird |
| Geheimnis | Dies wird auf den geheimen Schlüssel gesetzt, der für das moneywave -Objekt verwendet wird |
| Gebühr | standardmäßig auf 0 gesetzt |
| Empfänger | Für den createCardToWalletService ist dieser standardmäßig auf wallet eingestellt |
| Währung | automatisch auf Naira Currency::NAIRA gesetzt |
So wie es spezielle Felder gibt, gibt es auch einige spezielle Serviceobjekte, die mehr als die reguläre Methode send() darstellen.
createCardToBankAccountService() , createCardToWalletService() )Das Besondere an diesen Transferdiensten ist, dass es sich in den meisten Fällen um zweibeinige Transfers handelt. Sie umfassen die folgenden Schritte:
1 Die Übertragungsstrecke 2 Die Validierungsstrecke
Diese Schritte funktionieren nacheinander; und beide Schritte müssen abgeschlossen sein, um die Übertragung abzuschließen .
Es gibt zwei Dienste, die sich um die validation kümmern. sie sind:
createValidateCardTransferService() : ermöglicht Ihnen die Validierung einer Karte-zu-Wallet- oder Karte-zu-Konto- Übertragung, die mit einer Verve- Debitkarte durchgeführt wurdecreateValidateTransferService() : Ermöglicht die Validierung einer Karte-zu-Wallet- oder Karte-zu-Konto- Übertragung, die mit einem Konto durchgeführt wurde. Das heißt, das Feld „charge_with“ wurde auf ChargeMethod::ACCOUNT gesetzt.Wenn Sie also nach der ersten Etappe eine Erfolgsantwort von der API erhalten; Sie starten die Validierungsstrecke.
HINWEIS : Bei Mastercard- und Visa-Kartenübertragungen erhalten Sie in der erfolgreichen API-Antwort einen authurl . Sie müssen zu dieser URL weiterleiten , damit der Zahler die Überweisung bestätigen kann. Nach Erfolg oder Misserfolg wird der Zahler zurück zu der URL weitergeleitet, die im redirecturl Feld der Überweisungsanfrage festgelegt ist.
Mit diesem Service können Sie Bargeld von Ihrem moneywave -Wallet auf mehrere Bankkonten auszahlen. Es verfügt über eine spezielle Methode zum Hinzufügen der einzelnen beneficiary .
addRecipient(string $bankCode, string $accountNumber, float $amount, string $reference = null);
Mit dieser Methode können Sie nacheinander jedes Begünstigtenkonto hinzufügen:
$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);
Das vollständige Beispiel finden Sie in der Datei examples/disburse_bulk.php .
Wenn alle erforderlichen Felder des Dienstobjekts (siehe Dienste) festgelegt wurden, gibt der Aufruf von send() ein Antwortobjekt zurück, das eine Instanz der moneywave Response Klasse ist.
Fahren Sie mit dem obigen Beispiel zur Kontovalidierung fort:
$response = $accountValidation->send();
Eine erfolgreiche JSON Antwort sieht folgendermaßen aus:
{
status: "success",
data: {
name: "MICHAEL JACKSON"
}
}
Während eine Fehlerantwort im JSON Format wie folgt aussieht:
{
status: "error",
message: "error message description",
code: "error code string; e.g. INVALID_ID",
data: "data string -- this is absent most of the time"
}
Die Variable $response stellt einige Funktionen bereit, die zum Arbeiten mit diesen Daten verwendet werden können:
# 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();
}
HINWEIS : Auf alle Schlüssel im Antwort JSON kann auch über das Antwortobjekt als Eigenschaften zugegriffen werden:
if ($response->isSuccessful()) {
$name = $response->getData()['name'];
} else {
$message = $response->message;
$code = $response->code;
}
Als weiteres Beispiel sieht die Antwort des VerifyMerchant -Dienstes so aus:
{
status: "success",
token: "" // a valid merchant token
}
Mit der Antwort müssen Sie Folgendes tun:
$response = $verifyService->send();
if ($response->isSuccessful()) {
$token = $response->token;
} else {
# process the error response as you normally would
}
In der folgenden Tabelle werden die für das moneywave Response Objekt definierten Methoden beschrieben:
| Verfahren | Rückgabetyp | Beschreibung |
|---|---|---|
| getRawResponse() | Zeichenfolge | die JSON-Antwort von der API |
| isSuccessful() | bool | prüft, ob der status === "success" ist |
| getCode() | Zeichenfolge | gibt den code zurück |
| getMessage() | Zeichenfolge | gibt das message zurück |
| getData() | Array | gibt den data zurück |
HINWEIS : Für Antworten, bei denen es sich data um eine Zeichenfolge handelt; es gibt dieses Array zurück [data: string]
