Blog

Criando uma cobrança via PIX

Após inicializar a comunicação com o PIX, de acordo com o padrão de cada banco/fornecedor você deve montar um mapa com os dados da cobrança.

  • CHAVE (Letras) – Chave PIX de quem irá receber o dinheiro, será fornecida pelo banco (Chave DICT do recebedor). No ambiente de homologação informe uma das chaves de testes [Obrigatório];
  • TRANSACAO_ID (Letras) – Identificador único da transação (tx_id) conteúdo letras e números com até 35 caracteres [Obrigatório];
  • DEVEDOR_NOME (Letras) – Nome da pessoa que está sendo cobrada/solicitada [Obrigatório];
  • DEVEDOR_CPF (Letras) – Número do CPF do devedor quando for pessoa fisica [Obrigatório se for PF];
  • DEVEDOR_CNPJ (Letras) – Número do CNPJ do devedor quando for pessoa jurídica [Obrigatório se for PJ];
  • VALOR_ORIGINAL (Fracionado) – Valor em reais (R$), com até 02 (dois) digitos [Obrigatório];
  • SOLICITACAO_PAGADOR (Letras) – Texto que será apresentado ao pagador;
  • INFO_ADICIONAIS (Variante) – Mapa com nome/valor em Letras de informações adicionais da cobrança;
  • CALENDARIO_EXPIRACAO_SEGUNDOS (Inteiro) – Por quanto tempo a cobrança ficará disponível para pagamento (EX: 3600 para 60 minutos), usado quando a cobrança é instantânea;
  • CALENDARIO_DH_EXPIRACAO (Data) – Substitui a informação dos segundos por uma data e hora específica. O tempo será calculado baseado na hora atual do servidor onde a API esta sendo executada. Isso pode gerar diferenças em relação ao servidor do banco, em especial diferença por configuração de fuso horários, ou mera diferença de horário entre os servidores. Quando informar esse campo não deve ser informado o campo “CALENDARIO_EXPIRACAO_SEGUNDOS“.
  • (Disponível a partir da versão publicada após 19/05/2022.)

Após montar o mapa com os dados da cobrança você pode chamar a função “PIX – Criar Cobrança” passando os seguintes parâmetros:

  1. Conexão (Retorno da função “PIX – Inicializar“);
  2. ID da transação (Letras) – Deixe em branco para gerar um novo automáticamente;
  3. Dados da cobrança (Variante) – Mapa com os dados descritos acima. Opcionalmente você pode passar o JSON (Letras) já pronto, seguindo o padrão do PIX definido pelo BCB;

O retorno da função será um Variante com um Mapa com os dados do PIX gerado. Este mapa poderá conter além dos itens descritos no envio também os seguintes itens:

  • SUCESSO (Lógico) – Indica se a operação foi concluída com sucesso;
  • QRCODE_TEXTO – Texto do QrCode para pagamento;
  • REVISAO_NUMERO – Número da revisão da cobrança;
  • SITUACAO (Letras) – Texto indicando a situação da cobrança:
    • ATIVA – a cobrança está disponível, porém ainda não ocorreu pagamento;
    • CONCLUIDA – a cobrança encontra-se paga. Não se pode alterar e nem remover uma cobrança cujo status esteja “CONCLUÍDA”;
    • EM_PROCESSAMENTO – liquidação em processamento;
    • NAO_REALIZADO – indica que a devolução não pode ser realizada em função de algum erro durante a liquidação, como por exemplo, saldo insuficiente.;
    • DEVOLVIDO – cobrança com devolução realizada pelo Sistema de Pagamentos Instantâneos (SPI);
    • REMOVIDA_PELO_USUARIO_RECEBEDOR – foi solicitada a remoção da cobrança; a critério do usuário;
    • REMOVIDA_PELO_PSP – recebedor, por conta de algum critério, solicitou a remoção da cobrança.
  • DEVOLUCOES_VALOR (Fracionado) – Valor total das devoluções se houver;
  • ERRO_DESCRICAO (Letras) – Texto descritivo do erro (se houve falha);
  • _RESPOSTA (Letras) – Texto integral retornado pelo servidor do banco;
  • _HTTP_STATUS_MESSAGE (Letras) – Texto descritivo da situação da comunicação HTTPS;
  • _HTTP_STATUS_CODE – Código HTTP da resposta do servidor do PSP. Zero indica que não houve comunicação (causada por um firewall ou falha da Internet por exemplo).

O preenchimento dos dados acima irá depender da situação e histórico da cobrança.

Utilize esse retorno para gerar a imagem do QRCode através da função “PIX – Gerar QrCode“, para obter o QR Code em texto obtenha o elemento “QRCODE_TEXTO” no mapa retornado pela função “PIX – Criar Cobrança“.

Salve o JSON original retornado pela servidor obtendo o item “_RETORNO” do mapa retornado pela função “PIX – Criar Cobrança“, bem como o item “TRANSACAO_ID” para posterior consulta da situação do PIX.