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 métodos anotados com @RunAsync são despachados internamente para threads próprias sem bloquear a UI.

Arquitetura​

┌─────────────────┐     ┌─────────────────────────────────┐     ┌──────────────┐
│                 │     │            apossdk              │     │              │
│   Aplicativo    │────▶│  PosPinpad + PosPinpadCallback  │────▶│   Pinpad     │
│   UI + Fluxo    │     │  Pinpad, EMV, Cripto, Rede      │     │  Cartão+PIN  │
│                 │     │                                 │     │              │
└─────────────────┘     └─────────────────────────────────┘     └──────────────┘
                                      │
                                      ▼
                              ┌──────────────┐
                              │ 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 e models em sdk.api.model).
  • Distribuição: AAR publicado no GitHub Packages (Fused Library) ou no Maven local. Veja Instalação.

Funcionalidades​

  • Pagamentos com cartão (débito/crédito, à vista e parcelado)
  • Pagamentos PIX (geração de QR Code)
  • Pré-autorização e confirmação (captura) de pré-autorização
  • Estorno (refund/void)
  • Consulta de transações (histórico, pré-autorizações, transações estornáveis)
  • Consulta de limites por operação
  • Impressão de comprovantes (texto, colunas, imagem, QR Code)
  • Tela secundária (apenas OCTA 400)
  • Suporte a chip, tarja e contactless (NFC)
  • Tabelas EMV automáticas e reenvio de transações pendentes

Responsabilidades do Integrador​

  1. Criar a instância via PosPinpad.create(context, callback).
  2. Buscar a personalização do parceiro (getTerminalConfig(slug)).
  3. Registrar/autenticar o terminal (register(...) ou authenticate(...)).
  4. Inicializar o terminal (terminalInitialization(...)), carregando tabelas EMV.
  5. Iniciar operações (createPayment, createPixPayment, startRefundFlow, etc.).
  6. Reagir aos callbacks — incluindo fornecer as coordenadas do teclado PIN quando solicitado por onStartGetPinCoordinates.

Plataformas Suportadas​

  • Android: API 30+ (Android 11 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 — fluxo de registro e inicialização
  3. API PosPinpad — referência completa da API
  4. Callbacks — eventos e notificações
  5. Modelos — estruturas de dados e códigos de erro
  6. Exemplos — exemplos práticos de uso

Fluxo resumido​

1. PosPinpad.create(context, callback)
              ↓
2. getTerminalConfig(slug)            → personalização do parceiro
              ↓
3. register(fields, partnerSlug)      → vincula terminal e retorna merchantId
   (ou authenticate(request))
              ↓
4. terminalInitialization(request)    → carrega tabelas EMV (onTablesLoaded)
              ↓
5. createPayment(...) / createPixPayment(...) / startRefundFlow() / startPreAuthFlow()
              ↓
6. onStartGetCard() → onStartGetPinCoordinates() → onPinEntry() → onTransactionCompleted(result)

Suporte​

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