moneywave
1.0.0
Una biblioteca PHP para consumir los servicios API moneywave .
Puede consultar la documentación para ver todo lo que está disponible: https://moneywave-doc.herokuapp.com/
Para comenzar, simplemente necesitas instalarlo a través de composer :
$ composer require emmanix2002/ moneywave
Esto lo agregará a su composer.json y lo instalará como una dependencia del proyecto.
Todas las Funciones y Recursos disponibles en el servicio moneywave se exponen como Servicios . Por lo tanto, para utilizar cualquiera de los servicios, primero es necesario crearlo.
Todas las funciones y recursos de la API moneywave se exponen como servicios en esta biblioteca.
El punto de entrada a esta biblioteca es la clase moneywave .
$ moneywave = new moneywave ();
Hablaremos más sobre esto más adelante.
Para utilizar la biblioteca, debe obtener sus credenciales de su cuenta moneywave . Te proporcionan dos claves:
Su cuenta puede estar en uno de dos estados: Test o Production . Para cada uno de estos estados , utilizará claves diferentes.
Estas claves son requeridas por la clase moneywave (y deben estar protegidas: se utilizan para autenticar la cuenta del comerciante); para usarlos con esta biblioteca, puede usar uno de dos métodos posibles.
El uso de este método almacena la clave en un archivo específico en su servidor, lo que significa que los valores no están codificados en su código. La biblioteca espera encontrar un archivo llamado .env en el mismo nivel que el directorio vendor de su compositor .
.env
vendor/
composer.json
composer.lock
Como puede ver arriba, el archivo de configuración debe estar en el nivel descrito. El contenido del archivo debe ser el mismo que puede encontrar en .env.example así:
# 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"
Esos valores deben establecerse para utilizar la biblioteca; Una vez hecho esto, simplemente puedes llamar:
$ moneywave = new moneywave ();
La segunda forma de configurar el cliente moneywave es pasar todas las configuraciones al constructor.
A diferencia del método uno , deberá almacenar las claves en algún lugar y proporcionárselas al cliente cuando lo cree.
$ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);
Cuando se crea una instancia del cliente ( ver configuración), automáticamente inicia el servicio VerifyMerchant . Este servicio obtiene un access token del servicio moneywave que se utilizará para autorizar cualquier otra solicitud que realice contra la API.
Cada access token tiene una vida útil de 2 hours . En su solicitud, tiene una de 2 opciones:
Session para usarlo en múltiples solicitudes Para la primera opción, eche un vistazo a los archivos de muestra en el directorio examples . Verás algo como esto:
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());
}
Esto hace posible utilizar el mismo access token para otra solicitud desde la misma máquina.
Después de crear una instancia del objeto moneywave , siga estos pasos para utilizar un servicio:
create*Service()send() en el objeto de servicio creado. Cada característica y recurso se asigna a un servicio; las asignaciones se pueden inferir fácilmente a partir del nombre de la clase .
La siguiente tabla describe todos los servicios:
| Nombre de clase | Llamada de servicio |
|---|---|
| Validación del número de cuenta | crear servicio de validación de número de cuenta |
| CuentaACuenta | crearAccountToAccountService |
| CuentaACartera | crearAccountToWalletService |
| Transferencia de cuenta | crearAccountTransferService |
| Bancos | crearBancosServicio |
| Tarjeta A Cuenta Bancaria | crearCardToBankAccountService |
| Tokenización de tarjetas | crearCardTokenizationService |
| Tarjeta a billetera | crearCardToWalletService |
| Transferencia de tarjeta | crearCardTransferService |
| Desembolsar | crearDisburseService |
| Desembolsar a granel | crearDisburseBulkService |
| Banca por Internet a Wallet | crearInternetBankingToWalletService |
| QueryCardToAccountTransfer | crearQueryCardToAccountTransfer |
| ConsultaDesembolso | crearQueryDisbursementService |
| Reintentar transferencia fallida | crearRetryFailedTransferService |
| Cargo total a la tarjeta | crearTotalChargeToCardService |
| ValidarTransferenciaDeTarjeta | crearValidateCardTransferService |
| ValidarTransferir | crearValidateTransferService |
| VerificarComerciante | crearVerifyMerchantService |
| Saldo de billetera | crearWalletBalanceService |
Cada servicio tiene una lista de propiedades que se deben configurar antes de poder enviarlo a la API; Si una o más de estas propiedades no están configuradas, llamar send() genera una ValidationException .
Usemos el recurso Account Number validation API como ejemplo:
De la documentación, se requieren las siguientes propiedades:
| Nombre del campo | Descripción |
|---|---|
| número_cuenta | el número de cuenta del remitente |
| código_banco | el código bancario de la cuenta a resolver |
Para usar la biblioteca, haremos algo como esto:
$ moneywave = new moneywave ();
$accountValidation = $ moneywave ->createAccountNumberValidationService();
$accountValidation->account_number = '0690000004';
$accountValidation->bank_code = Banks::ACCESS_BANK;
$response = $accountValidation->send();
Si uno de esos campos no estuviera configurado en el objeto de servicio , se habría generado una excepción ValidationException .
Cada campo definido dentro de la documentación moneywave (para un servicio) se puede establecer como una propiedad en el objeto de servicio creado.
Hay ciertos campos que son especiales y no es necesario que usted los configure (aunque puede elegir configurarlos); La biblioteca les dará automáticamente el valor requerido. Encuéntrelos a continuación:
| Campo | Descripción |
|---|---|
| apiKey | esto se establecerá en la clave API utilizada para crear una instancia del objeto moneywave |
| secreto | esto se establecerá en la clave secreta utilizada para el objeto moneywave |
| tarifa | establecido por defecto en 0 |
| beneficiario | para createCardToWalletService , esto está configurado en wallet de forma predeterminada |
| divisa | se establece automáticamente en Naira Currency::NAIRA |
Así como hay campos especiales, también hay algunos objetos de servicio especiales que presentan más que el método normal: send() .
createCardToBankAccountService() , createCardToWalletService() )Estos servicios de traslado son especiales porque, la mayoría de las veces, son de 2 patas . Implican los siguientes pasos:
1 El tramo de transferencia 2 El tramo de validación
Estos pasos funcionan uno tras otro; y ambos pasos deben completarse para completar la transferencia.
Hay 2 servicios que se encargan del tramo validation ; ellos son:
createValidateCardTransferService() : le permite validar una transferencia de tarjeta a billetera o de tarjeta a cuenta realizada con una tarjeta de débito VervecreateValidateTransferService() : le permite validar una transferencia de tarjeta a billetera o de tarjeta a cuenta realizada con una cuenta. Es decir, el campo charge_with se configuró en ChargeMethod::ACCOUNT .Entonces, cuando reciba una respuesta de éxito de la API después del primer tramo ; comienzas el tramo de validación.
NOTA : Para transferencias con tarjetas Mastercard y Visa, recibirá una clave authurl en la respuesta API exitosa; debe redirigir a esta URL para que el pagador valide la transferencia. Después del éxito o el fracaso, el pagador será redirigido a la URL establecida en el campo redirecturl de la solicitud de transferencia.
Este servicio sirve para desembolsar efectivo desde su billetera moneywave a múltiples cuentas bancarias. Tiene un método especial para agregar las cuentas beneficiary individuales.
addRecipient(string $bankCode, string $accountNumber, float $amount, string $reference = null);
Este método le permite agregar cada cuenta de beneficiario por turno:
$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);
Mire el archivo examples/disburse_bulk.php para ver el ejemplo completo.
Si se han configurado todos los campos obligatorios en el objeto de servicio (ver servicios), la llamada a send() devolverá un objeto de respuesta que es una instancia de la clase moneywave Response .
Continuando con el ejemplo de Validación de cuenta anterior:
$response = $accountValidation->send();
Un JSON de respuesta exitoso tendrá este formato:
{
status: "success",
data: {
name: "MICHAEL JACKSON"
}
}
Mientras que una respuesta de error, JSON tendrá la forma:
{
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 presenta algunas funciones que se pueden utilizar para trabajar con estos datos:
# 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();
}
NOTA : También se puede acceder a todas las claves dentro del JSON de respuesta desde el objeto de respuesta como propiedades:
if ($response->isSuccessful()) {
$name = $response->getData()['name'];
} else {
$message = $response->message;
$code = $response->code;
}
Como otro ejemplo, la respuesta del servicio VerifyMerchant se ve así:
{
status: "success",
token: "" // a valid merchant token
}
Usando la respuesta, tendrás que hacer esto:
$response = $verifyService->send();
if ($response->isSuccessful()) {
$token = $response->token;
} else {
# process the error response as you normally would
}
La siguiente tabla describe los métodos definidos en el objeto moneywave Response :
| Método | Tipo de devolución | Descripción |
|---|---|---|
| obtenerRespuestaRaw() | cadena | la respuesta JSON de la API |
| es exitoso() | booleano | comprueba si la clave status === "success" |
| obtener código() | cadena | devuelve la clave code |
| obtener mensaje() | cadena | devuelve el atributo message |
| obtener datos() | formación | devuelve la clave data |
NOTA : Para respuestas donde data son una cadena; devuelve esta matriz [data: string]
