6 - Cancelamento

⚠️
Importante: Só é possível estornar transações dessa forma durante o mesmo dia em que essas foram realizadas. Isto é, se uma transação foi feita hoje, então ela só poderá ser estornada via requisição void hoje. A partir do dia seguinte, o estorno deverá ser realizado pelo dashboard.

Exemplo de cancelamento

Requisitando ao servidor

Inicie um cancelamento enviando uma requisição em JSON com os seguintes campos:

{
  "type": "void",
  "paymentType": 0 // Tipo de pagamento | Inteiro específico (vide abaixo).
}

O valor de paymentType deve ser um dentre:

- 0 para crédito;
- 1 para débito;
- e 2 para crédito parcelado.

A requisição deve ser feita por meio de WebSocket, como no exemplo abaixo, em JavaScript.

let voidRequest = {
  type: "void"
}

// Onde `socket` é um objeto de `WebSocket`.
socket.send(JSON.stringify(voidRequest))
socket.onmessage = (event) => {
  let response = JSON.parse(event.data)

  if (response == null) {
    return
  }

  if (response.type == "void") {
    if (response.status == "started") {
      // O processo de cancelamento foi iniciado.
      // ...

      return
    }

    if (response.status == "message") {
      /* Uma mensagem foi recebida no campo `message`, e deverá ser apresentada
         ao operador/cliente. */
      // ...

      return
    }

    if (response.status == "selectTransaction") {
      /* Uma lista de transações foi recebida no campo `transactionList`, e uma
         delas deve ser selecionada enviando uma requisição com `type` de valor
         `voidTransaction`. */
      // ...

      return
    }

    if (response.status == "success") {
      /* Cancelamento bem-sucedido, e os dados da transação cancelada poderão
         ser extraídos dos campos da resposta. */
      // ...

      return
    }

    if (response.status == "failed") {
      // Falha no cancelamento.
      // ...

      return
    }

    if (response.status == "finished") {
      // O processo de cancelamento terminou.
      // ...

      return
    }
  }

  // ...
}

📘
Um exemplo mais completo pode ser encontrado no aplicativo de exemplo, nas funções eventVoid e eventSendVoidTransaction do arquivo void.js.

Respostas

O Desktop Server responderá em JSON, indicando em status:

- started: o início do cancelamento;
- message: o recebimento de uma mensagem;
- selectTransaction: a necessidade de selecionar uma transação de uma lista;
- success: o sucesso do cancelamento;
- failed: a falha do cancelamento e a causa;
- finished: ou o término do cancelamento.

Início do cancelamento

Esta resposta sinaliza o início do processo de cancelamento. Ela será sucedida por outras respostas informando o andamento do processo.

{
  "type": "void",
  "status": "started",
  "message": "Processando cancelamento"
}

Mensagem

Esta resposta sinaliza o recebimento de uma mensagem que deverá ser apresentada de alguma forma ao operador/cliente.

{
  "type": "void",
  "status": "message",
  "message": "Processando cancelamento"
}

Lista de transações

Esta resposta sinaliza que uma transação deverá ser escolhida a partir de uma lista para cancelamento. Isto é, o Desktop Server precisa conhecer qual das últimas transações realizadas será cancelada.

{
  "type": "void",
  "status": "selectTransaction",
  "message": "Selecione a transação",
  "transactionList": [
    {
      "id": "------",            // ID do pagamento      | String numérica hexadecimal.
      "amount": "0,03",          // Montante pago        | String numérica decimal.
      "paymentType": 0,          // Tipo de pagamento    | Inteiro específico (vide abaixo).
      "cardBrand": "MASTERCARD", // Bandeira do cartão   | String alfanumérica.
      "date": "11/10",           // Data do pagamento    | String com data no formato "DD/MM".
      "time": "16:27"            // Horário do pagamento | String com horário no formato "HH:MM".
    },
    {
      "id": "------",
      "amount": "0,03",
      "paymentType": 1,
      "cardBrand": "MAESTRO",
      "date": "11/10",
      "time": "15:56"
    }
  ]
}

O valor de transactionList.paymentType será um dentre:

- 0 para crédito;
- 1 para débito;
- e 2 para crédito parcelado.

Indicando a transação selecionada

Para indicar qual transação da lista recebida em selectTransaction foi escolhida, envie a seguinte requisição em JSON:

{
  "type": "voidTransaction",
  "id": "------" // ID do pagamento | String numérica hexadecimal.
}

Assim como o início do processo de cancelamento, o envio deve ser feito por meio de WebSocket.

let selectionRequest = {
  type: "voidTransaction",
  id: "{ID da transação selecionada}"
}

socket.send(JSON.stringify(selectionRequest))
socket.onmessage = (event) => {
  let response = JSON.parse(event.data)

  if (response == null) {
    return
  }

  if (response.type == "void") {
    /* Apesar de `voidTransaction` ser um `type` de requisição diferente de
       `void`, o processo continua normalmente, com as respostas sendo de
       `type` com valor `void`. Isto é, assuma os mesmos tratamentos como se
       estivesse recebendo as respostas de uma requisição `void`. */
  }

  // ...
}

Depois da indicação da transação escolhida, o processo continuará normalmente. As respostas serão de type com o valor void, dando prosseguimento à requisição void que iniciou todo o processo.

Sucesso no cancelamento

Esta resposta sinaliza o sucesso do cancelamento. Os dados da transação cancelada serão recebidos na resposta.

{
  "type": "void",
  "status": "success",
  "message": "Transação cancelada",
  "value": 3,                // Montante cancelado                 | Inteiro (> 0).
  "paymentType": 1,          // Tipo de pagamento                  | Inteiro específico (vide abaixo).
  "brand": "Maestro",        // Bandeira do cartão                 | String alfanumérica
  "address": "-----",        // Endereço do seller                 | String alfanumérica.
  "sellerName": "-----",     // Nome do seller                     | String alfanumérica.
  "pan": "************3930", // PAN anonimizado do cartão          | String alfanumérica.
  "autoCode": "-----",       // Código de autorização (AUTO)       | String alfanumérica.
  "documentType": "CPF",     // Tipo de documento do seller        | String alfanumérica.
  "document": "-----",       // Documento do seller                | String alfanumérica.
  "nsu": "-----",            // NSU do pagamento                   | String alfanumérica.
  "date": "11/10/2023",      // Data do pagamento                  | String com data no formato "DD/MM/AAAA".
  "hour": "15:56",           // Horário do pagamento               | String com horário no formato "HH:MM".
  "cv": "-----",             // CV do pagamento                    | String alfanumérica.
  "arqc": "-----",           // ARQC do pagamento                  | String alfanumérica.
  "aid": "-----",            // ID da aplicação de pagamento (AID) | String alfanumérica.
  "sellerReceipt": "Maestro - Via Estabelecimento\n\n-----\n-----\nCPF:-----\nCV:-----\nAUTO:-----                 NSU:013686\nARQC:-----\n\nMaestro\nAID:-----\nVENDA DEBITO A VISTA\n\n************3930           11/10 15:56\nVALOR APROVADO                 R$ 0,03\n\n\n\n        APROVADA PELO EMISSOR\n", // Recibo, via do estabelecimento | String alfanumérica.
  "customerReceipt": "@        Maestro - Via Cliente@@-----@-----@CPF:-----@CV:-----@AUTO:-----@ARQC:-----@@Maestro@VENDA DEBITO A VISTA@@************3930           11/10 15:56@VALOR APROVADO                 R$ 0,03@", // Recibo, via do cliente | String alfanumérica.
  "approvalMessage": "APROVADA PELO EMISSOR", // Mensagem de aprovação          | String alfanumérica.
  "aidLabel": "Maestro",                      // Nome da aplicação de pagamento | String alfanumérica.
  "transactionId": "-----"                    // ID do pagamento                | String numérica hexadecimal.
}

O valor de value é dado em centavos:

- Exemplo: um montante de R$ 2,89 seria representado como 289.

O valor de paymentType será um dentre:

- 0 para crédito;
- 1 para débito;
- e 2 para crédito parcelado.

⚠️
A partir da versão 3.9.0-beta, os campos sellerReceipt e customerReceipt, que contêm o texto dos comprovantes da transação, não são mais retornados. Porém, os comprovantes podem ser montados a partir dos dados da própria transação: type, sellerName, documentType, document, address, transactionId, nsu, autoCode, arqc, cv.
Vide Geração de comprovantes.

Falha durante o cancelamento

Caso ocorra alguma falha durante o processo, a resposta será similar a esta:

{
  "type": "void",
  "status": "failed",
  "message": "05 - NAO AUTORIZADA",
  "statusCode": 5
}

O valor de statusCode será o código do erro que ocasionou a falha, sendo -1 caso não haja um código para a causa.

Término do cancelamento

Esta resposta sinaliza o término do processo de cancelamento, independente de sucesso ou falha.

{
  "type": "void",
  "status": "finished",
  "message": "Cancelamento finalizado"
}

Cancelamento assíncrono

A operação de cancelamento pode ser cancelada a qualquer momento enviando a requisição a seguir:

{
  "type": "abort"
}

📘

Ao receber uma mensagem cujo status seja selectTransaction, deve-se apresentar uma listagem de transações para o usuário. Neste ponto, uma transação deverá ser selecionada para cancelamento e notificada na requisição com type de valor voidtransaction.

O tempo para selecionar a transação a cancelar é de 30 segundos. Após isso, a operação será cancelada e notificada através de uma mensagem JSON com status de valor message.