PROC003 - Fluxo PIX Shipay (falta finalizar) Projeto/Sistema:Shipay - GerencieVendas Versão do Template:1.2 Processo:PROC003 - Fluxo PIX Shipay Versão do Documento:1.0 Responsável(eis): Luís Leite Data: 05/01/2026 1. Introdução Esta documentação visa registrar o processo para a utilização do PIX via Shipay no aplicativo GerencieVendas Processo Envolvidos Dados de Entrada Dados de Saída PROC001 - Configuração Shipay no Serviço Financeiro N/A N/A N/A PROC002 - Configuração do App GV, Serviço Financeiro Configuração do Pix via Shipay Validação no serviço e informação salva na base de dados PROC003 - Fluxo PIX Shipay GV, API Shipay Solicitação de pagamento via PIX  Geração do QR Code via Shipay Processos Relacionados PROC001 - Configuração Shipay no GV PROC002 - Configuração do App Especificação Funcional PROC003 - Fluxo PIX Shipay: Protótipo de Tela: Imagem I - Tela de Pagamento Descrição dos Campos: Campo Tipo Tamanho Obrig. ? Máscara Observações QRCode - - - - - Consultar Pagamento Botão - - - - Regras de Interface: 1. Se configurado o pagamento via PIX Shipay, ao finalizar uma venda com forma de pagamento PIX deve ser renderizado o QR Code (imagem 2). Caso não seja possível ser feita a renderização do QR Code, retornar aviso em tela e voltar para os pagamentos (imagem 1): Não foi possível gerar o QR Code, tente novamente. 1.1 Tela de QR Code - Deve conter as seguintes instruções Pagamento PIX 1. ABRA O APLICATIVO DO SEU BANCO2. ESCOLHA PAGAR COM QR CODE3. APONTE A CÂMERA DO APARELHO PARA O QR CODE 1.2 Botão "Consultar Pagamento" deve consultar o status do pagamento na API da Shipay. PAGAMENTO REALIZADO: deve ser finalizado a tela de QR Code, transferindo o usuario para a tela de finalização da venda. Ou se for o caso, repassar para outros pagamentos eletrônicos caso existirem.PAGAMENTO PENDENTE: Deve ser retornado a mensagem em tela: Pagamento PIX pendente! PAGAMENTO EXPIRADO: Deve retornar o usuário para a tela de pagamentos (imagem 1) e retornar a mensagem: Pagamento PIX expirado! 2. Tempo de espera:Passado 1 minuto sem pagamento, deve ser ficar disponível o botão "retornar", para que seja possível ao usuário voltar a tela anterior. (DEFINIR TEMPO) Regras de Negócio: 1. Botão Consultar Pagamento - Deve realizar a requisição na Shipay para retornar o status do QRCode. A solicitação é feita por meio do GET no endereço https://api-staging.shipay.com.br/order/{order_id}. 2. O app deve realizar consultar automáticas de 20 em 20 segundos (DEFINIR). Questões Técnicas: 1. ALTER TABLE salePayment ADD COLUMN shipayPayment INT CREATE TABLE shipayPayment ( id INTEGER PRIMARY KEY AUTOINCREMENT, createdAt DATETIME, orderId VARCHAR(100), qrCode LONGTEXT, status VARCHAR(30) ) Dados a serem usados para teste:Access Key: bDgEKCRmx0cAynN1Zd-3wgSecret Key: 4hXzdhTTRkhXlhyZSR6yhGI1Ytj8B9EtTuTAZq6ajn6r-_hTUi_ADqRGQ6QxKZbYGbipU3JLmrmxUTJ_Ibx8gAClient Id: aYvu_1ovLdDs5l4GSLFh-XS_WqSMVclJCLRuOkqLLHXmV0gwu0OSOADsRM2D1fZ8ApUkhDKeJYIWtm9yANKJ8FrcZnFkcGM4YcVFgAGKzbqCmdSkyWqab7m_RtndTJE4C13Ye0JkcO01Bc-LXn7RZKN_kn2458wU0U8IJN62T8 Link da Documentação: https://api-staging.shipay.com.br/docs.html URL_BASE: https://api-staging.shipay.com.br Requisição para Geração do QR Code (exemplo): Recurso: POST /order Header: authorization                      Token de autorização x-shipay-order-type           Header necessário somente para pedidos de e-commerce, com valor "e-order" Body { "buyer": { "cpf_cnpj": "88646743063", "email": "[email protected]", "name": "Roberto Dias", "phone": "(11) 99999-9999" }, "callback_url": "https://7d703c9451be72658b3fdc0dcf820946.m.pipedream.net", "items": [ { "ean": "0123456789012", "item_title": "batata doce", "quantity": 2.1626, "sku": "MTC-6110", "unit_price": 3.69 } ], "order_ref": "pedido-qualquer-123", "pix_dict_key": "99999999999", "total": 7.98, "wallet": "mercadopago" } Parâmetros do Corpo da Requisição: Campo Tipo Obrig. Descrição buyer object Informações do comprador. Para criar pedidos com expiração, é obrigatório o envio do nome e do CPF ou CNPJ do comprador.     cpf_cnpj string Sim CPF ou CNPJ da pessoa do comprador (PF ou PJ). Deve ser um CPF ou CNPJ válido.     email string Endereço de e-mail do comprador     name string Sim Nome completo do comprador, no caso de PF. Nome da empresa, no caso de PJ.     phone string Número de telefone do comprador callback_url string Iremos notificar o "callback_url" (quando fornecido na requisição de pagamento), via método POST, informando que houve uma alteração no status do pedido. Por questões de segurança, não iremos informar o novo status nesta requisição. Para isto, o PDV deverá consultar nosso endpoint de status de pedidos (GET /order) quando receber nossa notificação. Para que o callback seja considerado confirmado, o PDV deve responder com HTTP Status 200 em até 2 segundos, que é o tempo de timeout da chamada do callback (ver https://docs.shipay.com.br/faq/#callback). items [ Array of objects (item) Sim Lista de itens do pedido. É obrigatório enviar ao menos um item. No caso de pagamento parcial, ver https://docs.shipay.com.br/faq/#pagamento_parcial.     ean string EAN do item     item_title string Sim Nome do item     quantity number Sim Quantidade do item     sku string SKU do item     unit_price number Sim Valor unitário do item ] order_ref string Sim Número de referência do pedido no sistema de PDV pix_dict_key string Chave PIX da conta bancária que criou o pedido (exemplo: CNPJ, e-mail, telefone, etc.); ver mais em: https://docs.shipay.com.br/faq/#mais_de_um_pix_por_loja. total number Sim Valor total do pedido. Este valor tem que ser igual ao somatório dos valores dos itens wallet string Sim Enum: "mercadopago" "picpay" "ame" "pagseguro" "cielo" "pix"Nome da carteira digital Exemplo de Retorno (JSON): { "deep_link": "null", "order_id": "652f385f-91f4-48cd-8e56-1fc6dec21526", "pix_dict_key": "c7640914-46Fe-4c7d-8664-cf77e8bfeb5c", "pix_psp": "bb", "qr_code": "data:image/png;base64,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", "qr_code_text": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/70fcfe1e-f583-4dc7-87fa-924dba5247eb52040000530398654040.015802BR5915loja da ***6304A161", "status": "pending", "wallet": "mercadopago" } Parâmetros do Retorno: Campo Tipo Descrição deep_link string URL que redireciona o usuário para o aplicativo da carteira digital. No caso de pedidos PIX, esse campo retorna "null". order_id string ID do pedido na Shipay pix_dict_key string Chave PIX da conta bancária que criou o pedido (exemplo CNPJ, e-mail, telefone, etc.). No caso de pedidos com carteiras digitais, este objeto tem o valor "null". pix_psp string Enum: "itau" "original" "santander" "mercadopago" "pagseguro" "bb" "bradesco"Nome do provedor de serviço de pagamentos (PSP) no qual a cobrança PIX foi gerada. No caso de pedidos realizados com carteiras digitais (não PIX), o retorno é "null". qr_code string QR Code em imagem, codificado em Base64 qr_code_text string QR Code em formato de texto (facilita a impressão do QR Code em impressora térmica). No caso de PIX, esse campo é o código utilizado para a funcionalidade "copia e cola". status string Status do pedido/pagamento. Neste caso, o único status possível é: pending - Pedido aberto e ainda não pago ou cancelado wallet string Enum: "mercadopago" "picpay" "ame" "pagseguro" "cielo" "pix"Nome da carteira digital na qual o pedido foi criado. No caso de PIX, o valor desse campo é "pix", independente do provedor de serviço de pagamentos (PSP). Requisição para Consulta de Status (exemplo): Recurso: GET /order/{order_id} Path: order_id                  ID do pedido na Shipay Header: authorization          Example: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MDM4MzI3NjUs...                               Token de autorização Exemplo de Retorno (JSON): { "created_at": "07-10-2020 17:35:53", "external_id": "pedido-qualquer-123", "items": [ { "ean": "123456789012", "item_title": "batata doce", "quantity": 2.1626, "sku": "AA-AAA-000", "unit_price": 3.69 } ], "order_id": "f92d30a8-499d-4f46-bcf2-8d689ad7b5f7", "paid_amount": 7.98, "payment_date": "07-10-2020 17:45:51", "pix_psp": "itau", "status": "cancelled", "total_order": 7.98, "updated_at": "07-10-2020 17:42:06", "wallet": "pix", "wallet_payment_id": "E60736948202104381456C3987yL7T9s" } Parâmetros do Retorno: Campo Tipo Descrição created_at string Data e horário da criação do pedido external_id string Número de referência do pedido no sistema de PDV (igual ao 'order_ref' do POST /order) items [ Array of objects (Item) Lista de itens do pedido     ean string EAN do item     item_title string Nome do item     quantity number Quantidade do item     sku string SKU do item     unit_price number Valor unitário do item ] order_id string ID do pedido na Shipay paid_amount number Valor pago pelo cliente. Utilizado para o PDV verificar se o valor pago é igual ao valor do pedido. payment_date string Data do pagamento (data e horário) pix_psp string Enum: "itau" "original" "santander" "mercadopago" "pagseguro" "bb" "bradesco"Nome do provedor de serviço de pagamentos (PSP) no qual a cobrança PIX foi gerada. No caso de pedidos realizados com carteiras digitais (não PIX), o retorno é "null". status string Status do pedido/pagamento. Neste caso, os status possíveis são: status descrição pending Pedido aberto e ainda não pago ou cancelado pendingv Pedido aberto e ainda não pago ou cancelado (para pedidos com vencimento criados através do POST /orderv) approved Pedido aprovado na carteira digital cancelled Pedido (ainda não pago) cancelado na carteira digital expired Pedido expirado após 60 minutos com status "pending" refunded Pagamento devolvido ao comprador refund_pending Pagamento com devolução solicitada. Status aplicável para PIX e para a carteira digital Cielo Pay pois a ação de devolução não é síncrona nestes casos. No caso de PIX a devolução deve ser efetivada em até 90 segudos após a solicitação. No caso da Cielo Pay, a devolução ocorre sempre no dia seguinte à solicitação. Em ambos os casos, quando a devolução é efetivada, o status na Shipay é alterado para "refunded" total_order number updated_at string wallet string wallet_payment_id string ©SOFTEN SISTEMAS 2026