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âmetro | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
amount | Long | Sim | Valor da transação em centavos. | 500 (R$ 5,00) |
option | Option | Sim | Opção do pagamento. | Option.CREDIT |
installments | Long | Sim | Quantidade de parcelas. Para pagamentos à vista, use 1. | 1 |
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. | Vide Metadados em JsonObject |
externalSeller | ExternalSeller | Não | Dados 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ébitoMetadados em JsonObject
JsonObjectUse 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.
| Callback | Quando ocorre |
|---|---|
onStart | Quando o fluxo do pagamento começa. |
onSuccess | Quando a transação é aprovada. |
onFail | Quando ocorre uma falha na transação. |
onComplete | Quando o fluxo termina, tanto em casos de sucesso quanto de falha. |
onStart
onStartEsta callback é sinalizada quando o fluxo do pagamento começa. Use esse momento para indicar na aplicação que o processamento foi iniciado.
onSuccess
onSuccessQuando 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
onFailQuando 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 porexception.message.ZoopTimeoutException: tempo excedido na operação.ZoopClosedConnectionException: conexão interrompida.ZoopNetworkException: falha de conexão.
onComplete
onCompleteSinaliza 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
onSuccessMensagem a ser exibida pela aplicação para o usuário. O conteúdo da mensagem pode ser acessado por response.message.
onFail
onFailNã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()
}Updated 7 days ago
