moneywave
1.0.0
Библиотека PHP для использования сервисов API moneywave .
Вы можете просмотреть документацию, чтобы увидеть все, что доступно: https://moneywave-doc.herokuapp.com/
Для начала вам просто нужно установить его через composer :
$ composer require emmanix2002/ moneywave
Это добавит его в ваш composer.json и установит как зависимость проекта.
Все функции и ресурсы, доступные в сервисе moneywave , представлены как Сервисы . Следовательно, чтобы использовать любую из служб, ее сначала необходимо создать.
Все функции и ресурсы API moneywave представлены в этой библиотеке как сервисы.
Точкой входа в эту библиотеку является класс moneywave .
$ moneywave = new moneywave ();
Мы обсудим это позже.
Чтобы использовать библиотеку, вам необходимо получить учетные данные со своей учетной записи moneywave . Они предоставляют вам два ключа:
Ваша учетная запись может находиться в одном из двух состояний: Test или Production . Для каждого из этих состояний вы будете использовать разные клавиши .
Эти ключи требуются классу moneywave (и должны быть защищены — они используются для аутентификации торгового счета); чтобы использовать их с этой библиотекой, вы можете использовать один из двух возможных методов.
При использовании этого метода ключ сохраняется в определенном файле на вашем сервере, а это означает, что значения не запрограммированы жестко в вашем коде. Библиотека ожидает найти файл с именем .env на том же уровне, что и каталог vendor вашего композитора .
.env
vendor/
composer.json
composer.lock
Как видно выше, файл настроек должен находиться на описанном уровне. Содержимое файла должно быть таким же, как и в .env.example например:
# 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"
Эти значения должны быть установлены для использования библиотеки; после этого вы можете просто позвонить:
$ moneywave = new moneywave ();
Второй способ настройки клиента moneywave — передать все настройки в конструктор.
В отличие от первого метода , вам нужно будет где-то хранить ключи и предоставлять их клиенту при его создании.
$ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);
Когда создается экземпляр клиента ( см. конфигурацию), он автоматически запускает службу VerifyMerchant . Эта служба получает access token от службы moneywave , который будет использоваться для авторизации всех остальных запросов, которые вы делаете к API.
Срок действия каждого access token составляет 2 hours . В вашем приложении у вас есть один из двух вариантов:
Session , чтобы использовать его в нескольких запросах. Для первого варианта взгляните на файлы примеров в каталоге examples . Вы увидите что-то вроде этого:
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());
}
Это позволяет использовать тот же access token для другого запроса с того же компьютера.
После создания экземпляра объекта moneywave выполните следующие действия, чтобы использовать службу:
create*Service()send() для созданного объекта службы . Каждая функция и ресурс сопоставлены с сервисом; сопоставления можно легко вывести из имени класса .
В таблице ниже описаны все услуги:
| Имя класса | Сервисный вызов |
|---|---|
| Номер счетаПроверка | CreateAccountNumberValidationService |
| АккаунтКаккаунт | createAccountToAccountService |
| АккаунтToWallet | createAccountToWalletService |
| Перенос счета | CreateAccountTransferService |
| Банки | СоздатьБанкСервис |
| КартаToBankСчет | СоздатьCardToBankAccountService |
| Токенизация карты | createCardTokenizationService |
| КартаToWallet | CreateCardToWalletService |
| КартаПеревод | CreateCardTransferService |
| Выплата | создатьDisburseService |
| DisburseBulk | СоздатьDisburseBulkService |
| ИнтернетБанковское делоToWallet | СоздатьInternetBankingToWalletService |
| QueryCardToAccountTransfer | createQueryCardToAccountTransfer |
| ЗапросВыплата | createQueryDisbursementService |
| Повторить неудачную передачу | createRetryFailedTransferService |
| TotalChargeToCard | СоздатьTotalChargeToCardService |
| Проверка картыПередача | createValidateCardTransferService |
| ValidateTransfer | CreateValidateTransferService |
| VerifyMerchant | создатьVerifyMerchantService |
| КошелекБаланс | СоздатьWalletBalanceService |
У каждой службы есть список свойств, которые необходимо установить для нее, прежде чем ее можно будет отправить в API; если одно или несколько из этих свойств не установлены, вызов send() вызывает исключение ValidationException .
В качестве примера воспользуемся ресурсом Account Number validation API :
Из документации требуются следующие свойства:
| Имя поля | Описание |
|---|---|
| номер счета | номер счета отправителя |
| банковский_код | банковский код счета для решения |
Чтобы использовать библиотеку, мы сделаем что-то вроде этого:
$ moneywave = new moneywave ();
$accountValidation = $ moneywave ->createAccountNumberValidationService();
$accountValidation->account_number = '0690000004';
$accountValidation->bank_code = Banks::ACCESS_BANK;
$response = $accountValidation->send();
Если бы одно из этих полей не было установлено в объекте службы , было бы выдано исключение ValidationException .
Каждое поле, определенное в документации moneywave (для службы), можно установить как свойство созданного объекта службы.
Существуют определенные поля, которые являются специальными и не требуют настройки вами (хотя вы можете их установить); им будет автоматически присвоено требуемое значение библиотекой. Найдите их в списке ниже:
| Поле | Описание |
|---|---|
| APIKey | будет установлен ключ API, используемый для создания экземпляра объекта moneywave . |
| секрет | будет установлен секретный ключ, используемый для объекта moneywave . |
| платеж | по умолчанию установлено 0 |
| получатель | для createCardToWalletService по умолчанию установлено значение wallet . |
| валюта | автоматически устанавливается на Найра Currency::NAIRA |
Помимо специальных полей, существуют также специальные служебные объекты, которые предоставляют больше, чем обычный метод send() .
createCardToBankAccountService() , createCardToWalletService() )Эти услуги трансфера особенные, потому что в большинстве случаев они двуногие . Они включают в себя следующие шаги:
1 Этап передачи 2 Этап валидации
Эти шаги выполняются один за другим; и оба шага должны быть выполнены для завершения передачи.
Есть 2 службы, которые отвечают за этап validation ; они есть:
createValidateCardTransferService() : позволяет подтвердить перевод карты в кошелек или перевод карты на счет, выполненный с помощью дебетовой карты Verve .createValidateTransferService() : позволяет проверить перевод карты в кошелек или карту на учетную запись, выполненный с использованием учетной записи. То есть поле charge_with было установлено в ChargeMethod::ACCOUNT .Итак, когда вы получаете ответ об успехе от API после первого этапа ; вы начинаете этап проверки.
ПРИМЕЧАНИЕ . Для переводов по картам Mastercard и Visa вы получите ключ authurl в успешном ответе API; вам необходимо перенаправить на этот URL-адрес, чтобы плательщик мог подтвердить перевод. В случае успеха или неудачи плательщик будет перенаправлен обратно на URL-адрес, указанный в поле redirecturl запроса на перевод.
Эта услуга предназначена для вывода наличных из вашего кошелька moneywave на несколько банковских счетов. Он имеет специальный метод для добавления отдельных счетов beneficiary .
addRecipient(string $bankCode, string $accountNumber, float $amount, string $reference = null);
Этот метод позволяет поочередно добавлять каждый счет получателя:
$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);
Полный пример см. в файле examples/disburse_bulk.php .
Если все обязательные поля объекта службы (см. службы) установлены, вызов send() вернет объект ответа , который является экземпляром класса moneywave Response .
Продолжая приведенный выше пример проверки учетной записи :
$response = $accountValidation->send();
Успешный ответ JSON будет иметь такую форму:
{
status: "success",
data: {
name: "MICHAEL JACKSON"
}
}
Тогда как ответ об ошибке JSON будет иметь вид:
{
status: "error",
message: "error message description",
code: "error code string; e.g. INVALID_ID",
data: "data string -- this is absent most of the time"
}
Переменная $response представляет несколько функций, которые можно использовать для работы с этими данными:
# 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();
}
ПРИМЕЧАНИЕ . Все ключи в JSON ответе также доступны из объекта ответа как свойства:
if ($response->isSuccessful()) {
$name = $response->getData()['name'];
} else {
$message = $response->message;
$code = $response->code;
}
Еще один пример: ответ сервиса VerifyMerchant выглядит так:
{
status: "success",
token: "" // a valid merchant token
}
Используя ответ, вам нужно будет сделать это:
$response = $verifyService->send();
if ($response->isSuccessful()) {
$token = $response->token;
} else {
# process the error response as you normally would
}
В таблице ниже описаны методы, определенные в объекте moneywave Response :
| Метод | Тип возврата | Описание |
|---|---|---|
| getRawResponse() | нить | ответ JSON от API |
| isSuccessful() | логическое значение | проверяет, есть ли status ключ === "success" |
| получитьКод() | нить | возвращает code ключ |
| получить сообщение() | нить | возвращает атрибут message |
| получить данные() | множество | возвращает ключ data |
ПРИМЕЧАНИЕ . Для ответов, где data представляют собой строку; он возвращает этот массив [data: string]
