Arquitetura e Pré-Requisitos
Visão geral da arquitetura
A integração entre o aplicativo do parceiro, a SDK e a Nuvende segue um modelo de arquitetura simples e modular.
Cada componente tem uma função clara dentro do terminal POS:
| Componente | Função |
|---|---|
| App do Parceiro | Aplicativo desenvolvido pelo parceiro, responsável pela jornada do usuário (vendas, pedidos, cobranças). |
| App de Pagamentos (SDK) | Aplicativo nativo responsável por processar os pagamentos no terminal. É acionado pelo app do parceiro. |
| Nuvende | Responsável pelo processamento financeiro, autorização e liquidação das transações. |
Fluxo de operação
- O App do Parceiro cria uma solicitação de pagamento (valor e tipo de transação).
- O App de Pagamentos é acionado automaticamente via SDK.
- O cliente realiza o pagamento (inserção do cartão, senha ou Pix).
- A Nuvende processa a transação e retorna o resultado.
- O App do Parceiro recebe o status (aprovado, negado ou cancelado).
💡 Esse modelo garante que o parceiro não precisa lidar diretamente com dados sensíveis ou conexões de adquirência, pois tudo é feito pela PayStore, com a Nuvende atuando como processadora das transações.
Pré-requisitos de desenvolvimento
Antes de iniciar o desenvolvimento do aplicativo, é necessário garantir que todos os pré-requisitos abaixo estejam atendidos:
1. Ambiente de desenvolvimento
- IDE recomendada: Android Studio (versão atual).
- SDK de Pagamentos: Certifique-se de utilizar a versão do SDK compatível com o ambiente padrão dos terminais fornecidos pela Nuvende. Atualmente, os terminais vêm com o
payments.apkversão 2.11.8.33 pré-instalada, sendo recomendado o uso do payments-api-4.1.0.3.aar. Antes de iniciar a integração, valide sempre se está utilizando a versão correta tanto nos testes quanto em produção para evitar incompatibilidades. - Linguagens suportadas: Qualquer linguagem de programação capaz de gerar um pacote final (.apk) compatível com Android pode ser utilizada.
2. Hardware e terminal POS
- É obrigatório utilizar um terminal físico compatível.
- A Nuvende fornecerá o terminal para testes, que deverá ser retornado posteriormente a homologação.
- O uso de emuladores ou smartphones não é suportado.
Terminais homologados: A920 PAX, A910 PAX, N910 NEWLAND, L300 POSITIVO
3. Credenciais e registro
- O parceiro deve possuir:
- Um cadastro ativo na Nuvende.
- Um estabelecimento vinculado à conta.
- Um terminal registrado e configurado para testes.
- As produção (PROD) são fornecidas pela Nuvende após credenciamento e homologação.
- As chaves de desenvolvimento (DEV) para testes são:
APPLICATION_ID="0" SECRET_TOKEN="000000000000000000000000"
4. Aplicativos obrigatórios instalados no terminal
A Nuvende fornece o terminal com um conjunto de aplicativos de sistema previamente instalados no terminal, na seguinte ordem:
| Aplicativo | Função |
|---|---|
platform.apk | Gerencia o terminal, energia e conectividade. |
client.apk | Loja de aplicativos da PayStore (gerencia instalações e atualizações). |
acquirer.apk | Integração com adquirentes (incluindo a Nuvende). |
payments.apk | Realiza as transações de pagamento (cartão, Pix, estorno). |
⚠️ Importante: a ausência ou versão incorreta de qualquer um desses APKs pode impedir a integração com o SDK de pagamentos.
Resumindo
Os terminais devem ter os APKs essenciais instalados (platform, client, acquirer e payments), responsáveis por gerenciar a comunicação com o sistema operacional e o hardware do dispositivo. Por meio da SDK (payments.aar), seu aplicativo (seja desenvolvido em React Native ou Android Nativo) interage com essas APKs para realizar operações de pagamento de forma segura e padronizada.
5. Ambiente
- É necessário que o terminal esteja inicializado e vinculado à conta Nuvende.
- Caso o terminal ainda não esteja ativado, entre em contato com o suporte técnico da Nuvende para validação inicial.
Ambientes disponíveis
| Ambiente | Descrição |
|---|---|
| Sandbox (Homologação) | Utilizado para testes e desenvolvimento. Não gera transações reais. |
| Produção | Ambiente operacional. Requer aprovação e homologação prévia da Nuvende. |
Adicionando a SDK de Integração ao Projeto
Entre em
Após isso, abra o arquivo build.gradle (Module app) e adicione as seguintes dependências em destaque:
implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
implementation 'org.parceler:parceler-api:1.1.12'
annotationProcessor 'org.parceler:parceler:1.1.12'
implementation 'com.google.code.gson:gson:2.8.5'
Pronto! Agora o projeto já está configurado e terá acesso às classes disponíveis na SDK.
Demos
Veja algumas demonstrações de apps:
Próximos passos
Após concluir a configuração do ambiente e garantir que os APKs estão instalados corretamente, você estará pronto para executar seu primeiro pagamento de teste com a Nuvende.