SDK Barte para maquininhas POS

Visão Geral

O Barte SDK permite que aplicativos Android realizem transações em terminais POS de forma simples e segura.

Com ele, é possível iniciar, confirmar, listar, estornar e reimprimir pagamentos, além de acessar informações do terminal e configurar preferências de integração.

---

1. Instalação do SDK

1.1 Dependências necessárias

Antes de utilizar o SDK, é necessário seguir com a instalação dependências necessárias para que o projeto funcione:

implementation("com.jakewharton.threetenabp:threetenabp:1.0.5")

1.2 Instalação do SDK

A integração é feita via .aar disponibilizado pela Barte. Inclua o arquivo barte_payment_pos-<versão>.aar dentro da pasta libs/ do seu módulo Android.

implementation(files("libs/barte_payment_pos-1.0.0.0.aar"))

Atenção:

• Substitua 1.0.0.0 pela versão correspondente do SDK.

---

2. Inicialização do SDK

Antes de usar qualquer funcionalidade, é necessário inicializar o SDK.

Nome	Tipo	Obrigatório	Descrição
context	Context	✅	Use applicationContext.
applicationId	String	✅	ID da aplicação fornecido pela Phoebus.
secretToken	String	✅	Token secreto associado ao applicationId.
softwareVersion	String	✅	Versão do seu app para identificação e auditoria.

Inicializa o SDK. Deve ser chamado uma única vez no ciclo de vida do app.

Para recuperar a instância em qualquer parte do app:

---

3. Utilização do SDK

3.1 Configurações

Definição de tema de aplicação

Nome	Tipo	Obrigatório	Descrição
theme	String	✅	Nome do tema a ser aplicado. Veja em BarteTheme
callback	(BarteResult<Unit>) -> Unit	✅	Função de retorno que será chamada com o resultado da operação.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(Unit)	Indica que a configuração de tema do aplicativo foi aplicada com sucesso.
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

Definição de aplicação principal

Descrição

Define o pacote principal do app que controlará a experincia no terminal.

Nome	Tipo	Obrigatório	Descrição
packageName	String	✅	Nome do pacote Android do seu app.
callback	(BarteResult<Unit>) -> Unit	✅	Retorno assíncrono do resultado.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(Unit)	Indica que a configuração do aplicativo principal foi aplicada com sucesso.
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

Verificar tema da aplicação

Descrição

Obtém o tema atualmente configurado.

Nome	Tipo	Obrigatório	Descrição
callback	(BarteResult<String>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(String)	Nome do tema configurado no SDK (ex.: "dark", "light", "default").
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

---

3.2 Terminal

Verificar dados de terminal

Descrição

Retorna os dados do terminal como TerminalInfo .

Nome	Tipo	Obrigatório	Descrição
callback	(BarteResult<TerminalInfo>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(TerminalInfo)	Objeto TerminalInfo contendo todos os dados do terminal (merchantId, terminalId, endereço, moeda, etc.).
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

---

3.3 Pagamentos - Escrita

Iniciar uma transação

Descrição

Inicia uma transação com o status pendente, essa transação poderá ser confirmada com o método confirmTransaction .

Nome	Tipo	Obrigatório	Descrição
req	TransactionRequest	✅	TransactionRequest
callback	(BarteResult<BartePayment>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(BartePayment)	Objeto BartePayment com os dados completos da transação confirmada (valor, status, cartão, adquirente etc.).
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

Confirmar uma transação

Descrição

Confirma uma transação gerada como pendente.

Nome	Tipo	Obrigatório	Descrição
paymentId	String	✅	Id da transação
callback	(BarteResult<Unit>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(BartePayment)	Objeto BartePayment com os dados completos da transação confirmada (valor, status, cartão, adquirente etc.).
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

Iniciar uma transação ponta a ponta

Descrição

Inicia uma transação de ponta a ponta, essa transação não necessitará de uma confirmação após a tela de impressão de comprovantes.

Nome	Tipo	Obrigatório	Descrição
req	TransactionRequest	✅	Ver Tabela: TransactionRequest
callback	(BarteResult<Unit>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(Unit)	Indica que a transação foi iniciada e confirmada com sucesso. Não há payload adicional.
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

Reimprimir comprovante de pagamento

Descrição

Método responsável por realizar a reimpressão de comprovante de pagamento. Ao executar a chamada do método, o mesmo abrirá a tela de reimpressão de comprovante.

Nome	Tipo	Obrigatório	Descrição
paymentId	String	✅	ID do pagamento a reimprimir.
printMerchantReceipt	Boolean	—	Imprime a via do estabelecimento.
printCustomerReceipt	Boolean	—	Imprime a via do cliente.
previewMerchantReceipt	Boolean?	—	Pré-visualiza a via do estabelecimento (se suportado).
previewCustomerReceipt	Boolean?	—	Pré-visualiza a via do cliente (se suportado).
callback	(BarteResult<Unit>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(Unit)	Indica que a reimpressão ou pré-visualização dos comprovantes foi realizada com sucesso.
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

Estornar pagamento

Descrição

Método responsável pela realização de estorno de uma transação. Será necessário disponibilizar o paymentId da transação para que o estorno da transação possa ser realizado.

Nome	Tipo	Obrigatório	Descrição
paymentId	String	✅	ID do pagamento a ser estornado.
appTransactionId	String	✅	ID interno da sua ordem/pedido.
value	BigDecimal	✅	Valor do estorno.
printMerchantReceipt	Boolean	—	Imprimir via do estabelecimento.
printCustomerReceipt	Boolean	—	Imprimir via do cliente.
previewMerchantReceipt	Boolean	—	Pré-visualização via estabelecimento (se suportado).
previewCustomerReceipt	Boolean	—	Pré-visualização via cliente (se suportado).
callback	(BarteResult<Unit>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(Unit)	Indica que o estorno foi solicitado/executado com sucesso.
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

O estorno é feito mediante aproximação ou inserção do cartão utilizado no pagamento original

Cancelar estorno de pagamento

Descrição

Método responsável pelo cancelamento do estorno de uma transação

Nome	Tipo	Obrigatório	Descrição
paymentId	String	✅	ID do pagamento do estorno a ser cancelado.
callback	(BarteResult<Unit>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(Unit)	—
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

3.4 Pagamentos - Leitura

Listar pagamentos por filtro

Descrição

Método responsável pela consulta dos pagamentos executados com filtragem.

Nome	Tipo	Obrigatório	Descrição
filter	ListPaymentsRequest	✅	Objeto de filtro. Ver ListPaymentsRequest
callback	(BarteResult<List<BartePayment>>) -> Unit	✅	Retorno assíncrono.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(List<BartePayment>)	Cada item da lista é um objeto BartePayment com todos os detalhes da transação (valor, status, cartão, adquirente etc.).
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

Listar pagamentos pendentes

Descrição

Método responsável pela consulta dos pagamentos pendentes com filtragem.

Nome	Tipo	Obrigatório	Descrição
callback	(BarteResult<List<BartePayment>>) -> Unit	✅	Retorno assíncrono com a lista de pagamentos.

Tabela de Retorno (callback)

Caso	Tipo/Conteúdo	Campos
Sucesso	BarteResult.Success(List<BartePayment>)	Cada item da lista é um objeto BartePayment. Representa os pagamentos com status = PENDING, dentro da janela padrão (últimas 24h).
Erro	BarteResult.Error	message: String? • sdkCode: String? • acquirerCode: String? • cause: Throwable?

---

Informações complementares de implementação

1. Retornos por método (BartePaymentService)

Todos os métodos retornam via callback um BarteResult<T>:

• Success(data) — operação concluída; data é o payload abaixo
• Error(sdkCode, acquirerCode, message, cause) — falha; campos de erro abaixo

1.1 Visão geral dos retornos

Método	Success (tipo)	Error (sem alterações)
setMainApp(packageName)	Unit	sdkCode, acquirerCode, message, cause
getMainApp()	String (packageName)	idem
setTheme(theme)	Unit	idem
getTheme()	String (themeName)	idem
getTerminalInfo()	TerminalInfo	idem
startTransaction(req)	BartePayment	idem
startTransactionEndToEnd(req)	Unit	idem
confirmTransaction(paymentId)	Unit	idem
rePrintPayment(…)	Unit	idem
reversePayment(…)	Unit	idem
cancelReversePayment(paymentId)	Unit	idem
listPayments(filter)	List<BartePayment>	idem
listPendingPayments()	List<BartePayment>	idem

Estrutura do Error

Campo	Tipo	Descrição
sdkCode	String?	Código de erro padronizado do SDK.
acquirerCode	String?	Código específico da adquirente.
message	String?	Mensagem de erro legível.
cause	Throwable?	Exceção original para logs/diagnóstico.

Objetos (esquemas)

TerminalInfo

Retorno de: getTerminalInfo()

Campo	Tipo	Obrigatório	Descrição
merchantId	String	✅	Identificador do estabelecimento.
merchantName	String	✅	Razão social do estabelecimento.
merchantCommercialName	String	✅	Nome fantasia.
terminalId	String	✅	Identificador do terminal (TID).
nationalId	String	✅	Documento nacional (ex.: CNPJ).
postalCode	String	✅	CEP.
street	String	✅	Logradouro.
city	String	✅	Cidade.
state	String	✅	Estado (nome completo).
stateAbbreviation	String	✅	UF (ex.: “SP”).
country	String	✅	País.
complement	String	✅	Complemento do endereço.
neighbourhood	String	✅	Bairro.
addressNumber	String	✅	Número.
merchantWebsite	String	✅	Website do estabelecimento.
merchantEmail	String	✅	E-mail de contato.
merchantPhone	String	✅	Telefone de contato.
merchantCategoryCode	String	✅	MCC (Merchant Category Code).
merchantNationalType	String	✅	Tipo nacional (ex.: matriz/filial).
subAcquirerId	String	✅	Identificador do subadquirente (se aplicável).
terminalCurrencyCode	String	✅	Código de moeda numérico (ISO-4217 numérico).
terminalCurrencyIso4217	String	✅	Código de moeda alfabético (ISO-4217 alfabético).

Observação: Se no seu modelo real alguns campos podem ser nulos, ajuste a coluna “Obrigatório” conforme a implementação.

BarteTheme

Descrição: opções de tema disponíveis no SDK. Usado em: setTheme(...), getTheme().

Enum constante	themeName
RED	RedTheme
PINK	PinkTheme
PURPLE	PurpleTheme
DEEP_PURPLE	DeepPurpleTheme
INDIGO	IndigoTheme
BLUE	BlueTheme
LIGHT_BLUE	LightBlueTheme
CYAN	CyanTheme
TEAL	TealTheme
GREEN	GreenTheme
LIGHT_GREEN	LightGreenTheme
LIME	LimeTheme
YELLOW	YellowTheme
AMBER	AmberTheme
ORANGE	OrangeTheme
DEEP_ORANGE	DeepOrangeTheme
BROWN	BrownTheme
GREY	GreyTheme
BLUE_GREY	BlueGreyTheme

BartePayment

Retorno de: startTransaction, listPayments, listPendingPayments (estrutura consolidada a partir das mapeações enviadas)

Campo	Tipo	Obrigatório	Descrição
value	BigDecimal	✅	Valor da transação.
paymentType	BartePaymentType	✅	Tipo (ex.: CREDIT, DEBIT).
installments	Int?	—	Número de parcelas (se aplicável).
acquirer	String	✅	Nome/ID da adquirente.
paymentId	String	✅	ID do pagamento.
card	BarteCard?	—	Dados do cartão mascarados (marca, BIN, final).
captureType	BarteCaptureType	✅	Modo de captura (ex.: CHIP_CONTACTLESS).
paymentStatus	BartePaymentStatus	✅	Status (ex.: APPROVED, PENDING).
paymentDate	Date	✅	Data/hora do pagamento.
acquirerId	String	✅	ID interno da adquirente.
acquirerResponseCode	String	✅	Código de resposta da adquirente.
acquirerResponseDate	Date	✅	Data/hora da resposta da adquirente.
acquirerAuthorizationNumber	String	✅	Número de autorização (pode vir vazio).
receipt	BarteReceipt?	—	Vias do comprovante (cliente/estabelecimento), quando disponível.

BartePaymentType

Descrição: tipos de transações suportados pelo SDK. Usado em: TransactionRequest.paymentTypes, BartePayment.paymentType.

Enum constante	id	Descrição
CREDIT	1	Crédito à vista.
DEBIT	2	Débito.
CREDIT_STORE	3	Crédito parcelado loja.
CREDIT_ADMIN	4	Crédito parcelado administradora.
PRE_AUTHORIZATION	5	Pré-autorização.
PRE_AUTHORIZATION_CONFIRMATION	6	Confirmação de pré-autorização.
PRE_AUTHORIZATION_CREDIT_STORE	7	Pré-autorização com parcelado loja.
PRE_AUTHORIZATION_CREDIT_ADMIN	8	Pré-autorização com parcelado administradora.
PRE_AUTHORIZATION_SUBSTITUTIVE	9	Pré-autorização substitutiva.
DEBIT_POSTDATED	10	Débito pré-datado.
VOUCHER	11	Voucher genérico.
VOUCHER_MEAL	12	Voucher refeição.
VOUCHER_FEED	13	Voucher alimentação.
VOUCHER_FLEET	14	Voucher frota.
PRIVATE_LABEL	15	Cartão private label (loja própria).
PRIVATE_LABEL_QUERY	16	Consulta de saldo private label.
PARCELED_CREDIT	17	Crédito parcelado genérico.

BartePaymentStatus

Descrição: estados possíveis de um pagamento. Usado em: BartePayment.paymentStatus, filtros de ListPaymentsRequest.

Enum constante	id	Descrição
PENDING	1	Pagamento iniciado, aguardando processamento.
CONFIRMED	2	Pagamento confirmado.
CANCELED	3	Pagamento cancelado.
REVERSED	4	Pagamento estornado.
PROCESSING	5	Pagamento em processamento.
DENIED	6	Pagamento negado.
UNREACHABLE	7	Falha de comunicação, adquirente não alcançável.
WAITING_VALIDATION	8	Pagamento aguardando validação.
WAITING_CAPTURE	9	Pagamento aguardando captura.
REFUNDED_DEVOLUTION	10	Estorno/devolução registrado (normalizado para REVERSED no SDK).
REFUNDED	11	Pagamento reembolsado.
APPROVED	12	Pagamento aprovado pela adquirente.

BarteCaptureType

Descrição: métodos de captura suportados. Usado em: BartePayment.captureType.

Enum constante	id	Descrição
MANUAL	1	Entrada manual de dados do cartão.
MAGNETIC_STRIP	2	Tarja magnética.
CHIP	3	Chip com contato.
FALLBACK_MANUAL	4	Fallback para entrada manual.
FALLBACK_MAGNETIC_STRIP	5	Fallback para tarja magnética.
CHIP_CONTACTLESS	6	Chip por aproximação (NFC).
MAGNETIC_STRIP_CONTACTLESS	7	Tarja por aproximação.
QR_CODE	8	Pagamento via QR Code.

BarteCard

Descrição: dados de cartão. Usado em: BartePayment.card.

Campo	Tipo	Descrição
brand	String?	Bandeira do cartão (ex.: “VISA”, “MASTERCARD”).
bin	String?	BIN (6 primeiros dígitos).
panLast4Digits	String?	4 últimos dígitos do PAN.

BarteReceipt

Descrição: dados de comprovante de pagamento. Usado em: BartePayment.receipt.

Campo	Tipo	Descrição
clientVia	String	Via do cliente (texto).
merchantVia	String	Via do estabelecimento (texto).

TransactionRequest (request)

Entrada de: startTransaction, startTransactionEndToEnd

Campo	Tipo	Obrigatório	Padrão	Descrição
value	BigDecimal	✅	—	Valor da transação.
paymentTypes