Notificações automática de status (Retorno automático) - PIX

A PagHiper irá notificar a notification_url quando declarada no momento da requisição de emissão do título. A notificação consiste no envio de um post simples para a notification_url com algumas informações iniciais (apiKey, notification_id, transaction_id, notification_date, source_api). Ao receber essa requisição o servidor do lojista deve retornar as mesmas informações acrescida do token do lojista para o endpoint https://pix.paghiper.com/invoice/notification/ no formato JSON.

640

A PagHiper irá exibir os detalhes da notificação em formato json após receber o conteúdo do post inicial + token do lojista.
Caso a loja não responda a notificação, será feito outras tentativas a cada 2 horas durante 24 horas.

Endpoint
https://pix.paghiper.com/invoice/notification/
Protocolo / Tipo de Requisição
HTTPS / POST
Autenticação
Para utilizar o endpoint será necessário possuir credencias apiKey e token.
Esses dados estão disponíveis no painel de credenciais no PagHiper.

Pagina de credenciais: https://www.paghiper.com/painel/credenciais/
Tipo de Conteúdo (JSON)
O header “Accept” deverá ser enviado contendo o formato da mensagem desejado.

"Accept", "application/json"

Importante: Este procedimento é explicado em detalhes no item: 11.
Configurando o Formato das Mensagens.

Fluxo 1 - Post simples (não é json) enviado da PAGHIPER para a notification_url do lojista com informações iniciais sobre a notificação.

apiKey=apk_12345678-OiCWOKczTjutZazRSfTlVBDpHFxpkdzz&
transaction_id=BPV661O7AVLORCN5&
notification_id= W6QM6MORZW4KUENC0NU6ERN0AULFUIUROKEU72L6ZQQT4E6521CGT0G3V2JQKDI9&
notification_date=2017-07-25 11:21:19
source_api=https://pix.paghiper.com

Fluxo 2 – Resposta da loja no formato JSON com os dados inicias das notificações + token do lojista

{
"token":"ZKSRNZGN8VW3MWN68UX8DDMDJR578N9772YU2FHABDEX",
"apiKey":"apk_12345678-OiCWOKczTjutZazRSfTlVBDpHFxpkdzz",
"transaction_id":"BPV661O7AVLORCN5",
"notification_id":"W6QM6MORZW4KUENC0NU6ERN0AULFUIUROKEU72L6ZQQT4E6521CGT0G3V2JQKDI9"
}

Fluxo 3 – Resposta da PAGHIPER no formato JSON, exibindo todo o conteúdo da notificação.

{
   "status_request":{
      "result":"success",
      "response_message":"notification_id encontrada",
      "transaction_id":"1MW2ZLWYAJE7FJ96",
      "order_id":"pix_01",
      "created_date":"2020-12-07 14:22:40",
      "status":"pending",
      "payer_email":"[email protected]",
      "payer_name":"Weslley",
      "payer_cpf_cnpj":"20110153000107",
      "status_date":"2020-12-07 14:22:40",
      "value_cents": "400",
      "value_fee_cents": "149",
      "discount_cents": "100",
      "shipping_price_cents": "250",
      "value_cents_paid": "0",
      "pix_code":{          	
        "qrcode_base64":"iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAACxElEQVR4Xu2Xy20kMQxExUTE/LPYUKREpK1XMjDyHIw9uLmXEXr6o34GCmSRbLf98/rT3nfe1gc46wOc9QHO+jdgtBace66uX+OYZ7MMmDpGjxWrx+g95ooRbFYCejzyhLTwo8/FgB54SbgIVM//ACByzqUMrfgKXS2gY67UGx3KVu4R3iwE8Od8X++ufn//ywBLPlWgpEuXlUNCz6oCRgsiI6NKWmCcJoSA1QHyhlKl6k3ddkyrl05aHTCwScqkAyJ1Hr3RSCoBapUMhdU1WUVPaqaFgFQSn1ATc6CkT0I3TaUMkKK0V4/S49h5LmWAZ0ly7RQsCVNrfwWqABiERmeblUZGL2W4VgLkiDFC9SplDBaaSSUgBH0SZ5lOWd7JKgA00SSPiSZ5pElla7IQ2HgGTaoaakaSVcB38T4PqGi0R9OQVuQh+S7eCsA9Q4UyCY+6iXKG0iwEhChPtLHNfEMjN/uK5OPA9ERxdPxmuILH5agCYFK0vKObJ43VeCXgoMin1jaN0NRexVsAbL7sGtP0JIuy/ZasAkA3cilxUYBWYBc5dl3Jeh6gXdDKV8e72tdGuJALgaSFUL30MtdQ51+SrATkDh3JeSpjsqvCtS+RzwNO0UIZ1rFb0sILAT0oOkkjccX4sX1P1tOARG6qN0ElVLfyzZWsAmCxKasGv8VXL+VzB6oASDUNeVba0k7ZOPgu3gKgBy4lSuqei0Ju3EchwHc26ZG04IdA/iwLga8QdWpGucK9tJE7ks8DCo2UuXDtE+wj6CXyeYAOZr94tKmOWridVwIsjOqLhzvlfIksAIYVLQZJEJ/BZCFWhcCkhdExNFw3w+SIzFKAQT6UoX6SJfuge1YDgwZCF0+ShZEbl1pApbtJ0OQbR2g6V3XA5hUN3XtU0tFcCNi01njqlrGmqnElVQE/rQ9w1gc46wOc9QvAX+6y+aZjvEg1AAAAAElFTkSuQmCC",
        "emv":"00020101021226770014BR.GOV.BCB.PIX2555api.itau/pix/qr/v1/ce7f9743-6575-485a-86da-a0f56cf136565204000053039865802BR5925PAGHIPER SERV ONLINE EIRE6009SAO PAULO62070503***630409AD",        
        "pix_url":"https://pix.paghiper.com/qrcode/180068c7/HF97T5SH2ZQNLF6Z/30039",
        "bacen_url":"https://pix.bcb.gov.br/qr/MDAwMjAxMDEwMjEyMjY3NzAwMTRCUi5HT1YuQkNCLlBJWDI1NTVhcGkuaXRhdS9waXgvcXIvdjEvY2U3Zjk3NDMtNjU3NS00ODVhLTg2ZGEtYTBmNTZjZjEzNjU2NTIwNDAwMDA1MzAzOTg2NTgwMkJSNTkyNVBBR0hJUEVSIFNFUlYgT05MSU5FIEVJUkU2MDA5U0FPIFBBVUxPNjIwNzA1MDMqKio2MzA0MDlBRA=="
      },
      "due_date":"2020-12-09",
      "due_datetime":"2020-12-09 14:37:59",  
      "num_cart_items": "2",
      "items":[
         {
            "item_id":"1",
            "description":"teste 01",
            "quantity":"1",
            "price_cents": "250"
         },
         {
            "item_id":"6FDFJPTG4YZ499W",
            "description":"Frete",
            "quantity":"1",
            "price_cents": "250"
         }
      ],
      "http_code": "201"
   }
}

Especificações dos campos que a paghiper irá enviar na primeira etapa

Campo Tamanho Tipo Descrição
apiKey Até 50 caracteres Texto Campo composto de números, letras, traços e hífen.
Sempre começa por apk_

Exemplo: apk_48040241- OqCWOKczcjutZaFRSfTlVBDpHFXpkdzz

Utilizado para identificar o vendedor
transaction_id 16 Texto Toda transação possui o transaction_id, utilizado para identificar a transação em questão.
notification_id Até 128 caracteres Texto Código único utilizado para identificar a notificação.
notification_date   DATETIME Data em que a notificação foi gerada.
Atenção: A notificação ficará disponível para consulta por até 30 dias a partir dessa data.
source_api 24 Texto Composto pela url inicial da API que criou transação.
Exemplo: https://pix.paghiper.com (sinaliza que é uma notificação da API de um PIX)

Especificações dos campos que devem ser enviados em resposta a notificação.

Campo Tamanho Tipo Descrição
apiKey Até 50 caracteres Texto Campo composto de números, letras, traços e hífen.
Sempre começa por apk_

Exemplo: apk_48040241- OqCWOKczcjutZaFRSfTlVBDpHFXpkdzz

Utilizado para identificar o vendedor
token Até 128 caracteres  Texto Token individual para cada vendedor. Utilizado para validar a solicitação e não deve ser compartilhado com terceiros.

Para obter o token acesse:
https://www.paghiper.com/painel/token/
transaction_id 16 Texto Toda transação possui o transaction_id, utilizado para identificar a transação em questão.  
notification_id  Até 128 caracteres Texto Código único utilizado para identificar a notificação.

Especificações dos campos da mensagem de resposta da PAGHIPER

Campo Tamanho Tipo Descrição
result Até 8 caracteres Texto Campo que identifica se houve êxito na busca e se os parâmetros estão corretos.

Esperado:
success
reject

response_message Até 128 caracteres Texto Descreve em detalhes se houver algum erro ou se a transação foi encontrada.

verificar item mensagens de retorno

transaction_id 16 Texto Toda transação possui o transaction_id, utilizado para identificar a transação em questão.

order_id Até 64 caracteres Texto Código de referência da venda

Esse código foi atribuído pelo vendedor no momento da requisição.


created_date   Datetime Data em que a transação foi criada

Exemplo esperado:
2017-07-14 21:21:02

paid_date   Datetime Data em que a transação foi Aprovada

Exemplo esperado:
2017-07-14 21:21:02

status Até 16 caracteres Texto

Retorna o status da transação no momento em que a notificação foi gerada.

Esperado:

status significado
pending aguardando
canceled cancelado
completed completo
paid aprovado
processing analise
refunded estornado
payer_email Até 255 caracteres Texto e-mail do cliente pagador
payer_name Até 255 caracteres Texto Nome ou Razão social do cliente pagador
payer_cpf_cnpj Até 14 caracteres Texto CPF ou CNPJ do pagador

apenas os números do cpf ou cnpj

payer_phone Até 15 caracteres Numérico Número de telefone ou celular do cliente
Exemplo: 1140638785

due_date   DATE Data do vencimento do Pix

Exemplo esperado
2017-07-12

due_datetime   Datetime Data do vencimento do Pix com horas

Exemplo esperado
2017-07-12 14:37:59

value_cents  Até 15 caracteres Numérico Valor final da transação em centavos,
exemplo:

R$ 100,00 será representado por: 10000

value_fee_cents Até 15 caracteres Numérico  Tarifa da transação em centavos

exemplo:
R$ 2,79 será representado por: 279

value_cents_paid  Até 15 caracteres Numérico Valor final da transação em centavos, exemplo:

R$ 100,00 será representado por: 10000

Esse campo só será retornado se a transação estiver com status de paid, ou completed

discount_cents Até 15 caracteres Numérico Desconto total aplicado ao título em centavos

exemplo:
R$ 9,99 será representado por: 999

shipping_price_cents Até 15 caracteres Numérico  Valor do frete em centavos

exemplo:
R$ 19,50 será representado por: 1950

num_cart_items   Numérico Quantidade de itens enviados no momento da requisição de emissão do título.

Detalhes de items
item_id Até 64 caracteres Texto Código do item

Útil para identificar por exemplo, o código do produto.

description Até 255 caracteres Texto Descrição do item

Útil para identificar o nome do produto ou serviço

quantity Até 15 caracteres Numérico Quantidade do item

Define a quantidade de cada item.

price_cents Até 15 caracteres Numérico Valor unitário do item em centavos

Define o valor unitário de cada item.
Exemplo: Determinado item tem o preço definido em R$ 1.901,95, será informado: 190195 (total em centavos)

Detalhes do pix_code
qrcode_base64 Esperado entre 1000 a 3000 caracteres Texto Imagem Codificada em Base64

Exemplo:
iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAACxElEQVR4Xu2Xy20kMQ
xExUTE/LPYUKREpK1XMjDyHIw9uLmXEXr6o34GCmSRbLf98/rT3nfe1gc46wOc9QHO
+jdgtBace66uX+OYZ7MMmDpGjxWrx+g95ooRbFYCejzyhLTwo8/FgB54SbgIVM//AC
ByzqUMrfgKXS2gY67UGx3KVu4R3iwE8Od8X++ufn//ywBLPlWgpEuXlUNCz6oCRgsi
I6NKWmCcJoSA1QHyhlKl6k3ddkyrl05aHTCwScqkAyJ1Hr3RSCoBapUMhdU1WUVPaq
aFgFQSn1ATc6CkT0I3TaUMkKK0V4/S49h5LmWAZ0ly7RQsCVNrfwWqABiERmeblUZG
L2W4VgLkiDFC9SplDBaaSSUgBH0SZ5lOWd7JKgA00SSPiSZ5pElla7IQ2HgGTaoaak
aSVcB38T4PqGi0R9OQVuQh+S7eCsA9Q4UyCY+6iXKG0iwEhChPtLHNfEMjN/uK5OPA
9ERxdPxmuILH5agCYFK0vKObJ43VeCXgoMin1jaN0NRexVsAbL7sGtP0JIuy/ZasAk
A3cilxUYBWYBc5dl3Jeh6gXdDKV8e72tdGuJALgaSFUL30MtdQ51+SrATkDh3JeSpj
sqvCtS+RzwNO0UIZ1rFb0sILAT0oOkkjccX4sX1P1tOARG6qN0ElVLfyzZWsAmCxKa
sGv8VXL+VzB6oASDUNeVba0k7ZOPgu3gKgBy4lSuqei0Ju3EchwHc26ZG04IdA/iwL
ga8QdWpGucK9tJE7ks8DCo2UuXDtE+wj6CXyeYAOZr94tKmOWridVwIsjOqLhzvlfI
ksAIYVLQZJEJ/BZCFWhcCkhdExNFw3w+SIzFKAQT6UoX6SJfuge1YDgwZCF0+ShZEb
l1pApbtJ0OQbR2g6V3XA5hUN3XtU0tFcCNi01njqlrGmqnElVQE/rQ9w1gc46wOc9Q
vAX+6y+aZjvEg1AAAAAElFTkSuQmCC

Pode exibir a imagem para o cliente sem a necessidade de conversão utilizando como base o codigo html <img src="data:image/png;base64, {{qrcode_base64}}" />
emv Até 255 caracteres Texto Em resumo permite copiar o Código QrCode

Exemplo:
00020101021226770014BR.GOV.BCB.PIX2555api.itau/pix/qr/v1/
ce7f9743-6575-485a-86da-a0f56cf136565204000053039865802BR5925
PAGHIPER SERV ONLINE EIRE6009SAO PAULO62070503***630409AD
pix_url Até 255 caracteres Texto Url onde é possível visualizar o Pix

Exemplo:
https://pix.paghiper.com/qrcode/113d8222fb
24998baa2d48b015fd9de227403a977943ffe5f30f
beb5d01c9869aa6451a2b1ec622622cc8c4461b88e16c1d548
b01e3dcf3367c84cd0f7499e31/D7VE7WM4T1WZFWEJ/10044871
A0MDlBRA==


bacen_url Até 255 caracteres Texto Url Bacen Pix

Exemplo:
https://pix.bcb.gov.br/qr/MDAwMjAxMDEwMjEyMjY3NzAwMTRCUi5HT1
YuQkNCLlBJWDI1NTVhcGkuaXRhdS9waXgvcXIvdjEvY2U3Zjk3NDMtNjU3NS00OD
VhLTg2ZGEtYTBmNTZjZjEzNjU2NTIwNDAwMDA1MzAzOTg2NTgwMkJSNTkyNVBBR0
hJUEVSIFNFUlYgT05MSU5FIEVJUkU2MDA5U0FPIFBBVUxPNjIwNzA1MDMqKio2Mz
A0MDlBRA==


Detalhes do http cod
http_code 3 Numérico Consultar item Códigos de Retorno (Status Protocolo HTTP) e Mensagens de Retorno

Códigos de Retorno (Status Protocolo HTTP)

Protocolo HTTP



Descrição Código Mensagem
Requisição recebida, porém, não pode ser consultada devido as regras de negócio aplicada.
Verificar o item: Mensagens de Retorno
200 Ok
Notification_id encontrada 201 Success
Conteúdo da mensagem vazio ou mal formatado 400 BAD_REQUEST
Credenciais para acessar o endpoint estão incorretas 401 UNAUTHORIZED
Credenciais para acessar o endpoint estão incorretas 405 UNAUTHORIZED
Tipo de conteúdo da mensagem não suportado Valores válidos: application/json 415 Unsupported Media Type

Mensagens de Retorno

Response_message Result HTTP
Code
apiKey não informada reject 200
token não informado reject 200
transaction_id não informada ou inválida reject 200
transaction_id inválida reject 200
notification_id não informada ou inválida reject 200
notification_id inválida ou expirada reject 200
token ou apiKey inválidos reject 401
Request method must be POST reject 405
Content type must be: application/json reject 405
Received content contained invalid JSON reject 405
notification_id encontrada success 201

📘

Prazo para Expiração de Uma Notificação

A partir da data de envio, uma notificação se mantém acessível por no máximo 30 dias corridos.

Após o prazo já não será possível ter acesso as informações da notificação.