5 - Pagamento via Pix

Crie pagamentos Pix no terminal SmartPOS usando QR Code ou Pix NFC.

O Pix NFC permite que o cliente pague aproximando um celular Android com carteira digital compatível com NFC, sem escanear um QR Code.

Pré-requisitos

Antes de iniciar um pagamento Pix:

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

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

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

4. Prepare a interface para exibir QR Code, mensagens de status e erros de pagamento.

5. Defina se o fluxo permitirá Pix NFC.

Classe utilizada

Para pagamentos via Pix, use a classe SmartPOSPixPaymentRequestBuilder.

A requisição é criada por:

SmartPOSPlugin.createPixPaymentRequestBuilder()

Fluxo do pagamento Pix

1. Crie a requisição com valor e parâmetros opcionais.

2. Receba o QR Code pelo qrCodeCallback.

3. Exiba o QR Code para o cliente.

4. Receba o ID da transação pelo transactionIdCallback.

5. Exiba mensagens do fluxo pelo messageCallback.

6. Aguarde sucesso ou falha no callback principal.

7. Use response.transactionData para salvar ou imprimir os dados da transação.

Exemplo

val pixRequest = SmartPOSPlugin.createPixPaymentRequestBuilder()
    .amount(1000)
    //.referenceId("") Identificador próprio (opcional)
    //.metadata(buildJsonObject {}) Metadados adicionais (opcional)
    //.enableNfc(true) Pagamento via NFC (opcional)
    .callback(object: Callback<SmartPOSPixPaymentResponse>()\{
        override fun onSuccess(response: SmartPOSPixPaymentResponse) {
            handleSucessfullPayment(response)
        }

        override fun onFail(throwable: Throwable) {
            handlePaymentFailure(exception)
        }
    \})
    .qrCodeCallback(object: Callback<QRCodeCallbackRequestField.QRCodeData>() \{
        override fun onSuccess(qrCodeData: QRCodeCallbackRequestField.QRCodeData) {
            showQRCode(qrCodeData.getData())
        }

        override fun onFail(throwable: Throwable) {
            handleQrCodeFailure(throwable)
        }
    \})
    .transactionIdCallback(object: Callback<TransactionIdCallbackRequestField.transactionIdData>() \{
        override fun onSuccess(transactionId: TransactionIdCallbackRequestField.transactionIdData) {
            storeTransactionId(transactionId.data)
        }

        override fun onFail(throwable: Throwable) {
            handleTransactionIdFailure(throwable)
        }
    \})
    .messageCallback(object: Callback<MessageCallbackRequestField.MessageData>() \{
        override fun onSuccess(messageData: MessageCallbackRequestField.MessageData) {
            displayMessage()
        }

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

Zoop.post(pixRequest)

Parâmetros de entrada

Chave	Tipo	Obrigatório	Descrição	Exemplo
`amount`	`Long`	Sim	Valor da transação em centavos.	`1000`
`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.	`"{\"parcelado\":false,\"tentativa\":1}"`
`enableNfc`	`Boolean`	Não	Habilita (`true`) ou desabilita (`false`) pagamento Pix via NFC. Padrão: habilitado.	`false`

Optional: Habilitar ou desabilitar Pix NFC

Use enableNfc para controlar se o pagamento Pix por NFC estará disponível no fluxo.

val pixRequest = SmartPOSPlugin.createPixPaymentRequestBuilder()
    .amount(1000)
    .enableNfc(false)
    .build()

Quando enableNfc(false) é usado, o fluxo segue sem pagamento por aproximação via Pix NFC.

Optional: Enviar metadados

Você pode enviar metadados como JsonObject.

val metadata = buildJsonObject {
    put("endereco", "Avenida X")
    put("parcelado", false)
    put("tentativa", 1)
}

Depois, informe o objeto no builder:

.metadata(metadata)

Callbacks

`.callback`

Controla o fluxo principal do pagamento Pix: 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 ou imprimir a transação.
`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 SmartPOSPixPaymentResponse contendo TransactionData, acessível por response.transactionData.

Para imprimir o recibo, 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.
)

O campo pixId é um identificador interno da Zoop.

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.

`.qrCodeCallback`

Recebe o QR Code que deve ser exibido no app.

Método	Quando ocorre	Ação recomendada
`onSuccess`	O QR Code foi gerado.	Exiba `response.data` ou `qrCodeData.getData()` para o cliente.
`onFail`	O QR Code não foi gerado.	Trate a falha e permita iniciar uma nova tentativa.

`.transactionIdCallback`

Recebe o ID da transação na infraestrutura Zoop.

Método	Quando ocorre	Ação recomendada
`onSuccess`	O ID da transação foi gerado.	Salve `response.data` ou `transactionId.data` para rastreio.
`onFail`	O ID não foi recebido.	Trate a falha conforme a experiência do app.

`.messageCallback`

Recebe mensagens do fluxo do pagamento Pix.

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.

Checklist de pagamento Pix

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

O SDK foi inicializado com credenciais.
O SmartPOSPlugin foi plugado.
amount está em centavos.
A interface exibe QR Code.
A interface exibe mensagens do fluxo.
O app salva o ID da transação quando recebido.
O app trata sucesso e falha no callback principal.
O app define enableNfc conforme a experiência desejada.
O app sabe como imprimir ou armazenar response.transactionData após o sucesso.

Próximo passo

Depois de implementar pagamento Pix, consulte Impressão SmartPOS para imprimir recibos ou Cancelamento SmartPOS para cancelar transações quando aplicável.