Tutorial de Integração do Método de Pagamento eMola com a API de e2Payments
#### Visão Geral
A API de e2Payments permite que programadores acessem diversos recursos e realizem operações como processamento de pagamentos eMola, carteira Visa, MasterCard e outros. Para utilizar a API, você precisará das chaves `client_id` e `client_secret` disponíveis no painel administrativo. A principal característica de e2Payments é a segurança. Todas as transações são realizadas em um ambiente seguro, evitando acessos não autorizados.
Todas as requisições à API de e2Payments seguem a arquitetura REST e são realizadas via HTTP na URL base: `https://e2payments.explicador.co.mz/v1/`. A URL completa varia conforme o recurso desejado. Por exemplo, para buscar o histórico de todos os pagamentos recebidos nas carteiras eMola, o endpoint completo é: `https://e2payments.explicador.co.mz/v1/payments/emola/get/all`.
Nesta documentação, você encontrará todas as informações necessárias para realizar transações em qualquer sistema ou linguagem de programação.
---
### Credenciais da API
Para criar suas credenciais, é necessário estar autenticado com uma conta de email confirmado. A autenticação pode ser feita por uma das plataformas da Explicador. Após o login, você poderá criar suas credenciais no seguinte formato:
```json
{
"client_id": "91fdae03-29a0-496c-9451-fb1e7dd2adffdf",
"client_secret": "T8sHdLfujgjZBp8aAf0Gsfu3kJgDzmNRUGEdN0sdfdsf"
}
```
#### Composição das Credenciais
- **Name**: Nome que atribui às suas credenciais.
- **Redirect URL**: URL do aplicativo onde as credenciais serão usadas.
- **client_id**: Gerado automaticamente, necessário em todas as requisições.
- **client_secret**: Gerado automaticamente, necessário apenas para solicitar o token de autenticação.
---
### Token de Acesso
Para acessar a API de e2Payments, todas as requisições devem incluir um token de acesso. Este token é gerado com as credenciais `client_id` e `client_secret` e deve ser solicitado através de uma requisição POST para o endpoint `/oauth/token`.
#### Exemplo de Geração de Token
```javascript
axios.post('https://e2payments.explicador.co.mz/oauth/token', {
grant_type: 'client_credentials',
client_id: '91fdae03-29a0-496c-9451-fb1e7dd2adffdf',
client_secret: 'T8sHdLfujgjZBp8aAf0Gsfu3kJgDzmNRUGEdN0sdfdsf'
})
.then(function (response) {
storeTokenInBrowser(response.data);
})
.catch(function (err) {
console.log('token error', err);
});
```
#### Resposta com o Token
```json
{
"access_token": "eyJ0iJJ9.eyJWEwLTQ5NmMtOTQ1MS1mYjFlOiJlN...",
"expires_in": 31536000,
"token_type": "Bearer"
}
```
---
### Armazenamento do Token de Acesso
Para evitar solicitar o token de acesso em cada requisição, recomenda-se armazená-lo no navegador. Exemplo de como armazenar o token:
```javascript
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=/";
}
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);
}
```
---
### Composição do Header
Todas as chamadas para a API de e2Payments são do tipo POST. O header deve incluir:
```json
{
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm...",
"Accept": "application/json",
"Content-Type": "application/json"
}
```
---
### Listar Pagamentos
Para recuperar a lista de todos os pagamentos recebidos na sua conta eMola:
```javascript
var ENDPOINT_URL = "https://e2payments.explicador.co.mz/v1/payments/emola/get/all";
var payload = {
"client_id": "91fdae03-29a0-496c-9451-fb1e7dd2adffdf",
};
var header = {
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm...",
"Accept": "application/json",
"Content-Type": "application/json"
};
axios.post(ENDPOINT_URL, payload, {headers: header})
.then(function (response) {
console.log(response.data); // Pagamentos buscados.
})
.catch(function (err) {
console.log('Error buscando pagamentos', err);
});
```
---
### Recuperar Token Armazenado
Método para recuperar o token armazenado no navegador:
```javascript
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;
}
var header = {
"Authorization": getToken(),
"Accept": "application/json",
"Content-Type": "application/json"
};
```
---
### Carteiras
Para realizar transações, você precisará ter uma carteira eMola. É necessário criar uma conta de negócio em uma das instituições financeiras suportadas (MPesa, BIM ou StandardBank) e obter as chaves da API.
#### Listar Carteiras
Para listar todas as carteiras disponíveis na sua conta:
```javascript
var ENDPOINT_URL = "https://e2payments.explicador.co.mz/v1/wallets/emola/get/all";
var payload = {
"client_id": "91fdae03-29a0-496c-9451-fb1e7dd2adffdf",
};
var header = {
"Authorization": getToken(),
"Accept": "application/json",
"Content-Type": "application/json"
};
axios.post(ENDPOINT_URL, payload, {headers: header})
.then(function (response) {
console.log(response.data); // Carteiras listadas.
})
.catch(function (err) {
console.log('Error buscando carteiras', err);
});
```
---
### Transações
#### Tipos de Transação
- **c2b**: Customer to Business - Dinheiro sai da conta do cliente para a conta de negócio.
- **b2c**: Business to Customer - Dinheiro sai da conta do negócio para a conta do cliente.
- **b2b**: Business to Business - Dinheiro sai de uma conta de negócio para outra conta de negócio.
#### Transações c2b
Para realizar uma transação c2b (cliente para negócio) com eMola:
1. **Requisitos**
- `client_id`
- `client_secret`
- ID da carteira
2. **URLs e Endpoints**
- **URL do Servidor**: `https://e2payments.explicador.co.mz`
- **Endpoint**: `/v1/c2b/emola-payment/{wallet_id}`
3. **Composição do Header**
- Veja a sessão "Composição do Header"
4. **Payload**
- Dados enviados na requisição POST:
```javascript
var wallet_id = 123456; // ID da carteira
var ENDPOINT_URL = "https://e2payments.explicador.co.mz/v1/c2b/emola-payment/" + wallet_id;
var payloadC2b = {
"client_id": "91fdae03-29a0-496c-9451-fb1e7dd2adffdf",
"amount": "30", // no intervalo de 1 a 1250000
"phone": "848512345", // 9 dígitos
"reference": "PrimeiroPagamento"
};
var header = {
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiIsIm...", // Veja o exemplo 05
"Accept": "application/json",
"Content-Type": "application/json"
};
axios.post(ENDPOINT_URL, payloadC2b, {headers: header})
.then(function (response) {
console.log(response.data); // Transação realizada com sucesso.
})
.catch(function (err) {
console.log('A transação falhou', err);
});
```
---
### Histórico de Pagamentos
Para listar o histórico de pagamentos realizados pelas suas carteiras:
```javascript
var ENDPOINT_URL = "https://e2payments.explicador.co.mz/v1/payments/emola/get/all";
var payload = {
"client_id": "91fdae
03-29a0-496c-9451-fb1e7dd2adffdf",
};
var header = {
"Authorization": getToken(),
"Accept": "application/json",
"Content-Type": "application/json"
};
axios.post(ENDPOINT_URL, payload, {headers: header})
.then(function (response) {
console.log(response.data); // Lista dos pagamentos.
})
.catch(function (err) {
console.log('Error buscando pagamentos', err);
});
```
---
### Paginação do Histórico de Pagamentos
Para listar o histórico limitado dos pagamentos realizados pelas suas carteiras:
```javascript
var qtdDePagamentos = 10;
var ENDPOINT_URL = "https://e2payments.explicador.co.mz/v1/payments/emola/get/all/paginate/" + qtdDePagamentos;
var payload = {
"client_id": "91fdae03-29a0-496c-9451-fb1e7dd2adffdf",
};
var header = {
"Authorization": getToken(),
"Accept": "application/json",
"Content-Type": "application/json"
};
axios.post(ENDPOINT_URL, payload, {headers: header})
.then(function (response) {
console.log(response.data); // Lista dos pagamentos.
console.log(response.next_page_url); // URL para obter os próximos {qtdDePagamentos} pagamentos.
})
.catch(function (err) {
console.log('Error buscando pagamentos', err);
});
```
---
Com esses passos, você poderá integrar a API de e2Payments ao seu sistema para realizar e gerenciar pagamentos com segurança. Para dúvidas ou mais detalhes, entre em contato com a equipe de suporte do e2Payments ou participe da comunidade no WhatsApp.
