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.
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.
|
||||||||||||||
| 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== |
||||||||||||||
| e2e | Até 35 caracteres | Texto | Codigo End To End Observações: Esse campo passa existir nos retornos de aprovado e completo, a partir do dia 14/08/2024 Exemplo: E033114432024219201518geHiJfa7Rp |
||||||||||||||
| 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.