5 - Pagamento via cartão

Como criar, enviar e cancelar uma requisição de pagamento via cartão usando o Plugin mPOS.

Crie uma requisição de pagamento via cartão com MPOSPlugin.createPaymentRequestBuilder() e envie a operação com Zoop.post().

Pré-requisitos

1. Inicialize o SDK da Zoop.
2. Conecte o plugin mPOS com Zoop.plug().
3. Garanta que o dispositivo esteja ativado e pronto para transacionar.

Criar um pagamento via cartão

Use MPOSPlugin.createPaymentRequestBuilder() para montar a requisição de pagamento. O valor da transação deve ser informado em centavos.

val paymentRequest = MPOSPlugin.createPaymentRequestBuilder()
    .amount(500) // Valor em centavos: R$ 5,00
    .option(Option.CREDIT)
    .installments(1)
    //.referenceId("")                     // Identificador próprio (opcional)
    //.metadata(buildJsonObject {})        // Metadados adicionais (opcional)
    //.externalSeller(ExternalSeller(...)) // External seller (opcional)
    .callback(object: Callback<mPOSPaymentResponse>() {
        override fun onStart() {
            Log.d("mPOS", "onStart")
            state = state.copy(status = Status.MESSAGE, message = "Iniciando")
        }

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

        override fun onFail(error: Throwable) {
            Log.d("mPOS", "onFail ${error.message}")
            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) {
            Log.d("mPOS", "messageCallback ${response.message}")
            state = state.copy(status = Status.MESSAGE, message = response.message)
        }

        override fun onFail(error: Throwable) {
            Log.d("mPOS", "messageCallback fail")
        }
    })
    .build()

Zoop.post(paymentRequest)

Parâmetros de entrada

ParâmetroTipoObrigatórioDescriçãoExemplo
amountLongSimValor da transação em centavos.500 (R$ 5,00)
optionOptionSimOpção do pagamento.Option.CREDIT
installmentsLongSimQuantidade de parcelas. Para pagamentos à vista, use 1.1
referenceIdStringNãoIdentificador próprio gerado pelo parceiro. Máximo de 50 caracteres."237ab31-g99c-4e25-9hjs-32u4d3gf7fh2"
metadataString em JSON ou JsonObjectNãoMetadados personalizados fornecidos pelo parceiro. Máximo de 512 caracteres.Vide Metadados em JsonObject
externalSellerExternalSellerNãoDados do external seller.Vide External seller

Opções de pagamento

Use Option.CREDIT para crédito à vista, Option.CREDIT_WITH_INSTALLMENTS para crédito parcelado e Option.DEBIT para débito.

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

Metadados em JsonObject

Use metadata para enviar informações adicionais da transação. O campo aceita uma String em JSON ou um JsonObject.

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

val paymentRequest = MPOSPlugin.createPaymentRequestBuilder()
    .amount(500)
    .option(Option.CREDIT)
    .installments(1)
    .metadata(metadata)
    .build()

External seller

Use externalSeller para enviar os dados do external seller junto com a requisição de pagamento.

val externalSeller = ExternalSeller(
    addressLine = "Avenida **********, ***", // Endereço.
    softDescriptor = "SDESC TESTE", // Nome da empresa.
    cpfCnpj =  "***********", // CPF ou CNPJ, não é necessário adicionar máscara nesse campo.
    state = "SP", // Estado.
    city = "Campinas", // Cidade.
    country =  "076", // Sigla ou código do país.
    phoneNumber =  "+55***********", // O número de telefone deve iniciar com o código do país, DDD e o número.
    zipCode = "89******", // CEP do cliente.
    subMerchantId = "545*********", // Informação que identifica o estabelecimento para a bandeira e o emissor.
    merchantCategoryCode = "7399", // MCC do estabelecimento.
    name = "VAREJO LTDA.", // Razão social da empresa.
    voucherPv = "a9f3b7c1d2e8f4g" // Código de cadastro na adquirente. Opcional, mínimo 8 e máximo 15 caracteres.
)

val paymentRequest = MPOSPlugin.createPaymentRequestBuilder()
    .amount(500)
    .option(Option.CREDIT)
    .installments(1)
    .externalSeller(externalSeller)
    .build()

Callbacks

Use os callbacks para acompanhar o ciclo de vida da transação e atualizar a interface da aplicação durante o pagamento.

.callback

O .callback é responsável pelo fluxo do pagamento: início, processamento e conclusão com sucesso ou falha.

CallbackQuando ocorre
onStartQuando o fluxo do pagamento começa.
onSuccessQuando a transação é aprovada.
onFailQuando ocorre uma falha na transação.
onCompleteQuando o fluxo termina, tanto em casos de sucesso quanto de falha.

onStart

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

onSuccess

Quando a transação é aprovada, o SDK retorna um objeto do tipo mPOSPaymentResponse. Os dados da transação ficam disponíveis em response.transactionData, que contém um 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
    val cardEntryMode: String? // Identifica qual o modo de entrada do cartão(TARJA, CHIP, NFC)
)

onFail

Quando a transação falha, o SDK retorna uma exceção em onFail. A exceção pode ser de um dos seguintes tipos:

  • ZoopPaymentException: falha no fluxo do pagamento. A mensagem 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.

.messageCallback

Use .messageCallback para receber mensagens operacionais do fluxo de pagamento e exibi-las na interface da aplicação. Exemplo: "Aproxime, insira ou passe o cartão".

onSuccess

Mensagem a ser exibida pela aplicação para o usuário. O conteúdo da mensagem pode ser acessado por response.message.

onFail

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

Cancelar uma operação

Cancele uma operação chamando o método cancel() a partir do objeto da requisição que você deseja cancelar. Use o mesmo objeto passado para Zoop.post() ou Zoop.enqueue().

📘

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

Exemplo de cancelamento

var paymentRequest: Request? = null

fun payWithCard() {
    paymentRequest = MPOSPlugin.createPaymentRequestBuilder()
        // ...
        .build()

    Zoop.post(paymentRequest)
}

fun cancelCardPayment() {
    paymentRequest?.cancel()
}


Did this page help you?