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://api.paghiper.com/transaction/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 2 dias corridos.
| Endpoint https://api.paghiper.com/transaction/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://api.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":"3IMZI5QXGMI7K40W",
"order_id":"96874",
"created_date":"2017-07-14 21:21:02",
"status":"paid",
"paid_date":"2017-07-20 05:21:02",
"status_date":"2017-07-20 05:24:02",
"payer_email":"[email protected]",
"payer_name":"poul silva",
"payer_cpf_cnpj":"00000000191",
"payer_phone":"1140638785",
"payer_street":"Av Brigadeiro Faria Lima",
"payer_number":"1461",
"payer_complement":"Torre Sul 4º Andar",
"payer_district":"Jardim Paulistano",
"payer_city":"São Paulo",
"payer_state":"SP",
"payer_zip_code":"01452002",
"value_cents":"17012",
"value_fee_cents":"279",
"discount_cents":"1100",
"shipping_price_cents":"2595",
"bank_slip":{
"digitable_line":"34191.76437 47416.610245 61514.190000 9 72540000017012",
"url_slip":"https://www.paghiper.com/checkout/boleto/ab039901bd6f402e44424f30cd1d3ca9e1f5c90bdb78f7878e8dcdcf7701e1befdc7f1ff6521e8312f7cef408b10b500ee85da4b8903d28874a0436f00a0a3c6/3IMZI5QXGMI7K40W/43474166",
"url_slip_pdf":"https://www.paghiper.com/checkout/boleto/ab039901bd6f402e44424f30cd1d3ca9e1f5c90bdb78f7878e8dcdcf7701e1befdc7f1ff6521e8312f7cef408b10b500ee85da4b8903d28874a0436f00a0a3c6/3IMZI5QXGMI7K40W/43474166/pdf"},
"due_date":"2017-07-31",
"num_cart_items":"3",
"items":[
{
"item_id":"1",
"description":"piscina de bolinha",
"quantity":"1",
"price_cents":"1012"
},
{
"item_id":"1",
"description":"pula pula",
"quantity":"2",
"price_cents":"2000"
},
{
"item_id":"1",
"description":"mala de viagem",
"quantity":"3",
"price_cents":"4000"
}],
"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, ele é 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://api.paghiper.com (sinaliza que é uma notificação da API de boleto) |
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. Ele é utilizado para validar a solicitação e não deve ser compartilhado com terceiros. Para obter o token: https://www.paghiper.com/painel/token/ |
| transaction_id | 16 | Texto | Toda transação possui o transaction_id, ele é 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, ele é 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_date | Datetime | Data em que o status foi atualizado 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 |
||||||||||||||||
| payer_street | Até 255 caracteres | Texto | Endereço do cliente pagador. Exemplo: Av Brigadeiro Faria Lima |
||||||||||||||||
| payer_number | Até 15 caracteres | Texto | Número do endereço do cliente pagador Exemplo: 1461 Caso não seja enviado um numero valido, sera retornado a string "S/N" |
||||||||||||||||
| payer_complement | Até 200 caracteres | Texto | Complemento do endereço do cliente pagador Exemplo: Torre Sul 4º Andar |
||||||||||||||||
| payer_district | Até 255 caracteres | Texto | Bairro do cliente pagador Exemplo: Jardim Paulistano |
||||||||||||||||
| payer_city | Até 100 caracteres | Texto | Cidade do cliente pagador Exemplo: São Paulo |
||||||||||||||||
| payer_state | Até 2 caracteres | Texto | Estado do cliente pagador Exemplo: SP Deve ser representado pela sigla de cada estado |
||||||||||||||||
| payer_zip_code | Até 8 caracteres | Numérico | CEP do cliente pagador Exemplo: 01452002 |
||||||||||||||||
| due_date | DATE | Data do vencimento do boleto Exemplo esperado 2017-07-12 |
|||||||||||||||||
| 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 R$ 2,79 será representado por: 279 |
||||||||||||||||
| value_cents_paid | Até 15 caracteres | Numérico | Valor final da transação em centavos, contendo juros e multas, ou desconto de pagamento antecipado exemplo: R$ 100,00 será representado por: 10000 Esse campo só será retornado se a transação estiver com status de paid, ou completed |
||||||||||||||||
| late_payment_fine | Até 2 caracteres | Numérico | Percentual da multa O percentual máximo autorizado é de 2%, de acordo artigo 52, parágrafo primeiro do Código de Defesa do Consumidor, Lei 8.078/90 Exemplo: multa de 2% deve ser enviado o valor: 2 Qualquer valor acima do máximo autorizado será levado em consideração 2% = 2 Aceito apenas números inteiros: 1 e 2 Esse campo só será retornado se na requisição do Boleto foi configurado a opção Multa |
||||||||||||||||
| per_day_interest | Booleano | Juros por atraso Aplicar 1% de juros máximo ao mês, esse percentual será cobrado proporcionalmente aos dias de atraso. Dividindo 1% por 30 dias = 0,033% por dia de atraso. Esse campo só será retornado se na requisição do Boleto foi configurado a opção Juros
|
|||||||||||||||||
| early_payment_discounts_days | Até 3 caracteres | Numérico | Número de dias em que o pagamento pode ser realizado com antecedência recebendo o desconto extra. Exemplo: O valor do boleto é R$ 100,00 e será concedido um desconto extra caso o pagador realize o pagamento com até 5 dias antes da data do vencimento. Neste caso deve ser enviado o número 5 simbolizando o número máximo de dias de antecedência. Esse campo só será retornado se na requisição do Boleto foi configurado a opção desconto por antecipação |
||||||||||||||||
| early_payment_discounts_cents | Até 15 caracteres | Numérico | Valor do desconto em centavos que será aplicado caso o pagamento ocorra de forma antecipada. Exemplo: O valor do boleto é R$100,00, porem, caso seja pago com antecedência mínima de 5 dias antes da data do vencimento, será concedido um desconto extra de R$5,00. Neste caso, o valor a ser enviado será o número 500, valor em centavos, que representará o desconto extra pelo pagamento antecipado. Se o desconto extra pelo pagamento antecipado for aplicado em porcentagem, a sua aplicação deverá realizar o cálculo e nos informar apenas o valor já calculado em centavos. Esse campo só será retornado se na requisição do Boleto foi configurado a opção desconto por antecipação |
||||||||||||||||
| open_after_day_due | Até 2 caracteres | Numérico | Número máximo de dias em que o boleto poderá ser pago após o vencimento. (Prática comum para quem opta por cobrar juros e multas). Neste campo será aceito, qualquer número maior ou igual a 5, e menor ou igual a 30. Exemplo: Se optar em receber após o vencimento por até 15 dias, deverá ser enviado o número 15, e a frase será exibida no boleto da seguinte forma: “Não receber após 15 dias do vencimento.” Recomendamos o uso deste campo apenas se existir o interesse em permitir que o pagador realize o pagamento fora do prazo de vencimento. Ele é útil para se trabalhar em conjunto com a aplicação de juros e multas. Esse campo só será retornado se o Boleto foi configurado, para ficar em aberto após o vencimento. |
||||||||||||||||
| discount_cents | Até 15 caracteres | Numérico | Desconto total aplicado ao título em centavos R$ 9,99 será representado por: 999 |
||||||||||||||||
| shipping_price_cents | Até 15 caracteres | Numérico | Valor do frete em centavos 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 bank_slip | |||||||||||||||||||
| digitable_line | Até 60 caracteres | Texto | Linha digitável do boleto bancário Exemplo: 34191.76106 04487.160246 61514.190000 3 72180000002000 |
||||||||||||||||
| url_slip | Até 255 caracteres | Texto | Url onde é possível visualizar o boleto Exemplo: https://www.paghiper.com/checkout/boleto/113 d8222fb24998baa2d48b015fd9de227403a977943ffe5f30f beb5d01c9869aa6451a2b1ec622622cc8c4461b88e16c1d548 b01c84cd0f7499e31/D7VE7WM4T1WZFWEJ/10044871 |
||||||||||||||||
| url_slip_pdf | Até 255 caracteres | Texto | Url onde é possível visualizar o boleto Exemplo: https://www.paghiper.com/checkout/boleto/113 d8222fb24998baa2d48b015fd9de227403a977943ffe5f30f beb5d01c9869aa6451a2b1ec622622cc8c4461b88e16c1d548 b01c84cd0f7499e31/D7VE7WM4T1WZFWEJ/10044871/pdf |
||||||||||||||||
| 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.