4 - Pagamento via cartão

Pagamento

Inicie um pagamento via cartão enviando uma requisição em JSON com os seguintes campos:

{
  "type": "payment",
  "paymentType": 1,                 // Tipo de pagamento                | Inteiro específico (vide abaixo).
  "amount": 3,                      // Montante a cobrar                | Inteiro (> 0).
  "installments": 1,                // Número de parcelas               | Inteiro (> 0).
  "referenceId": "123.456-abc",     // Identificador personalizado      | String alfanumérica.
  "metadata": {}                    // Campos adicionais personalizados  | Objeto em JSON.
}

O valor de paymentType deve ser um dentre:
- 0 para crédito;
- 1 para débito;
- 2 para crédito parcelado;
- e 3 para voucher.
O valor de amount é dado em centavos:
- Exemplo: um montante de R$ 1,75 seria representado como 175.
O valor padrão de installments, quando omitido, é 1.
O campo referenceId é opcional, podendo ser omitido. Seu valor deve ser um identificador alfanumérico, com um máximo de 50 caracteres, fornecido pelo parceiro para fins próprios:
- Exemplo: "1237ab31-g99c-4e25-9hjs-32u4d3gf7fh2".
O campo metadata é opcional, podendo ser omitido. Seu valor deve ser um objeto em JSON, com um máximo de 512 caracteres quando condensado, fornecido pelo parceiro para fins próprios:
- Exemplo:

{
  "type": "payment",
  // ...
  "metadata": {
    "comerciante": {
      "endereco": {
        "cep": 99999555,
        "cidade": "SÃO PAULO",
        "complemento": "",
        "logradouro": "AVENIDA X",
        "numero": 1200,
        "unidade_federativa": "SP"
      },
      "id": "abc12345",
      "nome": "REDE SUPERMERCADOS X",
      "telefone": "+55***********",
      "tipo": "business"
    },
    "parcelado": false,
    "taxa": 0.07,
    "tentativa": 1,
    "versao": "1.23.4"
  }
}

Envio da requisição

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

let paymentRequest = {
  type: "payment",
  paymentType: 1,
  amount: 150,
  installments: 1
}

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

  if (response == null) {
    return
  }

  if (response.type == "payment") {
    if (response.status == "started") {
      // O processo de pagamento 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 == "success") {
      /* Pagamento bem-sucedido, e os dados poderão ser extraídos dos campos da
         resposta. */
      // ...

      return
    }

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

      return
    }

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

      return
    }
  }

  // ...
}

📘
Um exemplo mais completo pode ser encontrado no aplicativo de exemplo, na função eventPayment do arquivo payment.js.

Respostas

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

started: o início do pagamento;
message: o recebimento de uma mensagem;
success: o sucesso do pagamento;
failed: a falha do pagamento e a causa;
finished: ou o término do pagamento.

Início do pagamento

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

{
  "type": "payment",
  "message": "Iniciando pagamento",
  "status": "started"
}

Mensagem

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

{
  "type": "payment",
  "status": "message",
  "message": "Processando"
}

Sucesso no pagamento

Esta resposta sinaliza o sucesso do pagamento. Os dados dele serão recebidos na resposta.

{
  "type": "payment",
  "status": "success",
  "message": "Transação aprovada",
  "value": 3,                // Montante pago                      | 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$ 0,94 seria representado como 94.
O valor de paymentType será um dentre:
- 0 para crédito;
- 1 para débito;
- 2 para crédito parcelado;
- 3 para voucher.
O campo remainingTransactionDebt estará presente na resposta de um pagamento utilizando o saldo restante de um voucher.

⚠️
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 pagamento

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

{
  "type": "payment",
  "status": "failed",
  "message": "83 - CARTAO INVALIDO, USE CHIP/TARJA",
  "statusCode": 83,
}

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 pagamento

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

{
  "type": "payment",
  "status": "finished",
  "message": "Transação finalizada"
}

Cancelamento assíncrono

A operação de pagamento pode ser cancelada a qualquer momento (exceto no fluxo após a aproximação do cartão ou na confirmação da senha no PIN Pad) enviando a requisição a seguir:

{
  "type": "abort"
}