4 - Pagamento via cartão

Crie pagamentos com cartão no terminal SmartPOS usando crédito, crédito parcelado ou débito.

Consulte a chave transacional na inicialização do plugin. Se a chave não existir no terminal, a transação com cartão será impedida e o dispositivo deverá ser enviado ao fabricante para correção.

Pré-requisitos

Antes de iniciar um pagamento com cartão:

1. Ative o terminal em Ativação SmartPOS.

2. Inicialize o SDK e plugue o SmartPOSPlugin em Inicialização SmartPOS.

3. Consulte a chave transacional e confirme que response.hasKey retornou true.

4. Solicite as permissões Android necessárias em tempo de execução.

5. Prepare a interface do app para exibir mensagens, menus, input de senha e eventuais solicitações de CVV.

Classe utilizada

Para pagamentos via cartão, use a classe SmartPOSPaymentRequestBuilder.

A requisição é criada por:

SmartPOSPlugin.createPaymentRequestBuilder()

Exemplo de pagamento

val paymentRequest = SmartPOSPlugin.createPaymentRequestBuilder()
    .amount(1000)
    .option(Option.CREDIT)
    .installments(2)
    //.autoPrintEstablishmentReceipt(false) // Para desabilitar a impressão automática.
    //.referenceId("")                      // Identificador próprio (opcional)
    //.metadata(buildJsonObject {})         // Metadados adicionais (opcional)
    .callback(object: Callback<SmartPOSPaymentResponse>() \{
        override fun onStart() {
            startLoadingAnimation()
        }

        override fun onSuccess(response: SmartPOSPaymentResponse) {
            handleSucessfullPayment(response)
        }

        override fun onFail(exception: Throwable) {
            handlePaymentFailure(exception)
        }

        override fun onComplete() {
            stopLoadingAnimation()
        }
    \})
    .messageCallback(object: Callback<MessageCallbackRequestField.MessageData>() \{
        override fun onSuccess(messageData: MessageCallbackRequestField.MessageData) {
            displayUserMessage(messageData.message)
        }

        override fun onFail(exception: Throwable) {
        }
    \})
    .pinCallback(object: Callback<PinCallbackRequestField.PinData>() \{
        override fun onSuccess(pinData: PinCallbackRequestField.PinData) {
            val eventType = pinData.getType()
            when (eventType) {
                Terminal.PinEventHandler.EventType.Start -> creatViewToDisplayPasswordInput()
                Terminal.PinEventHandler.EventType.Finish -> finishPasswordInput()
                Terminal.PinEventHandler.EventType.Inserted -> handlePasswordCaracterInput()
                Terminal.PinEventHandler.EventType.Removed -> handlePasswordCaracterRemoved()
                else -> handlePasswordCaracterCleared()
            }
        }

        override fun onFail(exception: Throwable) {
        }
    \})
    .menuSelectionCallback(object: Callback<SmartPOSMenuOptions>() \{
        override fun onFail(error: Throwable) {
        }

        override fun onSuccess(response: SmartPOSMenuOptions) {
            assembleOptionsList(response.options.iterable)
        }
    \})
    .userInputCallback(object: Callback<UserInput>() \{
        override fun onSuccess(response: UserInput) {
            when (response.type) {
                UserInputType.CVV -> { requestCvv() }
            }
        }

        override fun onFail(error: Throwable) {
        }
    \})
    .build()

Zoop.post(paymentRequest)

Parâmetros de entrada

Chave	Tipo	Obrigatório	Descrição	Exemplo
`amount`	`Long`	Sim	Valor da transação em centavos.	`1000`
`option`	`Option`	Sim	Opção do pagamento.	`Option.CREDIT`
`installments`	`Long`	Conforme opção	Quantidade de parcelas.	`2`
`autoPrintEstablishmentReceipt`	`Boolean`	Não	Define se a via do estabelecimento será impressa automaticamente.	`true`
`referenceId`	`String`	Não	Identificador próprio gerado pelo parceiro. Máximo de 50 caracteres.	`"237ab31-g99c-4e25-9hjs-32u4d3gf7fh2"`
`metadata`	`String` em JSON ou `JsonObject`	Não	Metadados personalizados fornecidos pelo parceiro. Máximo de 512 caracteres.	Veja exemplo abaixo.

Opções de pagamento

Option.CREDIT                   // Crédito à vista
Option.CREDIT_WITH_INSTALLMENTS // Crédito parcelado
Option.DEBIT                    // Débito

Optional: Enviar metadados

Você pode enviar metadados como JsonObject.

val metadata = buildJsonObject {
    put("endereco", "Avenida X")
    put("parcelado", false)
    put("tentativa", 1)
    put("vencimento", "2024-02-15")
    put("versao", "1.23.4")
}

Depois, informe o objeto no builder:

.metadata(metadata)

Callbacks

`.callback`

Controla o fluxo principal do pagamento: início, sucesso, falha e conclusão.

Método	Quando ocorre	Ação recomendada
`onStart`	O fluxo de pagamento começou.	Inicie um loading ou bloqueie ações concorrentes.
`onSuccess`	A transação foi aprovada.	Use `response.transactionData` para salvar a transação ou imprimir recibo.
`onFail`	A transação falhou.	Trate a exceção e exiba uma mensagem para o operador.
`onComplete`	O fluxo terminou, com sucesso ou falha.	Remova loading e libere a interface.

Retorno de sucesso

Em onSuccess, você recebe um objeto SmartPOSPaymentResponse contendo TransactionData, acessível por response.transactionData.

Se a impressão automática da via do estabelecimento estiver ativa, a via será impressa. Para imprimir manualmente, envie esse objeto para o request de impressão.

data class TransactionData(
    val value: Int?, // Valor da transação em centavos
    val paymentType: Int?, // Tipo de pagamento
    val installments: Int?, // Parcelas
    val status: String?, // Status (approved/canceled)
    val brand: String?, // Marca do cartão ex: Visa
    val address: String?, // Endereço do seller
    val sellerName: String?, // Nome do seller
    val acquiring: String?, // Adquirente
    val pan: String?, // PAN do cartão
    val autoCode: String?, // Código de autorização
    val documentType: String?, // Tipo de documento, CPF/CNPJ
    val document: String?, // Documento
    val nsu: String?, // NSU
    val date: String?, // Data da transação
    val hour: String?, // Hora da transação
    val cv: String?, // CV
    val arqc: String?, // ARQC
    val aid: String?, // AID
    val sellerReceipt: String?, // Recibo do estabelecimento
    val customerReceipt: String?, // Recibo do cliente
    val approvalMessage: String?, // Mensagem de aprovação ex: APROVADA PELO EMISSOR
    val aidLabel: String?, // Label do cartão
    var transactionId: String?, // Id da transação
    val receiptId: String? = null, // Id do recibo, caso aplicável (hoje, apenas transações Pix)
    val pixId: String? = null, // Id do Pix
    val cardFingerprint: String? = null // Token único do cartão.
)

Exceções de falha

Em onFail, você pode receber uma destas exceções:

Exceção	Quando ocorre
`ZoopPaymentException`	Falha no fluxo do pagamento. A mensagem pode ser acessada em `exception.message`.
`ZoopTimeoutException`	Tempo excedido na operação.
`ZoopClosedConnectionException`	Conexão interrompida.
`ZoopNetworkException`	Falha de conexão.

`.messageCallback`

Recebe mensagens do fluxo de pagamento, como “Aproxime, insira ou passe o cartão”.

Método	Quando ocorre	Ação recomendada
`onSuccess`	Uma mensagem foi enviada pelo fluxo.	Exiba `response.message` ou `messageData.message` para o usuário.
`onFail`	Não recebe dados.	Nenhuma ação necessária.

`.pinCallback`

Recebe eventos do input de senha quando a senha é necessária.

Em onSuccess, o callback recebe PinCallbackRequestField.PinData. O tipo do evento é acessado por response.type ou pinData.getType().

EventType.Start    // É necessário criar uma view em que o teclado de senha será exibido de forma automática.
EventType.Finish   // O fluxo de senha foi finalizado.
EventType.Inserted // Caractere inserido na senha.
EventType.Removed  // Caractere removido da senha.
EventType.Cleared  // Campo de senha foi limpo; todos os caracteres foram removidos.

Método	Quando ocorre	Ação recomendada
`onSuccess`	Um evento de senha foi emitido.	Atualize a interface de senha conforme o evento recebido.
`onFail`	Não recebe dados.	Nenhuma ação necessária.

`.menuSelectionCallback`

Solicita que o app exiba uma seleção manual de aplicação do cartão.

A aplicação deve exibir a lista com as opções recebidas e permitir que uma opção seja selecionada em até 30 segundos. Se nenhuma opção for selecionada, a operação será cancelada.

Para selecionar uma opção, use:

response.options.select(MenuOptionsData)

Retorno

data class SmartPOSMenuOptions(
    val options: List<MenuOptionsData>, // Lista de itens, acessada como response.options.iterable
    val title: String, // Título do tipo de seleção requisitada. Ex: "Opções do cartão"
    val defaultOption: Int // Opção padrão pré-definida.
)

data class MenuOptionsData(
    val index: Int, // Valor a ser exibido como índice do item na lista.
    val itemName: String // Título do item do menu. Ex: "Crédito"
)

Método	Quando ocorre	Ação recomendada
`onSuccess`	Há opções para seleção manual.	Exiba a lista e chame `select()` com a opção escolhida.
`onFail`	Não recebe dados.	Nenhuma ação necessária.

`.userInputCallback`

Solicita dados adicionais da aplicação, como CVV do cartão.

Em onSuccess, o callback recebe UserInput, com o parâmetro type do tipo UserInputType.

Para enviar o dado solicitado, use:

userInput.input(cvv)

Para cancelar a solicitação, use:

userInput.cancel()

Tipos de input disponíveis:

UserInputType.AMOUNT           // Valor do pagamento.
UserInputType.CVV              // CVV do cartão.
UserInputType.INSTALLMENTS     // Número de parcelas.
UserInputType.LAST_FOUR_DIGITS // Últimos quatro dígitos do cartão.
UserInputType.PHONE_NUMBER     // Número de telefone.

Método	Quando ocorre	Ação recomendada
`onSuccess`	O fluxo solicitou um dado adicional.	Capture o dado na UI e responda com `input()` ou cancele com `cancel()`.
`onFail`	Não recebe dados.	Nenhuma ação necessária.

Checklist de pagamento

Antes de enviar a requisição com Zoop.post(paymentRequest), confirme:

O SDK foi inicializado com credenciais.
O SmartPOSPlugin foi plugado.
A chave transacional foi validada com sucesso.
amount está em centavos.
option corresponde ao tipo de pagamento desejado.
installments foi definido quando aplicável.
A interface trata mensagens do messageCallback.
A interface trata input de senha no pinCallback.
A interface trata seleção de menu em até 30 segundos.
O app trata CVV e outros inputs solicitados pelo userInputCallback.
O app trata sucesso, falha e conclusão no .callback.

Próximo passo

Depois de implementar pagamento via cartão, consulte Impressão SmartPOS para imprimir recibos ou Cancelamento SmartPOS para cancelar transações.