5 - Pagamento via Pix

Exemplo de pagamento

Requisitando ao servidor

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

{
  "type": "pix",
  "amount": 100,                // Montante a cobrar                       | Inteiro (> 0).
  "referenceId": "123.456-abc", // Identificador personalizado             | String alfanumérica.
  "metadata": {},               // Campos adicionais personalizados        | Objeto em JSON.
  "displayOnPinPad": true       // Usar o PIN Pad como display             | Booleano.
}

- O valor de amount é dado em centavos:
- Exemplo: um montante de R$ 1,75 seria representado como 175.
- 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 displayOnPinPad é opcional, podendo ser omitido. Quando omitido, assume-se seu valor como true.
- 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 de metadata:

{
  "type": "pix",
  // ...
  "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": "+99***********",
      "tipo": "business"
    },
    "parcelado": false,
    "taxa": 0.07,
    "tentativa": 1,
    "versao": "1.23.4"
  }
}

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

let pixPaymentRequest = {
  type: "pix",
  amount: 150,
}

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

  if (response == null) {
    return
  }

  if (response.type == "pix") {
    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 == "qrCode") {
      // URL contida no QR Code para pagar o Pix, recebida no campo `qrCode`.
      return
    }

    if (response.status == "transactionId") {
      // ID da transação, recebido no campo `transactionId`.
      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
    }
  }

  // ...
}

circle-info

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

Respostas

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

- started: o início do pagamento;
- message: o recebimento de uma mensagem;
- qrCode: os dados do QR Code de pagamento;
- transactionId: o ID da transação;
- 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 Pix. Ela será sucedida por outras respostas informando o andamento do processo.

{
  "type": "pix",
  "message": "Iniciando pagamento Pix",
  "status": "started"
}

Mensagem

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

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

QR Code de pagamento

Esta resposta traz a URL contida no QR Code para o fácil pagamento do Pix.

{
  "type": "pix",
  "status": "qrCode",
  "qrCode": "https://url.de.pagamento/",
  "message": "Dados do QR Code para o pagamento do Pix."
}

ID da transação

Esta resposta traz o ID da transação corrente.

{
  "type": "pix",
  "status": "transactionId",
  "transactionId": "0123456789abcdef0123456789abcdef",
  "message": "ID da transação via Pix."
}

Sucesso no pagamento

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

{
  "type": "pix",
  "status": "success",
  "message": "Transação aprovada",
  "value": 100,              // Montante pago                      | Inteiro (> 0).
  "address": "-----",        // Endereço do seller                 | String alfanumérica.
  "sellerName": "-----",     // Nome do seller                     | 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".
  "pixId": "-----",          // ID do Pix                          | String numérica hexadecimal.
  "sellerReceipt": "Pix - Via Cliente 
    MAKEPLACE
    Rua **********, 572           SP
    CNPJ: ***********
    ID: b0c6e370303348479a3592fc4c097ffe   
    VENDA A VISTA              18/03 10:37
    VALOR APROVADO                 R$ 0,01", // Recibo, via do cliente | String alfanumérica.
  "customerReceipt": "MAKEPLACE
    Rua **********, 572           SP
    CNPJ: ***********
    ID: b0c6e370303348479a3592fc4c097ffe
    VENDA A VISTA              18/03 10:37
    VALOR APROVADO                 R$ 0,01
    IDRECEIPT: d26ef86e988f475baaee07304944eb7f
    NSU: E18236120202403181337s07095da0db
    IDTRX: 708fef8e0098460989715f6048452e5f", // Recibo, via do estabelecimento | 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.

⚠️
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": "pix",
  "status": "failed",
  "message": "06 - SERVICO INDISPONIVEL",
  "statusCode": 6
}

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": "pix",
  "status": "finished",
  "message": "Transação finalizada"
}

Cancelamento assíncrono

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

{
  "type": "abort"
}