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 BANCO
2. ESCOLHA PAGAR COM QR CODE
3. 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:

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-3wg
Secret Key: 4hXzdhTTRkhXlhyZSR6yhGI1Ytj8B9EtTuTAZq6ajn6r-_hTUi_ADqRGQ6QxKZbYGbipU3JLmrmxUTJ_Ibx8gA
Client 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

PROC003 - Fluxo PIX Shipay (falta finalizar)

1. Introdução

Processos Relacionados

Especificação Funcional

PROC003 - Fluxo PIX Shipay:

Protótipo de Tela:

Descrição dos Campos:

Regras de Interface:

Regras de Negócio:

Questões Técnicas:

Requisição para Geração do QR Code (exemplo):

Requisição para Consulta de Status (exemplo):

No Comments

**PROC003 - Fluxo PIX Shipay:**