moneywave
1.0.0
Uma biblioteca PHP para consumir os serviços da API moneywave .
Você pode conferir a documentação para ver tudo o que está disponível: https://moneywave-doc.herokuapp.com/
Para começar, basta instalá-lo via composer :
$ composer require emmanix2002/ moneywave
Isso irá adicioná-lo ao seu composer.json e instalá-lo como uma dependência do projeto.
Todos os recursos e recursos disponíveis no serviço moneywave são expostos como serviços . Portanto, para usar qualquer um dos serviços, primeiro ele precisa ser criado.
Todos os recursos e recursos da API moneywave são expostos como serviços nesta biblioteca.
O ponto de entrada para esta biblioteca é a classe moneywave .
$ moneywave = new moneywave ();
Discutiremos mais sobre isso mais tarde.
Para usar a biblioteca, você precisa obter suas credenciais de sua conta moneywave . Eles fornecem duas chaves:
Sua conta pode estar em um dos dois estados: Test ou Production . Para cada um desses estados , você usará chaves diferentes.
Essas chaves são exigidas pela classe moneywave (e devem ser protegidas – elas são usadas para autenticar a conta do comerciante); para usá-los com esta biblioteca, você pode usar um dos dois métodos possíveis.
O uso desse método armazena a chave em um arquivo específico em seu servidor, o que significa que os valores não são codificados em seu código. A biblioteca espera encontrar um arquivo chamado .env no mesmo nível do diretório vendor do compositor .
.env
vendor/
composer.json
composer.lock
Como você pode ver acima, o arquivo de configuração deve estar no nível descrito. O conteúdo do arquivo deve ser o mesmo que você encontra em .env.example assim:
# 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"
Esses valores devem ser definidos para usar a biblioteca; feito isso, você pode simplesmente ligar para:
$ moneywave = new moneywave ();
A segunda maneira de configurar o cliente moneywave é passar todas as configurações para o construtor.
Ao contrário do método one , você precisará armazenar as chaves em algum lugar e fornecê-las ao cliente ao instanciá-las.
$ moneywave = new moneywave (null, $apiKey, $secretKey); # this defaults to the STAGING environment
$ moneywave = new moneywave (null, $apiKey, $secretKey, Environment::STAGING);
Quando o cliente é instanciado ( ver configuração), ele inicia automaticamente o serviço VerifyMerchant . Este serviço obtém um access token do serviço moneywave que será usado para autorizar todas as outras solicitações feitas na API.
Cada access token tem uma vida útil de 2 hours . Na sua aplicação, você tem uma de 2 opções:
Session para usá-lo em várias solicitações Para a primeira opção, dê uma olhada nos arquivos de amostra no diretório examples . Você verá algo assim:
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());
}
Isto torna possível utilizar o mesmo access token para outra solicitação da mesma máquina.
Depois de instanciar o objeto moneywave , siga estas etapas para usar um serviço:
create*Service()send() no objeto de serviço criado. Cada recurso e recurso é mapeado para um serviço; os mapeamentos podem ser facilmente inferidos a partir do nome da classe .
A tabela abaixo descreve todos os serviços:
| Nome da classe | Chamada de serviço |
|---|---|
| Validação de número de conta | createAccountNumberValidationService |
| Conta para conta | createAccountToAccountService |
| Conta para carteira | createAccountToWalletService |
| Transferência de conta | createAccountTransferService |
| Bancos | createBanksService |
| Cartão para conta bancária | createCardToBankAccountService |
| CardTokenização | createCardTokenizationService |
| Cartão para carteira | createCardToWalletService |
| Transferência de cartão | createCardTransferService |
| Desembolsar | createDisburseService |
| Desembolsar em massa | createDisburseBulkService |
| InternetBankingToWallet | criarInternetBankingToWalletService |
| QueryCardToAccountTransfer | createQueryCardToAccountTransfer |
| ConsultaDesembolso | createQueryDisbursementService |
| Tentar novamente com falha na transferência | createRetryFailedTransferService |
| TotalChargeToCard | createTotalChargeToCardService |
| ValidateCardTransfer | createValidateCardTransferService |
| ValidarTransferência | createValidateTransferService |
| Verificar comerciante | createVerifyMerchantService |
| Saldo da carteira | criarWalletBalanceService |
Cada serviço possui uma lista de propriedades que devem ser definidas antes de poder ser enviado para a API; se uma ou mais dessas propriedades não estiverem definidas, chamar send() lança uma ValidationException .
Vamos usar o recurso Account Number validation API como exemplo:
Na documentação, as seguintes propriedades são obrigatórias:
| Nome do campo | Descrição |
|---|---|
| número de conta | o número da conta do remetente |
| código_banco | o código do banco da conta para resolver |
Para usar a biblioteca, faremos algo assim:
$ moneywave = new moneywave ();
$accountValidation = $ moneywave ->createAccountNumberValidationService();
$accountValidation->account_number = '0690000004';
$accountValidation->bank_code = Banks::ACCESS_BANK;
$response = $accountValidation->send();
Se um desses campos não fosse definido no objeto de serviço , uma exceção ValidationException teria sido lançada.
Cada campo definido na documentação moneywave (para um serviço) pode ser definido como uma propriedade no objeto de serviço criado.
Existem determinados campos que são especiais e não precisam ser definidos por você (embora você possa optar por defini-los); eles receberão automaticamente o valor exigido pela biblioteca. Encontre-os listados abaixo:
| Campo | Descrição |
|---|---|
| APIKey | isso será definido como a chave API usada para instanciar o objeto moneywave |
| segredo | isso será definido como a chave secreta usada para o objeto moneywave |
| taxa | definido por padrão como 0 |
| destinatário | para createCardToWalletService , isso é definido como wallet por padrão |
| moeda | definido automaticamente para Currency::NAIRA |
Assim como existem campos especiais, também existem alguns objetos de serviço especiais, que apresentam mais do que o método regular: send() .
createCardToBankAccountService() , createCardToWalletService() )Esses serviços de transferência são especiais porque, na maioria das vezes, são bidirecionais . Eles envolvem as seguintes etapas:
1 A etapa de transferência 2 A etapa de validação
Estas etapas funcionam uma após a outra; e ambas as etapas devem ser concluídas para concluir a transferência.
Existem 2 serviços que cuidam da etapa validation ; eles são:
createValidateCardTransferService() : permite validar um cartão para carteira ou transferência de cartão para conta feita com um cartão de débito VervecreateValidateTransferService() : permite validar um cartão para carteira ou transferência de cartão para conta feita com uma conta. Ou seja, o campo charge_with foi definido como ChargeMethod::ACCOUNT .Portanto, quando você receber uma resposta de sucesso da API após a primeira etapa ; você inicia a perna de validação.
NOTA : Para transferências com cartão Mastercard e Visa, você receberá uma chave authurl na resposta da API bem-sucedida; você deve redirecionar para este URL para que o pagador valide a transferência. Após sucesso ou falha, o pagador será redirecionado de volta para a URL definida no campo redirecturl da solicitação de transferência.
Este serviço serve para desembolsar dinheiro de sua carteira moneywave para várias contas bancárias. Possui um método especial para adicionar contas beneficiary individuais.
addRecipient(string $bankCode, string $accountNumber, float $amount, string $reference = null);
Este método permite adicionar cada conta de beneficiário por vez:
$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);
Veja o arquivo examples/disburse_bulk.php para ver o exemplo completo.
Se todos os campos obrigatórios no objeto de serviço (consulte serviços) tiverem sido definidos, a chamada para send() retornará um objeto de resposta que é uma instância da classe moneywave Response .
Continuando com o exemplo de validação de conta acima:
$response = $accountValidation->send();
Um JSON de resposta bem-sucedido terá este formato:
{
status: "success",
data: {
name: "MICHAEL JACKSON"
}
}
Embora uma resposta de falha JSON tenha o formato:
{
status: "error",
message: "error message description",
code: "error code string; e.g. INVALID_ID",
data: "data string -- this is absent most of the time"
}
A variável $response apresenta algumas funções que podem ser utilizadas para trabalhar com esses dados:
# 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 : Todas as chaves dentro do JSON de resposta também podem ser acessadas no objeto de resposta como propriedades:
if ($response->isSuccessful()) {
$name = $response->getData()['name'];
} else {
$message = $response->message;
$code = $response->code;
}
Como outro exemplo, a resposta do serviço VerifyMerchant é semelhante a esta:
{
status: "success",
token: "" // a valid merchant token
}
Usando a resposta, você terá que fazer isso:
$response = $verifyService->send();
if ($response->isSuccessful()) {
$token = $response->token;
} else {
# process the error response as you normally would
}
A tabela abaixo descreve os métodos definidos no objeto moneywave Response :
| Método | Tipo de retorno | Descrição |
|---|---|---|
| getRawResponse() | corda | a resposta JSON da API |
| é bem sucedido() | bool | verifica se a chave status === "success" |
| getCode() | corda | retorna a chave code |
| getMessage() | corda | retorna o atributo message |
| obterDados() | variedade | retorna a chave data |
NOTA : Para respostas onde data são uma string; ele retorna este array [data: string]
