QRCode

Transação QR Code

int DIRETIVA_CALLBACK TransacaoQRCode(char *pValorTransacao, char *pNumeroCupom, 
                                      char *pNumeroControle, char *pTransactionParamsData)

A solicitação de transação com QR Code através da chamada à função TransacaoQRCode, descrita acima.

Na resposta da chamada à função será preenchido o campo NumeroControle e será devolvido o Status, indicando o resultado da transação:

[ 00 ] indica que não existiram restrições para a efetivação da transação.

[ 11 ] indica que existiram restrições para a efetivação da transação. O sistema de automação deve retornar à rotina de recebimento de valores, pois a transação solicitada não foi autorizada, não sendo válida como forma de pagamento.

O NumeroControle, incluído na resposta, deverá ser armazenado pelo sistema de automação, pois na função de confirmação este número será, obrigatoriamente, utilizado.

Caso a transação seja autorizada, será disponibilizado no diretório parametrizado para os cupons um arquivo contendo o comprovante da operação a ser impresso pela automação. O nome desse arquivo tem o formato NNNNNN.PPP, onde NNNNNN é o NumeroControle e PPP é o número do terminal configurado.

Se a rede autorizadora permitir e se estiver configurada no TEF a impressão de cupom reduzido, além do arquivo acima será liberado um arquivo com o comprovante reduzido no formato RNNNNNN.PPP, onde NNNNNN é o NumeroControle e PPP é o número do terminal configurado. Assim, o comprovante reduzido deverá ser impresso no espaço destinado à mensagem promocional do cupom fiscal e o comprovante normal continuará a ser impresso no cupom vinculado

O PDV deverá verificar a existência do arquivo com o comprovante reduzido após a aprovação da transação. Se o arquivo com o comprovante reduzido estiver disponível, o PDV deverá imprimir no cupom fiscal e em seguida realizar a confirmação do mesmo, antes da impressão do comprovante normal. Se o comprovante reduzido não estiver disponível, a confirmação deverá ser realizada após a impressão do comprovante normal

Ao final da venda, tanto no caso do comprovante reduzido como no comprovante normal, para encerrar a operação deve ser chamada a função FinalizaTransacao.

Campo	Tamanho	Descrição
ValorTransacao	12N	10 inteiros, 2 decimais
NumeroCupom	06N	Número do cupom (fiscal ou não fiscal)
NumeroControle	06N	NSU (número seqüencial único)
TransactionParamsData	variavel A	Esse campo é opcional e somente será utilizado pela rede QRLinx. Quando enviado é esperado que contenha um JSON que será descrito mais abaixo. Pelo campo ser opcional e de tamanho variável, em caso de não envio a automação deve passar NULL ou um buffer vazio nesse campo, em caso de envio a automação deve garantir que ao final da string contendo o json exista o caracter de terminação de string ('\0') caso contrário o Paykit não irá processar o conteúdo recebido

atenção

Os itens descritos abaixo desse alerta são customizações liberadas a partir da release de Paykit 8.22.23.0012 (inclusive)

TransactionParamsData

Json de Exemplo

Clique para expandir e mostrar o JSON de exemplo

{
    "specific_wallets":[
        "PIX",
        "PICPAY"
    ],
    "is_pix_upfront":true,
    "payments":[
        {
            "value:":1.50,
            "payer":{
                "first_name":"Juan",
                "last_name":"Cardoso",
                "email":"jc@provider.com.br",
                "external_code":"0",
                "client_phone":{
                    "area_code":"11",
                    "number":"982232155",
                    "extension":"0"
                },
                "client_identification":{
                    "type":"CPF",
                    "number":"12345678901"
                }
            },
            "expiration_time":100000,
            "withdraw_pix":0,
            "change_pix":0
        }
    ],
    "order_items":[
        {
            "name":"produto1",
            "quantity":1,
            "amount":1.50,
            "subtotal":1.50,
            "discount_value":0.0,
            "add_value":0.0,
            "number_external":"123",
            "ncm":"12345678"
        }
    ]
}

TransactionParamsData

Descrição dos parametros de entradas possíveis, não representa a estrutura do JSON, apenas os atributos possíveis.

Parâmetro	Descrição	Tipo	Obrigatório
is_pix_upfront	Campo para criação de PIX parcelado junto a Paga leve. Caso enviado para operações que não sejam da Paga Leve, o QRCode não será enviado ao PDV.	bool (true/false)	Não
specific_wallets	Informação necessária para criação de cobrança específica.	array	Não
payments	Informações necessárias à realização do pagamento.	objeto	Não
payer	Informações do pagador.	objeto	Não
client_phone	Telefone do pagador	objeto	Não
client_identification	Natureza jurídica do pagador (Pessoa Física/Jurídica). Valores aceitos: "PF" e "PJ".	objeto	Não
order_items	Itens da ordem de venda.	objeto	Não
shipping_address	Endereço para entrega da compra.	objeto	Não

specific_wallets

Este objeto é necessário para criação de uma cobrança específica, ou seja, quando a loja não deseja criar uma cobrança com todas as carteiras disponíveis.

O campo aceita apenas o nome da carteira, caso a loja não possua a informação de quais carteiras estão ativas para transacionar, o PDV poderá utilizar API “Consulta Carteiras”, essa API retorna as carteiras ativas da loja.

O campo é uma lista, pois o PDV pode escolher criar a cobrança apenas com uma carteira ou mais de uma. Quando o PDV for enviar a chamada para criação de cobrança ele deverá enviar uma das opções da lista abaixo:

Clique para mostrar o Objeto

Valores Possíveis
AME
CASH_BERTI
MERCADO_PAGO
PEDE_PRONTO
PICPAY
PIX
VERO

payments

Clique para mostrar o Objeto

Parâmetro	Descrição	Tipo	Obrigatorio
value	Valor total da venda. Campo utilizado apenas nas transações de PIX Saque e PIX Troco	decimal (7,2)	Sim
payer	Informações do pagador.	objeto	Não
expiration_time	Tempo em segundos da expiração da cobrança criada.	integer (10)	Não
withdraw_pix	Representa o valor que o cliente deseja sacar na loja, ou seja, utilizar o PIX SAQUE.	decimal (7,2)	Não
change_pix	Representa o valor que o cliente deseja de troco na transação, ou seja, utilizar o PIX TROCO.	decimal (7,2)	Não

payer

Clique para mostrar o Objeto

Parâmetro	Descrição	Tipo	Obrigatorio
first_name	Primeiro nome do pagador	string (30)	Não
last_name	Último nome do pagador.	string (30)	Não
email	E-mail do pagador.	string (50)	Não
external_code	Código do cliente no PSP de dados do EC.	string (36)	Não
client_phone	Dados do telefone do pagador.	objeto	Não

client_phone

Clique para mostrar o Objeto

Parâmetro	Descrição	Tipo	Obrigatorio
area_code	Código de área do telefone do pagador.	string (4)	Não
number	Número do telefone do pagador.	string (12)	Não
extension	Ramal do telefone do pagador.	string (7)	Não

client_identification

Clique para mostrar o Objeto

Parâmetro	Descrição	Tipo	Obrigatorio
type	Natureza jurídica do pagador. Valores Aceitos: "CPF" para pessoa física; "CNPJ" para pessoa jurídica.	string (5)	Não
number	Número do CPF/CNPJ do pagador. Campo obrigatório para integrações com Paga Leve.	string (15)	Não

order_items

Clique para mostrar o Objeto

Parâmetro	Descrição	Tipo	Obrigatório
name	Descrição do item.	string (150)	Não
quantity	Quantidade do item.	decimal (7,2)	Não
amount	Valor total do item	decimal (7,2)	Não
subtotal	Subtotal do item.	decimal (7,2)	Não
discount_value	Valor do desconto concedido.	decimal (7,2)	Não
add_value	Valor adicionado à venda. Ex.: frete, embalagem.	decimal (7,2)	Não
number_external	Código do item.	string (14)	Não
ncm	Natureza jurídica do pagador (Pessoa Física/Jurídica).	string (8)	Não

shipping_address

Clique para mostrar o Objeto

Parâmetro	Descrição	Tipo	Obrigatório
street	Descrição do logradouro.	string (60)	Não
postal_code	CEP do logradouro.	string (10)	Não
number	Número do logradouro	string (15)	Não
complement	Complemento do endereço.	string (40)	Não
state	Estado/UF do endereço.	string (2)	Não
district	Bairro do logradouro	string (60)	Não
city	Código do item.	string (14)	Não
ncm	Cidade do logradouro.	string (60)	Não

OBS: Preencher campos conforme documentado nas Convenções do manual, documentadas na [página inicial]../Introducao.md.

OBS: Para realização da confirmação da transação deverá ser realizada chamada à função ConfirmaCartao, e para o desfazimento da transação deverá ser realizada chamada à função DesfazCartao. Para maiores detalhes, consulte a página Confirmação e Desfazimento de Transações.

PIX Troco

No caso do Pix Troco, a dinâmica é idêntica, com a diferença que o saque de recursos em espécie acontece junto com a realização de uma compra no agente de saque. Nesse caso, o Pix é feito pelo valor total (compra + saque). O extrato do cliente evidenciará o valor correspondente ao saque e o valor correspondente à compra.

Importante que para gerar um PIX Troco automação deverá enviar o campo “payments.value” conforme a compra realizada pelo cliente, e no campo “payments.change_pix” informar o valor que o cliente deseja sacar/receber de troco. Por fim o campo “order_items.amount” representa a soma dos dois campos acima na criação da cobrança.

Segue abaixo o campo obrigatório na criação da cobrança PIX Troco:

Clique para mostrar o Objeto

Parâmetro	Descrição	Tipo	Obrigatorio
change_pix	Representa o valor que o cliente deseja de troco na transação, ou seja, utilizar o PIX TROCO.	decimal (7,2)	Sim

Não é permitido gerar uma cobrança de PIX Saque e PIX Troco em conjunto, caso os campos específicos sejam enviados o QRLinx retornará erro na criação da cobrança.

PIX Saque

O Pix Saque permitirá que todos os clientes de qualquer participante do Pix realizem um saque em um dos pontos que ofertar o serviço. Estabelecimentos comerciais, redes de caixas eletrônicos (ATMs) compartilhados e os próprios participantes do Pix, por meio de seus ATMs próprios, poderão ofertar o serviço. Para ter acesso aos recursos em espécie, basta que o cliente faça um Pix para o agente de saque, em dinâmica similar à de um Pix normal, a partir da leitura de um QRCode mostrado ao cliente ou a partir do aplicativo do prestador do serviço.

Importante que para gerar um PIX Saque automação deverá enviar o campo “payments.value” zerado, já que não está ocorrendo uma compra e sim apenas um saque junto ao estabelecimento.

Segue abaixo o campo obrigatório na criação da cobrança PIX Saque:

Clique para mostrar o Objeto

Parâmetro	Descrição	Tipo	Obrigatorio
withdraw_pix	Representa o valor que o cliente deseja sacar na loja, ou seja, utilizar o PIX SAQUE.	decimal (7,2)	Sim

Não é permitido gerar uma cobrança de PIX Saque e PIX Troco em conjunto, caso os campos específicos sejam enviados o QRLinx retornará erro na criação da cobrança.

Link de Pagamento QRLinx

Ao realizar um pagamento via a rede QRLinx, esta disponibilizará um link de pagamento que pode ser disponibilizado ao cliente final via whatsapp, e-mail, SMS ou de alguma outra forma que a automação encontre facilidade de enviar e disponibilizar mais um canal de pagamento para seu cliente. Esta informação será enviada para a automação através da Callback Informações Transacionais.

Transação Generica QRCode

const char* OperacoesGenericasQR(char *pDadosJson, int *status)

Essa integração com o Paykit visa disponibilizar métodos de consultas para a automação sobre as transações de QR, e tem por objetivo receber da automação um JSON com os dados da integração bem como o tipo de consulta a ser realizada, e o Paykit disponibilizará um objeto JSON de retorno compatível com a solicitação feita.

O valor retornado para a automação não aceita modificações e seu conteúdo deve ser copiado pra um atributo interno do software consumidor do Paykit, sendo que no inicio da proxima solicitação para o Paykit o buffer será limpo.

O status da transação (se bem sucedido ou não) será retornado para a automação através do parametro status.

Os inputs e outputs de cada possibilidade de interação com este método, estarão descritos abaixo:

Carteiras Ativas para a loja no QRLinx

Automação poderá consultar as carteiras que estão disponíveis para uma determinada loja, essa consulta se faz necessária na geração de uma cobrança específica, pois assim o PDV poderá solicitar a geração do QRCode apenas para as carteiras desejadas.

Clique para expandir e mostrar o exemplo de Requisição e Reposta

Exemplo Requisição

{
    "methodRequest": 2
}

Sendo, methodRequest um valor fixo para identificar essa requisição.

Exemplo Resposta

{
    "success":true,
    "message":"Carteiras retornadas com sucesso",
    "data":[
        {
            "cnpj":"22896431000110",
            "name":"Picpay Servicos S.A",
            "trading_name":"PicPay",
            "logo_link":"https://static.provider.com.br/images/logos/LogoPicPay.png",
            "logo_link_download":"https://static.provider.com.br/images/logos/LogoPicPay.png",
            "specific_wallet":"PICPAY"
        },
        {
            "cnpj":"00000000000000",
            "name":"Pix",
            "trading_name":"Pix",
            "logo_link":"https://static.provider.com.br/images/logos/LogoPix.jpg",
            "logo_link_download":"https://static.provider.com.br/images/logos/LogoPix.jpg",
            "specific_wallet":"PIX",
            "integrationTypePixModel":{
                "id":7,
                "name":"Pagar.me",
                "priority":"Primary"
            }
        },
        {
            "cnpj":"00000000000000",
            "name":"Pix",
            "trading_name":"Pix",
            "logo_link":"https://static.provider.com.br/images/logos/LogoPix.jpg",
            "logo_link_download":"https://static.provider.com.br/images/logos/LogoPix.jpg",
            "specific_wallet":"PIX",
            "integrationTypePixModel":{
                "id":5,
                "name":"Santander",
                "priority":"Secondary"
            }
        }
    ]
}

Consulta Parcelamento (Paga Leve - QRLinx)

Na integração com o PSP Paga Leve existe uma integração de PIX com a opção do parcelamento, devido a isso os objetos payer, client_identification, is_pix_upfront passa a ser obrigatório para a TransacaoQRCode, e o client_phone um parametro recomendado.

Para que a loja consulte se o parcelamento está disponivel para o cliente em questão a automação deve consumir este método, assim o lojista poderá oferecer um parcelamento de pix antes da finalização da transação:

Clique para expandir e mostrar o exemplo de Requisição e Reposta

Exemplo Requisição

{
    "methodRequest": 1,
    "value":1.50,
    "document":"12345678901"
}

Sendo, methodRequest um valor fixo para identificar essa requisição, value o valor da transação e document o CPF do cliente.

Exemplo Resposta

{
    "sucesso":true,
    "message":"Consulta realiza com sucesso",
    "data":{
        "status":"APPROVED"
    }
}

Essa consulta possui apenas duas mensagens de retorno “Approved” ou “Declined”, assim a loja terá a informação se o PIX parcelado está aprovado ou não para o seu cliente.

Caso o cliente do lojista seja aprovado no pagamento do PIX parcelado automação deverá enviar o campo is_pix_upfront com o valor false. O QRLinx retornará no campo “payment_link” o link de pagamento da Paga Leve que poderá ser exibido ou enviado para o cliente concluir o processo de pagamento.