6 - Pagamento via Pix

Como criar uma solicitação de pagamento via Pix com o SDK mPOS, configurar callbacks e cancelar a operação.

Pré-requisitos

Antes de iniciar um pagamento via Pix:

1. Inicialize o SDK mPOS na aplicação.
2. Realize o login para criar uma sessão válida.
3. Defina o valor da cobrança em centavos.

Criar um pagamento Pix

Para criar e executar uma solicitação de pagamento via Pix:

1. Crie a requisição com MPOSPlugin.createPixPaymentRequestBuilder().
2. Informe o valor da transação com .amount().
3. Configure os callbacks para acompanhar o fluxo do pagamento.
4. Execute a requisição com Zoop.post(pixRequest).

Exemplo
val pixRequest = MPOSPlugin.createPixPaymentRequestBuilder()
    .amount(1000L) // Valor em centavos: R$ 10,00
    //.referenceId("") Identificador próprio (opcional)
    //.metadata(buildJsonObject {}) Metadados adicionais (opcional)
    .callback(object: Callback<mPOSPixPaymentResponse>() {
        override fun onStart() {
            state = state.copy(status = Status.MESSAGE, message = "Iniciando")
        }

        override fun onSuccess(response: mPOSPixPaymentResponse) {
            state = state.copy(status = Status.MESSAGE, message = "SUCESSO")
        }

        override fun onFail(error: Throwable) {
            val message = if (error.message?.contains("invalid session") == true) {
                "Não foi realizado um login"
            } else {
                error.message
            }

            state = state.copy(status = Status.MESSAGE, message = message ?: "Falha")
        }
    })
    .messageCallback(object: Callback<MessageCallbackRequestField.MessageData>() {
        override fun onSuccess(response: MessageCallbackRequestField.MessageData) {
            state = state.copy(status = Status.MESSAGE, message = response.message)
        }

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

        override fun onFail(throwable: Throwable) {
            handleTransactionIdFailure(throwable)
        }
    })
    .qrCodeCallback(object: Callback<QRCodeCallbackRequestField.QRCodeData>() {
        override fun onSuccess(response: QRCodeCallbackRequestField.QRCodeData) {
            state = state.copy(status = Status.QR_CODE, qrCode = response.data)
        }

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

Zoop.post(pixRequest)

Parâmetros de entrada

ChaveTipoObjetivoExemplo
amountLongValor da transação em centavos.1000 (R$ 10,00)
referenceIdStringIdentificador próprio gerado pelo parceiro. Opcional, com máximo de 50 caracteres."237ab31-g99c-4e25-9hjs-32u4d3gf7fh2"
metadataString em JSON ou JsonObjectMetadados personalizados fornecidos pelo parceiro. Opcional, com máximo de 512 caracteres."{\"parcelado\":false,\"tentativa\":1,\"vencimento\":\"2024-02-15\",\"versao\":\"1.23.4\"}"

Opcional: Metadados em JsonObject

Use JsonObject quando precisar enviar metadados personalizados junto com a solicitação de pagamento.

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

Callbacks

Use os callbacks para acompanhar o ciclo de vida da transação, exibir mensagens na interface e armazenar identificadores retornados pelo SDK.

.callback

Responsável pelo fluxo do pagamento, incluindo início, processamento e conclusão com sucesso ou falha.

CallbackQuando é chamadoUso recomendado
onStartQuando o fluxo do pagamento começa.Exibir uma mensagem de carregamento, como Iniciando pagamento.
onSuccessQuando a transação é aprovada.Ler os dados de response.transactionData e exibir a confirmação da transação.
onFailQuando ocorre uma falha na transação.Registrar o erro e exibir uma mensagem de falha para o usuário.
onCompleteQuando o fluxo termina, tanto em casos de sucesso quanto de falha.Finalizar estados de carregamento ou limpar controles temporários da interface.

onStart

Esta callback é sinalizada quando o fluxo do pagamento começa. Use esse retorno para indicar na aplicação que o processamento foi iniciado.

onSuccess

Neste momento, a transação foi aprovada. Você recebe o objeto do tipo MPOSPixPaymentResponse, que contém um TransactionData acessível por response.transactionData.

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
    val 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
    var cardFingerprint: String? = null, // Token único do cartão
    var cardEntryMode: String? = null // Identifica qual o modo de entrada do cartão(TARJA, CHIP, NFC)
)
📘

O campo pixId é um identificador interno da Zoop.

onFail

Falha na transação. A aplicação recebe uma exception, que pode ser de um dos seguintes tipos:

  • ZoopPaymentException: falha no fluxo do pagamento. A mensagem de erro pode ser acessada por exception.message.
  • ZoopTimeoutException: tempo excedido na operação.
  • ZoopClosedConnectionException: conexão interrompida.
  • ZoopNetworkException: falha de conexão.

onComplete

Sinaliza o final do fluxo do pagamento, tanto em casos de sucesso quanto de falha.

.qrCodeCallback

Responsável por receber o QR Code para exibição no POS.

CallbackQuando é chamadoUso recomendado
onSuccessQuando o SDK retorna o QR Code Pix.Exibir response.data na interface da aplicação.
onFailNão é chamado nesse callback.Não implementar ações dependentes de falha aqui.

onSuccess

Retorna o QR Code que deve ser exibido pela aplicação para o usuário. O valor é acessado por response.data.

onFail

Não recebe nenhum dado. Esta callback não é chamada.

.transactionIdCallback

Responsável por receber o ID da transação.

CallbackQuando é chamadoUso recomendado
onSuccessQuando o SDK retorna o ID da transação.Armazenar response.data para consulta ou conciliação.
onFailNão é chamado nesse callback.Não implementar ações dependentes de falha aqui.

onSuccess

Retorna o ID da transação na infraestrutura Zoop. O valor é acessado por response.data.

onFail

Não recebe nenhum dado. Esta callback não é chamada.

.messageCallback

Responsável pelas mensagens exibidas durante o fluxo do pagamento.

CallbackQuando é chamadoUso recomendado
onSuccessQuando o SDK envia uma mensagem operacional do pagamento.Exibir response.message na interface da aplicação.
onFailNão é chamado nesse callback.Não implementar ações dependentes de falha neste callback.

onSuccess

Retorna a mensagem que deve ser exibida pela aplicação para o usuário. O valor é acessado por response.message.

onFail

Não recebe nenhum dado. Esta callback não é chamada.

Cancelar um pagamento Pix

Chame o método cancel() a partir do objeto da requisição que deseja cancelar. Use o mesmo objeto passado ao método Zoop.post() ou Zoop.enqueue().

📘

O cancelamento é assíncrono e cooperativo. O método cancel() sinaliza a intenção de cancelamento para o SDK e retorna imediatamente, sem aguardar a conclusão do cancelamento. O SDK interrompe e cancela a operação na primeira oportunidade possível.

Exemplo
var pixRequest: Request? = null

fun payWithPix() {
    pixRequest = MPOSPlugin.createPixPaymentRequestBuilder()
        // ...
        .build()

    Zoop.post(pixRequest)
}

fun cancelPixPayment() {
    pixRequest?.cancel()
}

Acompanhe o resultado final da operação pelos callbacks configurados na requisição.


Did this page help you?