Painel

API e2Payments

A API de e2Payments permite que programadores acessem os diferentes recursos disponíveis e realizem diversas operações como processamento de pagamentos mpesa, pela carteira visa, master card e mais. Tudo o que o programador precisa, é de ter acesso as chaves client_id e client_secret disponíveis no painel administrativo de todos os utilizadores. A principal caracteristica de e2Payments é a segurança. Todas as transações são realizadas num ambiente totalmente seguro, não sendo possível que pessoas não permitidas tenham acesso aos recursos de outros utilizadores.

Todas as requisições realizadas na API de e2Payments baseam-se na arquitectura REST são realizadas via HTTP numa URL especificada. A URL base para todas as requisições é https://e2payments.explicador.co.mz/v1/. A URL completa varia, depende do recurso que se deseja acessar. Por exemplo, para buscar o histórico de todos os pagamentos recebidos nas carteiras Mpesa o endpoint completo é: https://e2payments.explicador.co.mz/v1/payments/mpesa/get/all.

Nesta documentação encontrará toda a informação que precisa para realizar transações em qualquer sistema ou linguagem de programação.

Para poder criar as suas credenciais, você precisará de estar autenticado com uma conta com email confirmado (a confirmação é feita quando você se regista nas nossas plataformas). A autenticação é feita com base numa das plataformas da Explicador, isso significa que se você já tem conta, poderá entrar ou iniciar sessão no e2Payments usando a sua conta de explicador.co.mz.

Para autenticar-se:

Você precisa iniciar sessão na sua conta para ter acesso aos recursos de servidor. Depois de iniciar a sessão, você poderá criar as suas credenciais que terão o seguinte formato:

Exemplo 01 - credenciais da API:

{
"client_id": "91fdae03-29a0-496c-9451-fb1e7dd2adffdf",
"client_secret": "T8sHdLfujgjZBp8aAf0Gsfu3kJgDzmNRUGEdN0sdfdsf"
}

Tendo a sessão iniciada, você pode clicar aqui para criar as suas credenciais da API.

Composição das credenciais:

  • Name - Nome que atribui as suas credenciais para ajudá-lo a diferenciar as diferentes credencias. Recomendamos que identifique pelo aplicativo onde serão usados.
  • Redirect URL - Indique o link do aplicativo onde as credenciais serão usadas. Exemplo: http://localhost:8080,http://exemplo.com. NOTA: Se as credenciais forem usadas num aplicativo ou dominio que não faz parte da lista de Redirect URL, o servidor vai bloquear as requisições.
  • client_id - Gerado automaticamente, precisará dele em todas as requisições.
  • client_secret - Gerado automaticamente, precisará apenas para solicitar o token de autenticação. Recomendamos que passe essa chave somente ao solicitar o token, nas outras requisições, não envie para o servidor, para evitar expor as suas credenciais.

Um token de acesso é uma cadeia de caractéres opaca que identifica um utilizador, aplicativo ou Sistema. Ele pode ser usado pelo aplicativo para enviar requisições a API da e2Payments. Há diversos métodos que podem ser utilizados para obter tokens de acesso, mas nesta documentação, vamos explicar apenas um método principal.

O token inclui informações sobre quando o token expirará e qual aplicativo ou conta de utilizador gerou o token. Devido às verificações de privacidade e segurança, todas as chamadas ou requisições feitas a API de e2Payments precisam incluir um token de acesso.

Se deseja buscar qualquer recurso no servidor, precisará de solicitar um token de acesso para autenticação, todas as requisições que não possuem o token de acesso no Header, são bloqueadas, retornando-se o erro 401.

Para gerar um token de acesso, precisa de enviar uma requisição POST para o endpoint /oauth/token. URL completo: https://e2payments.explicador.co.mz/oauth/token

Em todos os exemplos, estaremos a usar axios para exemplificarmos as requisições.

Note que para poder gerar o seu token de acesso, precisará de client_id e client_secret você pode encontrar as suas credenciais aqui

Exemplo 02 - Geração de token:

Quando a requisição for feita com sucesso, a resposta terá as seguintes caracteristicas:

Response com o token (1):

{
access_token: "eyJ0iJJ9.eyJWEwLTQ5NmMtOTQ1MS1mYjFlOiJlN...",
expires_in: 31536000
token_type: "Bearer"
}

Depois que receber uma response com caracteristicas acima, pode armazená-lo no browser para não precisar de solicitar o token em cada requisição.

Gerar token várias vezes ou em cada requisição, pode comprometer a segurança e o desempenho principalmente se fizer essas chamadas do lado do cliente. Incentivamos a fazer as chamadas do lado do servidor para não expor as suas credenciais.

Em situações em que as requisições são feitas do lado do cliente (Javascript), veja o tópico a seguir.

Se vai fazer chamadas a API de e2Payments de forma contínua, é muito importante armazenar o token de acesso no browser do utilizar (Cookies). Quando o token estiver armazenado no browser, nas próximas requisições não precisará de solicita-lo novamente, poderá recuperar o token e adicionar no Header das suas requisições, isso vai aumentar um pouco de desempenho das suas requisições.

Mas talvez você fique com algumas dúvidas:

  • Guardar o token no browser não deixa o mesmo disponível para qualquer um? O token ficará visível para qualquer um que inspecionar o seu site, mas ninguém poderá fazer chamadas usando o seu token, porque o servidor vai validar o Redirect URL que você definiu quando criou as credenciais
  • Guardei no browser, e se o token expirar? Quando o token inspirar poderá solicitar outro, chamando o mesmo método que usou para gerar o token expirado.

Assim que já sabe a importância de armazenar o Token de acesso no browser, veja a seguir um exemplo de como pode armazená-lo.

Exemplo 03 - Armazenamento do token no browser:

Método que armazena o token no browser.

async function storeTokenInBrowser(responseData) {

    let token = responseData.token_type + ' ' + responseData.access_token;
    let expires = addDaysToToken(10); // validade de 10 dias
    document.cookie = "e2payment_token=" + (token || "")  + expires + "; path=/";

}

Método auxiliar para adicionar dias na data de hoje, assim quando receber 10 ou 30 significará que o token terá validade de 10 ou 30 dias. Quando terminarem os dias especificados o token irá expirar e será removido do navegador, será necessário solicitar-se um novo token de acesso.

async function addDaysToToken(totalDays) {

    Date.prototype.addDays = function(days) {
        var date = new Date(this.valueOf());
        date.setDate(date.getDate() + days);
        return date;
    }

    var date = new Date();

    return date.addDays(totalDays);

}

Todas as chamadas feitas para a API da e2Payments são do tipo POST, nenhuma chamada é feita sendo do tipo GET. O motivo principal disso é para que em cada requisição se envie o client_id para a validação da requisição. Visto que todos os tokens de acesso possuem o escopo padrão de acesso a todos os recursos na conta do respectivo utilizador, padronizamos todos os Headers que devem ser enviados com excepção de quando se solicita o token.

Quais são as caracteristicas principais do Header?

Vamos responder a pergunta pensando no seguinte exemplo:

Imagine que queira recuperar a lista de todos os pagamentos recebidos na sua conta?

Para tal, precisa de saber qual é o endpoint.

  • https://e2payments.explicador.co.mz - Link do servidor
  • /payments/mpesa/get/all - Endpoint
  • https://e2payments.explicador.co.mz/payments/mpesa/get/all - URL completo para ter acesso aos pagamentos

O Header deve ter essas caracteristicas:

{
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm...",
"Accept": "application/json"
"Content-Type": "application/json"
}

A chave obrigatória a ser enviada no Header é a Authorization, ela deve receber o token do tipo Bearer .... Sobre como gerar um token válido veja o Exemplo 02

Já que entende a estrura principal do Header, o exemplo a seguir mostra como recuperar a lista de todos os pagamentos realizados na sua conta.

Exemplo 04 - Composição do Header, para recuperar todos os pagamentos:

Vamos Criar variáveis separadadas para melhor entendermos a lógica:

Assim, essa requisição vai retornar a lista de todos os pagamentos realizados na sua conta:

O exemplo acima, mostra-nos como podemos recuperar todos os pagamentos da API de e2Payments.

Porém, olhando para o exemplo acima, no contexto real, não seria fácil ter a string para compor o token Bearer do Header, principalmente se tivermos de fazer isso manualmente.

Mas se for a lembrar, no Exemplo 03, mostramos como armazenar o token no browser, agora precisamos de saber como recuperar esse token armazenado no browser.

client_id Lembra de como pode ter acesso ao seu client ID? Acessando o painel administrativo. Em todos os exemplos, estaremos utilizando credenciais inválidos. Essas são strings aleatórias, certifique-se de colocar as suas credenciais, senão terá o erro 401.

Exemplo 05 - Recuperar o token armazenado no browser:

Método que recupera o token no browser.

async function getToken() {

    var nameEQ = "e2payment_token=";
    var ca = document.cookie.split(';');
    for(var i=0;i < ca.length;i++) {
    var c = ca[i];
    while (c.charAt(0)==' ') c = c.substring(1,c.length);
    if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length,c.length);
    }
    return null;

}

Assim, o Header teria as seguintes características:

No contexto real na sua aplicação, terá de combinar diferentes métodos para poder ter o efeito que deseja. Por exemplo, você pode verificar se o token existe no browser, se não existir gerar novo token, mas se existir, utilizar o token existe. Faça parte da nossa Comunidade de Whatsapp onde poderá interagir directamente com a nossa equipe para ter mais ideias.

As carteiras no e2Payments, são as mais importantes do que qualquer outra componente, pois são elas que guardam o valor total da sua conta.

Para ter uma carteira, você precisa ter uma conta de negócio no MPesa, BIM ou StandardBank. Estas instituições, vão fornecer para si chaves da API que poderá utilizar para realizar transações por esses meios. Adicionar carteira

No caso de MPesa, você pode criar uma conta no portal desenvolvedor de MPesa, depois poderá ter acesso as credencias da API. Link do portal

Carteiras de e2Payments como funcionam? A Explicador Inc, LDA empresa que desenvolveu essa solução não é um banco. Por esse motivo é muito importante entender correctamente o termo carteira.

No e2Payments, uma carteira serve como instrumento que vai facilitar a gestão do seu dinheiro. Se acontecer algum ataque cibernético nos servidores da Explicador, não se preocupe que o seu dinheiro continuará intacto no seu banco, apenas cerifique-se de não permitir que pessoas não autorizadas tenham acesso a sua conta, senão poderiam realizar transações em seu nome.

Denomina-se transação a uma operação comercial que consiste em trocar um bem ou serviço por uma determinada quantidade de dinheiro.

No e2Payments, definiremos transação como uma operação de troca de dinheiro de uma conta bancária ou MPesa para outra conta. Note que nesta versão 1 de e2Payments, a transação só é feita de uma conta Mpesa para outra conta Mpesa, ou de uma conta bancária para outra conta bancária. Pode ser a sua conta de negócio a receber dinheiro dos seus clientes ou a transferir dinheiro para os seus clientes essa operação vamos chamar de transação.

A plataforma e2Payments, suporta todas as transações disponíveis na API do MPesa, API do BIM e do StandardBank.

Entendendo a logica das transações, precisamos agora de saber quais são os tipos de transações disponíveis na plataforma e2Payments

Tipos de transação

  • c2b: Customer to Business - Quando o dinheiro sai da conta do cliente para a conta de negócio. Exemplo: Quando um cliente compra um produto online, o dinheiro saí da conta do cliente para a conta do negócio a transação é c2b;
  • b2c: Business to Customer - Quando o dinheiro sai da conta do negócio para a conta do cliente. Exemplo: Quando o negócio ou empresa envia dinheiro para o cliente ou funcionário;
  • b2b: Business to Business - Quando o dinheiro sai da conta do negócio para outra conta do negócio. Exemplo: Quando o negócio ou empresa envia dinheiro para outro negócio ou empresa;

NOTA: Considera-se conta de negócio ou Business, a uma conta que possui um contracto com o banco ou Mpesa, e esse contracto não é celebrado entre pessoa singular e o banco, mas sim, uma empresa ou banco. Em outras palavras, será necessário ter uma empresa registada para poder criar uma conta de negócio. Mais informações contacte o seu Banco ou MPesa.

Todas as transações no e2Payments, são relacionadas ás carteiras. O que significa que de certa forma o valor que transfere ou recebe ficará disponível nas suas carteiras. Por isso, antes de realizar qualquer transação, você precisará de criar uma carteira. Criar carteira agora.

As carteiras no e2Payments, são as mais importantes do que qualquer outra componente, pois são elas que guardam o valor total da sua conta.

Para ter uma carteira, você precisa ter uma conta de negócio no MPesa, BIM ou StandardBank. Estas instituições, vão fornecer para si chaves da API que poderá utilizar para realizar transações por esses meios. Adicionar carteira Na sessão anterior explicamos sobre transações e tipos de transações. Nesta sessão, vamos ver na prática sobre como implementar ou integrar c2b para pagamentos online em qualquer linguagem de programação ou tecnologia.

Vamos ver passo a passo. O exemplo a seguir está baseado em Javascript, mas esses passos podem ser seguidos na mesma sequência em qualquer linguagem de programação.

Passo 01 - Cumprir os requisitos necessários

Passo 02 - Ter as URL do servidor e os endpoints

  • SERVER_URL https://e2payments.explicador.co.mz - URL do servidor da API de e2Payments
  • ENDPOINT /v1/c2b/mpesa-payment/{wallet_id} - Endpoint a chamar para realizar pagamento c2b, onde o wallet_id é o id da carteira que deseja utilizar nesta transação, veja o passo anterior.
  • URL Completo https://e2payments.explicador.co.mz/v1/c2b/mpesa-payment/{wallet_id} - URL a utilizar para realizar a transação c2b.

Passo 03 - Composição do Header

Os parámetros que devem fazer parte do Header, são sempre os mesmos. Veja a sessão Composição do Header

Passo 04 - Payload

No caso de MPesa, você pode criar uma conta no portal desenvolvedor de MPesa, depois poderá ter acesso as credencias da API. Link do portal Consideramos payload os dados que você envia para o servidor pelo verbo POST. O valor de reference deve ser a de uma String que corresponde a mensagem MPESA que irá aparecer no pop do cellular do cliente. Esta String não pode conter espaço A seguir exemplo de como deve ser o payload:

O exemplo a seguir mostra como fazer a requisição.

Exemplo 06 - Transação c2b

Carteiras de e2Payments como funcionam? A Explicador Inc, LDA empresa que desenvolveu essa solução não é um banco. Por esse motivo é muito importante entender correctamente o termo carteira.

No e2Payments, uma carteira serve como instrumento que vai facilitar a gestão do seu dinheiro. Se acontecer algum ataque cibernético nos servidores da Explicador, não se preocupe que o seu dinheiro continuará intacto no seu banco, apenas cerifique-se de não permitir que pessoas não autorizadas tenham acesso a sua conta, senão poderiam realizar transações em seu nome.

Vamos Criar variáveis separadadas para melhor entendermos a lógica:

Para a realizar a transação c2b é suficiente passar as variaveis acima no axios da seguinte forma:

NOTA: Se tudo correr bem, o dispositivo que utiliza o número indicado no phone vai receber um popup de Mpesa a solicitar o PIN para confirmar o pagamento do valor indicado no amount.

Para listar todas as carteiras disponíveis na sua conta, é só fazer uma chamada POST para o endpoint: https://e2payments.explicador.co.mz/v1/wallets/mpesa/get/all , indicando apenas o client_id no payload. O Header das requisições é sempre o mesmo.

Para ver detalhes de uma carteira, é só fazer uma chamada POST para o endpoint: https://e2payments.explicador.co.mz/v1/wallets/mpesa/get/{walletId} , indicando apenas o client_id no payload. O walletId é o ID da carteira que deseja ver os seus detalhes.

Para listar histórico dos pagamentos realizados pelas suas carteiras, é só fazer uma chamada POST para o endpoint: https://e2payments.explicador.co.mz/v1/payments/mpesa/get/all , indicando apenas o client_id no payload. O Header das requisições é sempre o mesmo.

Para listar o histórico limitado dos pagamentos realizados pelas suas carteiras, é só fazer uma chamada POST para o endpoint: https://e2payments.explicador.co.mz/v1/payments/mpesa/get/all/paginate/{qtdDePagamentos} , indicando apenas o client_id no payload. O Header das requisições é sempre o mesmo. Esta maneira de carregar os pagamentos é mais eficiente no caso de não querer listar TODOS os pagamentos já feitos na sua carteira. Pois, depois de algum tempo, o número de pagamentos pode chegar a milhares.

Para ler a resposta: