Documentação da API

1. No painel da Hakopay, em Meu site, o vendedor cria a chave de acesso e a entrega a você.
2. Você informa o endereço de aviso: uma URL https do site que recebe os avisos de pagamento. O painel mostra o segredo para conferir a assinatura desses avisos.
3. O site cadastra os planos pela API e inscreve cada cliente numa assinatura.
4. O vendedor usa Verificar conexão no painel para confirmar que o site está recebendo os avisos.

Endereço base: https://api.hakopay.com.br. Valores sempre em centavos inteiros (9700 = R$ 97,00).

Toda chamada leva a chave de acesso no cabeçalho:

Authorization: Bearer hako_live_...

A chave identifica a conta do vendedor. Guarde-a somente no servidor do site, nunca no navegador ou no aplicativo. Sem chave, ou com chave desligada, a resposta é 401.

Cadastre cada produto uma vez. A resposta traz o id do plano.

POST /v1/planos
{ "name": "Curso completo", "priceCents": 9700, "cycleDays": 30 }

cycleDays de 7 a 366. GET /v1/planos lista os planos ativos. Os planos cadastrados aparecem automaticamente no painel do vendedor.

Inscreva o cliente e receba a primeira cobrança:

POST /v1/assinaturas
{
  "planId": "ID_DO_PLANO",
  "customer": { "externalId": "aluno-123", "email": "aluno@exemplo.com", "name": "Ana" }
}

externalId é o código do cliente no seu sistema. A resposta traz payment.checkoutUrl (página de pagamento pronta) e payment.pix, para mostrar o Pix dentro do seu site. Chamar de novo antes do pagamento devolve a mesma cobrança.

Para decidir se libera o acesso, olhe somente o campo active da assinatura.

Para vendas únicas, sem assinatura:

POST /v1/cobrancas
Idempotency-Key: pedido-42
{ "amountCents": 4990, "description": "Plano mensal", "externalRef": "pedido-42" }

Repetir a mesma Idempotency-Key devolve a mesma cobrança. GET /v1/cobrancas/:id consulta a situação.

A Hakopay envia um POST com JSON para o endereço de aviso a cada mudança. O mesmo aviso pode chegar mais de uma vez: use o id do evento para ignorar repetidos. Responda 2xx em até 10 segundos; caso contrário, a Hakopay tenta novamente até 6 vezes, ao longo de cerca de 4 horas.

Confira a assinatura de cada aviso. O cabeçalho X-Hako-Signature tem o formato t=<unix>,v1=<hmac>:

1. Recuse se t estiver a mais de 5 minutos de agora.
2. Calcule HMAC-SHA256(segredo, "<t>.<corpo cru>") em hexadecimal.
3. Compare com v1. Se forem iguais, o aviso é legítimo.

Para desenvolver sem cobrar ninguém, a Hakopay oferece um ambiente de testes com chaves próprias (prefixo hako_test_). Nele, o pagamento é simulado e nenhuma conta real é movimentada. Peça o acesso ao ambiente de testes ao suporte da Hakopay.

Cada chave só funciona no ambiente dela. Usada no ambiente errado, a resposta é 401 com wrong_environment, e nada é cobrado. Ao publicar, troque pela chave criada no painel (hako_live_).

Dúvidas técnicas: fale com a equipe.