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

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). 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

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.

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.

Esperado:

status significado
pending aguardando
reserved reservado (Como Funciona ?)
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

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

esperado significado
true Aplicará o juros de 1% ao mês por atraso.
false Nenhum juro será aplicado.


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.