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
| Chave | Tipo | Objetivo | Exemplo |
|---|---|---|---|
amount | Long | Valor da transação em centavos. | 1000 (R$ 10,00) |
referenceId | String | Identificador próprio gerado pelo parceiro. Opcional, com máximo de 50 caracteres. | "237ab31-g99c-4e25-9hjs-32u4d3gf7fh2" |
metadata | String em JSON ou JsonObject | Metadados 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.
| Callback | Quando é chamado | Uso recomendado |
|---|---|---|
onStart | Quando o fluxo do pagamento começa. | Exibir uma mensagem de carregamento, como Iniciando pagamento. |
onSuccess | Quando a transação é aprovada. | Ler os dados de response.transactionData e exibir a confirmação da transação. |
onFail | Quando ocorre uma falha na transação. | Registrar o erro e exibir uma mensagem de falha para o usuário. |
onComplete | Quando o fluxo termina, tanto em casos de sucesso quanto de falha. | Finalizar estados de carregamento ou limpar controles temporários da interface. |
onStart
onStartEsta callback é sinalizada quando o fluxo do pagamento começa. Use esse retorno para indicar na aplicação que o processamento foi iniciado.
onSuccess
onSuccessNeste 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
onFailFalha 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 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.
.qrCodeCallback
Responsável por receber o QR Code para exibição no POS.
| Callback | Quando é chamado | Uso recomendado |
|---|---|---|
onSuccess | Quando o SDK retorna o QR Code Pix. | Exibir response.data na interface da aplicação. |
onFail | Não é chamado nesse callback. | Não implementar ações dependentes de falha aqui. |
onSuccess
onSuccessRetorna o QR Code que deve ser exibido pela aplicação para o usuário. O valor é acessado por response.data.
onFail
onFailNão recebe nenhum dado. Esta callback não é chamada.
.transactionIdCallback
Responsável por receber o ID da transação.
| Callback | Quando é chamado | Uso recomendado |
|---|---|---|
onSuccess | Quando o SDK retorna o ID da transação. | Armazenar response.data para consulta ou conciliação. |
onFail | Não é chamado nesse callback. | Não implementar ações dependentes de falha aqui. |
onSuccess
onSuccessRetorna o ID da transação na infraestrutura Zoop. O valor é acessado por response.data.
onFail
onFailNão recebe nenhum dado. Esta callback não é chamada.
.messageCallback
Responsável pelas mensagens exibidas durante o fluxo do pagamento.
| Callback | Quando é chamado | Uso recomendado |
|---|---|---|
onSuccess | Quando o SDK envia uma mensagem operacional do pagamento. | Exibir response.message na interface da aplicação. |
onFail | Não é chamado nesse callback. | Não implementar ações dependentes de falha neste callback. |
onSuccess
onSuccessRetorna a mensagem que deve ser exibida pela aplicação para o usuário. O valor é acessado por response.message.
onFail
onFailNã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.
Updated 7 days ago
