Home

Perguntas Frequentes

Pagamento Parcial

Access Token

Dados do Comprador (Buyer)

Hierarquia de Lojas e Caixas

Mais de um PIX por Loja

Validação de Payload

Pagamento_Parcial

Pergunta: [P1] Ocorre muito dos clientes pagarem um valor no dinheiro e o restante com outra forma de pagamento (carteira digital, por exemplo). Nesse caso, como eu teria que implementar o processo? Teria que alterar o valor dos itens na criação do pedido (order)? Preciso me preocupar se a soma do valor dos itens bate com o valor total pago pelo cliente na carteira digital?

Resposta: Para esse caso, nossa recomendação é:

Mandar o valor do pagamento em carteira digital em apenas um item, com a descrição “Pagamento Parcial em Carteira Digital”;

Voltar

Token

Pergunta: [T1] Qual é a validade do Access Token?

Resposta: Atualmente são 3 dias, mas pode ser modificado a qualquer tempo. Recomendamos fortemente a implementação do Refresh Token.

Voltar

Buyer

Pergunta: [B1] Qual a vantagem em enviar os dados do comprador (buyer) no pedido?

Resposta: Se a carteira for PicPay e o CPF for informado, o cliente recebe um push notification em seu celular. Clicando no push, o cliente já é redirecionado para a tela de pagamento do app PicPay e não precisa ler o QR Code para pagar o pedido.

Voltar

Order

Pergunta: [O1] Em relação aos dados informados no pedido (order), existe alguma limitação de caracteres nos campos exigidos?

Resposta: Sim. O limite do campo “order_ref” são 30 caracteres. O limite do campo “item_title” são 100 caracteres.

Voltar

Pergunta: [O2] Sistemas de PDV de postos de combustíveis utilizam 3 (três) casas decimais no valor unitário do produto. Considerando que a Shipay só aceita 2 (duas) casas decimais no campo “unit_price” do objeto “items”, como enviar o objeto “items” nesses casos?

Resposta: No caso de postos de combustíveis ou qualquer outra situação onde se utilizam mais do que 2 (duas) casas decimais no valor unitário do produto, recomendamos que seja enviado um único item (“quantity”: 1), com o valor unitário (“unit_price”) igual ao valor total do produto. Se possível, enviar a descrição do item com a quantidade e valor unitário do mesmo para melhorar a experiência do usuário.

Exemplo:

	"items": [
		{
			"item_title": "Etanol R$ 2.42 x 34.773 L ",
			"unit_price": 84.15,
			"quantity": 1
		}
	]	

Voltar

E-commerce

Pergunta: [E1] A solução da Shipay suporta e-commerce?

Resposta: Sim, é possível utilizar a integração da Shipay para e-commerce. Sobre isso, é importante ressaltar alguns pontos:

a) No caso de pedidos de e-commerce, é necessário acrescentar o header customizado “x-shipay-order-type”: “e-order” no POST /order

b) Lojas de e-commerce devem cadastrar apenas um caixa no painel Shipay e esse caixa deve ser do tipo e-commerce.

Voltar

Callback

Pergunta: [C1] A Shipay envia callback quando os pedidos são pagos? Como funciona?

Resposta: Sim. No body do POST /order, existe um objeto não obrigatório chamado “callback_url”. Se o objeto “callback_url” for informado no body do request, a Shipay enviará um POST com o “order_id” do pedido em todo evento de alteração de status do pedido na Shipay para a url informada. Após o recebimento do callback, a aplicação integrada à Shipay deverá consultar o status do pedido na Shipay através do GET /order/{order_id}.

Importante 1: No POST do callback, a Shipay enviará um header chamado “x-shipay-secretkey” contendo o “secret_key” do cliente que criou o pedido. Recomendamos fortemente que a aplicação do PDV integrado valide que o header “x-shipay-secretkey” é igual à “secret_key” do cliente, garantindo que o callback foi enviado pela Shipay.

Importante 2: Só notificamos URLs “https”. URLs de callback “http” não serão notificadas.

Exemplo do POST de callback enviado pela Shipay:

Método: POST
URL: callback_ulr informada no POST /order
Headers: 
"x-shipay-secretkey": "9HnN91frrqSp9Onb_zF4gJX3a5Wil3SwYiG_9JecLrZzuO8unHi5xCpBxjo6GlWzvA-rSs0f1LBBd1OGKFqx9f"

Body:

{
  "order_id": "9894fb04-9b1e-41e5-9cce-c33b8130a504"
}

Voltar

Pergunta: [C2] Existe algum mecanismo de retentativas?

Resposta: Sim. Caso a comunicação com a url informada falhe, a Shipay tentará 3 vezes em um intervalo de 2, 4 e 6 segundos respectivamente. Se todas as tentativas falharem, a comunicação não acontece e o PDV deve vir fazer suas consultas pelo endpoint GET /order.

Voltar

Pergunta: [C3] Quais status que a Shipay aceita como válidos?

Resposta: Consideramos que o callback foi recebido com sucesso quando recebemos os status_code: 200, 201 ou 204.

Voltar

Deeplink

Pergunta: [D1] Existe a possibilidade de gerar um link de pagamento ao invés de somente o Qr Code?

Resposta: Sim. No caso do pix, o campo “qr_code_text” é o “código” utilizado no pix copia e cola. No caso das carteiras digitais, o campo “deep_link” retorna um link que direciona o usuário para a tela de pagamento no aplicativo da carteira digital. Ambos os objetos são retornados no POST /order.

Importante: O “deep_link” da Ame não é legível para smartphones que utilizam Android. Nós desenvolvemos uma solução de contorno para que o link seja lido também por smartphones que utilizam Android e soluciona esse problema:

Solução de Contorno para deeplink da Ame: Basta concatenar a string abaixo no deeplink da Ame.

String a ser concatenada: https://deeplink.shipay.com.br/
Exemplo do deeplink Ame “concatenado”: https://deeplink.shipay.com.br/amedigital://payment?qrcode=eyJ0eXBlIjoiUEFZTUVOVCIsIm9yZGVyX2lkIjoiMGNlODQ4NzMtYWViZC00NWYxLThlYjEtMjNlYjNkMjhmZDQ2In0=
Essa solução funciona no IOS também.

Voltar

Hierarquia

Pergunta: [H1] Como funciona a estrutura hierárquica de Estabelecimento, Lojas e Caixas dentro da Shipay?

Resposta: Segue abaixo como funciona atualmente. Para mais detalhes sobre como era antes, e como está agora, clique aqui.

Voltar

Mais_de_um_PIX_por_Loja

Pergunta: [M1] Como faço para ter a possíbilidade de receber com mais de uma conta pix na mesma loja?

Resposta: Atualmente é possível associar mais de um pix na mesma loja, com isto, temos a seguinte visualização na página de detalhes da loja:

O pix padrão é o pix para o qual será enviada a transação quando for enviado somente o campo "wallet": "pix" no body do POST /order.

Caso queira enviar o pedido para outra conta pix, temos duas possíveis soluções:

Trocar o pix padrão no painel Shipay;
Enviar o campo "pix_dict_key" no body do POST /order, informando diretamente com qual chave pix deseja realizar a transação.

Obs.1: A(s) "pix_dict_key" da(s) conta(s) é(são) retornada no GET /v1/wallets.

Obs.2: O mercado pago é o único PSP em que a Shipay não salva a chave pix; com isto, a solução dois não é viável para pix do mercado pago, somente a solução 1. Sugestão: Deixar o pix do mercado pago como padrão no painel Shipay, e usar o campo "pix_dict_key" quando for necessário transacionar com os demais pix associados.

Voltar

Validação_de_payload

Pergunta: [M1] Devo validar os campos da payload de resposta da Shipay e travar o sistema caso novos parâmetros sejam inseridos?

Resposta: Não recomendamos que o sistema trave sua rotina caso identifique um campo desconhecido nas payloads de resposta da Shipay. Estamos em constante aprimoramento e evolução e nosso compromisso é jamais remover um campo da payload, mas eventualmente incluiremos novos campos/parâmetros para auxiliar os parceiros que estão integrados com a Shipay.

Voltar