Pular para o conteúdo principal

SDK - Android

O SDK Android Mobile POS da Tupi (apossdk) permite integrar funcionalidades de pagamento em terminais POS Android da Positivo. O SDK encapsula toda a lógica de comunicação com o pinpad, tabelas EMV, criptografia (PCI), captura de cartão/senha e a integração com o backend (gateway YBY).

Visão Geral​

O SDK expõe duas interfaces principais ao integrador:

  • PosPinpad — interface de entrada para todas as operações: configuração, inicialização, pagamentos, estorno, pré-autorização, PIX, consultas, impressão e tela secundária.
  • PosPinpadCallback — interface implementada pelo app para receber os eventos do fluxo (cartão, PIN, transação, impressão, inputs, erros, etc.).

A maior parte dos métodos de I/O do PosPinpad é suspend (corrotinas) — chame-os de dentro de um CoroutineScope. Os fluxos start* (estorno e pré-autorização) são anotados com @RunAsync: executam em segundo plano e respondem pelos callbacks.

Modos de integração​

O SDK pode ser integrado de duas formas, com o mesmo núcleo:

ModoComo funcionaQuando usar
Biblioteca (esta seção)O seu app embute o SDK, implementa PosPinpadCallback e desenha as telas de pagamentoVocê controla a experiência de pagamento no terminal
App-to-appO seu app aciona o app host da Tupi por Intents e recebe o desfecho. Não embute o SDK nem as bibliotecas do fabricanteVocê quer integrar pagamento sem cuidar de hardware e telas de pagamento

O modo app-to-app tem documentação própria, na seção Integração app-to-app.

Arquitetura​

┌─────────────────┐     ┌─────────────────────────────────┐     ┌──────────────┐
│                 │     │            apossdk              │     │              │
│   Aplicativo    │────▶│  PosPinpad + PosPinpadCallback  │────▶│   Pinpad     │
│   UI + Fluxo    │     │  Pinpad, EMV, Cripto, Rede      │     │  Cartão+PIN  │
│                 │     │                                 │     │              │
└─────────────────┘     └─────────────────────────────────┘     └──────────────┘
                                      │ mTLS
                                      ▼
                              ┌──────────────┐
                              │ Gateway YBY  │
                              │ Admin + PCI  │
                              └──────────────┘

O backend é dividido em dois escopos de endpoint:

  • Admin (não-PCI): autenticação, registro, tabelas EMV, configuração, health check e consulta de transações.
  • Financeiro (PCI): pagamentos, estornos, confirmações, desfazimentos, advice e PIX.

Pacote e distribuição​

  • Package: com.tupifintech.apossdk
  • Superfície pública: com.tupifintech.apossdk.sdk.api (interfaces PosPinpad, PosPinpadCallback, LocalUserManager e models em sdk.api.model), com.tupifintech.apossdk.sdk.model (SdkErrorCode, ErrorMessageProvider) e com.tupifintech.apossdk.sdk.exceptions.
  • Distribuição: AAR Fused Library (SDK + bibliotecas da Positivo), disponibilizado por e-mail. Veja Instalação.

Funcionalidades​

  • Pagamentos com cartão de crédito, débito e voucher (vale-refeição e vale-alimentação), à vista e parcelado (com e sem juros)
  • Pagamentos e estornos PIX (QR Code)
  • Pré-autorização e captura
  • Estorno com cartão, total ou parcial
  • Suporte a chip, tarja e contactless (NFC)
  • Multi-adquirência: o terminal escolhe o adquirente pela bandeira e pelo produto do cartão
  • Tabelas EMV carregadas automaticamente na inicialização
  • Consulta de transações, totalizadores e ciclos (NSU, código de autorização)
  • Consulta de limites por operação e de produtos disponíveis
  • Impressão de comprovantes (texto, colunas, imagem, QR Code)
  • Usuários locais do terminal (Supervisor e Operador)
  • Metadados do app que viajam com a transação até o gateway
  • Tempo de espera do cartão configurável
  • Reenvio automático de confirmações e desfazimentos pendentes
  • Tela secundária (apenas OCTA 400)

Responsabilidades do Integrador​

  1. Criar a instância via PosPinpad.create(context, callback) — uma única por processo.
  2. Ativar o terminal uma vez: buscar a personalização do parceiro (getTerminalConfig(slug)) e registrar (register(...)).
  3. Inicializar o terminal a cada execução do app (terminalInitialization(...)), carregando tabelas EMV.
  4. Iniciar operações (createPayment, createPixPayment, startRefundFlow, etc.).
  5. Reagir aos callbacks — incluindo fornecer as coordenadas do teclado PIN quando solicitado por onStartGetPinCoordinates e responder aos pedidos de entrada do operador (CVV, últimos dígitos, seleção de aplicação).

Plataformas Suportadas​

  • Android: API 26+ (Android 8.0 ou superior)
  • Terminais: Positivo L300, L400 e OCTA 400 (este último com tela secundária)

Documentação​

  1. Instalação — adicione o SDK ao seu projeto
  2. Configuração — instância, certificado, endpoints, tempos, usuários locais e metadados
  3. API PosPinpad — visão geral da interface
  4. Callbacks — eventos e notificações
  5. Modelos — estruturas de dados, códigos de erro e exceções
  6. Exemplos — exemplos práticos de uso

Fluxo resumido​

1. PosPinpad.create(context, callback)
              ↓
2. getTerminalConfig(slug)            → personalização do parceiro              (só na ativação)
              ↓
3. register(fields, partnerSlug)      → vincula terminal e retorna merchantId   (só na ativação)
              ↓
4. terminalInitialization(request)    → carrega tabelas EMV (onTablesLoaded)    (a cada execução)
              ↓
5. createPayment(...) / createPixPayment(...) / startRefundFlow() / startPreAuthFlow()
              ↓
6. onStartGetCard() → onStartGetPinCoordinates() → onPinEntry() → onTransactionCompleted(result)
              ↓
7. result.requiresCardRemoval → removeCard()   (cartão de chip, em qualquer status)

Suporte​

Para dúvidas específicas do SDK, consulte a documentação completa ou entre em contato com o suporte.

Nesta página