# Documentação da API Grinny Pay --- # Introdução https://app.grinnypay.com/docs?p=introducao Seção: Comece por aqui Com a API da Grinny Pay o seu sistema cria cobranças Pix, consulta vendas, saldo e saques, e recebe avisos em tempo real quando um Pix é pago. ## URL base Todas as chamadas vão para o endereço abaixo, sempre por https://: **URL base** ``` https://app.grinnypay.com/api/v1 ``` : O caminho de cada endpoint é somado à URL base. Exemplo: POST /charges vira https://app.grinnypay.com/api/v1/charges. ## Formato - Pedidos e respostas em JSON (Content-Type: application/json). - Valores de dinheiro sempre em centavos e números inteiros: R$ 97,00 é 9700. - Datas no padrão ISO 8601 com fuso, por exemplo 2026-10-15T14:30:00-03:00. - Campos e códigos em português: valor, status, pendente, pago. - Toda resposta de erro tem o mesmo formato. Veja Erros. ## O que dá pra fazer Endpoint | Para quê | Permissão da chave | POST /charges | Criar cobrança Pix | Transações | GET /charges/{id} | Consultar uma cobrança | Transações | GET /charges | Listar cobranças | Transações | GET /balance | Consultar saldo | Conta | POST /withdrawals | Criar saque | Saques | GET /withdrawals/{id} | Consultar um saque | Saques | GET /withdrawals | Listar saques | Saques | Além disso, a Grinny Pay manda webhooks para o seu servidor quando algo acontece (Pix pago, expirado, MED aberto, saque concluído). ## Para ferramentas e IAs - openapi.yaml: o contrato da API em OpenAPI 3.1. Abre no Swagger, no Postman e gera cliente em qualquer linguagem. - llms.txt: lista de todas as páginas, para assistentes de IA. llms-full.txt traz a documentação inteira num arquivo só. ## Antes de começar - Sua conta precisa estar aprovada. Conta em análise recebe 403 conta_nao_aprovada. - A aba Integrações › API do painel só abre com a verificação em duas etapas (2FA) ligada. - Chave gp_live_ cria Pix real. Para testar sem dinheiro de verdade, use a chave gp_test_: veja Modo de teste. Comece pelo guia Sua primeira cobrança: do zero ao Pix pago e ao webhook recebido. --- # Sua primeira cobrança https://app.grinnypay.com/docs?p=primeira-cobranca Seção: Comece por aqui Do zero ao Pix pago: chave de API, cobrança, QR Code para o cliente e o aviso de pagamento no seu servidor. Com a chave gp_live_ a cobrança deste guia é um Pix de verdade: use um valor pequeno (a partir de R$ 1,00). Para testar sem dinheiro, crie uma chave gp_test_ e siga o modo de teste. ## Passo a passo ### Crie uma chave de API No painel, abra Integrações › API (pede a verificação em duas etapas) e clique em criar credencial. Marque a permissão Criar/consultar transações. A chave privada começa com gp_live_ e aparece uma única vez. Copie e guarde no seu servidor (por exemplo numa variável de ambiente). A chave é credencial de servidor. Ela nunca deve aparecer no JavaScript do navegador, em app de celular, em repositório público ou em print. ### Crie a cobrança Mande o valor em centavos e os dados do cliente. A Idempotency-Key é opcional, mas recomendada: se a conexão cair e você mandar de novo, não nasce uma segunda cobrança. **cURL** ``` curl -X POST https://app.grinnypay.com/api/v1/charges \ -H "Authorization: Bearer $GRINNY_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-1042" \ -d '{ "valor": 9700, "descricao": "Curso de Marketing", "referencia": "pedido-1042", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com", "cpf": "52998224725" } }' ``` **PHP** ``` true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('GRINNY_KEY'), 'Content-Type: application/json', 'Idempotency-Key: pedido-1042', ], CURLOPT_POSTFIELDS => json_encode([ 'valor' => 9700, 'descricao' => 'Curso de Marketing', 'referencia' => 'pedido-1042', 'cliente' => ['nome' => 'Carlos Silva', 'email' => 'carlos@email.com', 'cpf' => '52998224725'], ]), ]); $cobranca = json_decode(curl_exec($ch), true); ``` **Node.js** ``` const resp = await fetch('https://app.grinnypay.com/api/v1/charges', { method: 'POST', headers: { Authorization: `Bearer ${process.env.GRINNY_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'pedido-1042', }, body: JSON.stringify({ valor: 9700, descricao: 'Curso de Marketing', referencia: 'pedido-1042', cliente: { nome: 'Carlos Silva', email: 'carlos@email.com', cpf: '52998224725' }, }), }); const cobranca = await resp.json(); ``` : A resposta vem assim: **Resposta 201** ``` { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pendente", "valor": 9700, "taxa": 371, "liquido": 9329, "descricao": "Curso de Marketing", "pix_copia_e_cola": "00020101021226...", "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": null, "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1042" } ``` : Guarde o id junto do seu pedido: é por ele que você consulta a cobrança e reconhece o webhook. ### Mostre o Pix para o cliente Você tem dois caminhos: - Gere o QR Code no seu site a partir do pix_copia_e_cola e mostre também o texto para o cliente copiar. - Ou mande o cliente para o link_pagamento: uma página pronta com QR Code, botão de copiar e contador. ### Receba o aviso de pagamento Em Integrações › Webhooks, cadastre a URL do seu servidor (https) e marque o evento venda.aprovada. Quando o Pix for pago, chega um POST assim: **Corpo do webhook** ``` { "id": "evt_5821", "tipo": "venda.aprovada", "sequencia": 5821, "criado_em": "2026-10-15T14:32:10-03:00", "dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pago", "valor": 9700, "...": "..." } } ``` : Confira a assinatura antes de liberar o acesso (veja Conferir a assinatura) e responda com HTTP 2xx em até 5 segundos. ### Confira quando quiser Se o webhook atrasar, consulte a cobrança pelo id. Enquanto ela está pendente, a consulta pergunta ao banco na hora. **cURL** ``` curl https://app.grinnypay.com/api/v1/charges/8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f \ -H "Authorization: Bearer $GRINNY_KEY" ``` ## Antes de ir para produção - Chave só no servidor e, se possível, com IPs autorizados cadastrados. - Webhook conferindo a assinatura, o horário e o id repetido. - Tratamento dos erros 422 (dados do cliente) e 429 (limites). Veja Erros. --- # Autenticação https://app.grinnypay.com/docs?p=autenticacao Seção: Comece por aqui Toda chamada leva a sua chave privada no cabeçalho Authorization. As chaves são criadas no painel, em Integrações › API. ## Como enviar a chave **Cabeçalho** ``` Authorization: Bearer gp_live_1a2b3c4d5e6f_0123456789abcdef0123456789abcdef0123456789abcdef ``` - Formato: gp_live_ + 12 caracteres + _ + 48 caracteres (letras a-f e números). - A parte gp_live_ + os 12 primeiros caracteres é o identificador público da chave (aparece no painel). O resto é segredo. - A chave privada inteira aparece uma única vez, na criação. Guardamos só uma versão embaralhada (hash): se perder, gere outra. - Chave de produção começa com gp_live_. Para testar sem Pix de verdade, use a chave de teste gp_test_ (mesmo formato): veja Modo de teste. Pedido feito por http:// recebe 403 https_obrigatorio e não é redirecionado, porque a chave já teria passado aberta pela internet. Se isso acontecer, troque a chave no painel. ## Permissões Cada chave tem uma ou mais permissões. Chamada sem a permissão daquele endereço recebe 403 sem_permissao. Permissão no painel | Libera | Criar/consultar transações | /charges | Consultar dados da conta e saldo | /balance | Criar/consultar saques | /withdrawals | Chave com permissão de saque tem regras a mais: - Sempre tem data de validade, de no máximo 365 dias. - Só cria saque se a conta tiver pelo menos um IP autorizado (senão: 403 ip_obrigatorio). - Pode ser criada com a opção Exigir minha aprovação: o saque fica esperando você aprovar no painel (status aguardando_sua_aprovacao). ## IPs autorizados Em Integrações › API você pode cadastrar até 20 IPs ou faixas (IPv4 de /16 a /32, IPv6 de /48 a /128). Com a lista preenchida, pedido de outro IP recebe 403 ip_nao_autorizado. Com a lista vazia, qualquer IP é aceito (menos para saques). ## Validade, troca e revogação - Você pode dar uma data de validade à chave (até 5 anos). Depois dela: 401 chave_expirada. - Trocar a chave gera uma nova chave privada com o mesmo identificador; a antiga para na hora. - Revogar desliga a chave para sempre: 401 nao_autorizado. - Cada conta pode ter até 5 chaves ativas de produção e até 5 de teste. ## Quando a chave é recusada HTTP | Código | Quando | 401 | nao_autorizado | Chave errada, revogada ou cabeçalho fora do formato. | 401 | chave_expirada | Passou da data de validade. | 403 | https_obrigatorio | Pedido chegou por http. | 403 | conta_nao_aprovada | Conta ainda em análise. | 403 | ip_nao_autorizado | IP fora da lista de IPs autorizados. | 403 | sem_permissao | A chave não tem a permissão daquele endereço. | 403 | recurso_indisponivel_em_teste | Chave de teste chamando saldo ou saque. | 403 | chave_de_teste_na_producao | Chave de teste (gp_test_) no endereço de produção. Ela só vale em /sandbox. | 429 | muitas_chaves_invalidas | Muitos pedidos com chave errada da mesma rede em 1 minuto. Espere 1 minuto. | --- # Modo de teste (sandbox) https://app.grinnypay.com/docs?p=sandbox Seção: Comece por aqui Teste a integração inteira, do pedido ao webhook, sem Pix de verdade e sem mexer no seu saldo. Basta usar uma chave de teste no lugar da chave de produção. ## A chave de teste Em Integrações › Ambiente de teste, crie uma chave de teste. Ela começa com gp_test_ e aparece uma única vez, como a de produção. **Cabeçalho** ``` Authorization: Bearer gp_test_1a2b3c4d5e6f_0123456789abcdef0123456789abcdef0123456789abcdef ``` - O teste tem endereço próprio, separado da produção: https://app.grinnypay.com/api/v1/sandbox. A chave gp_test_ só vale nele, e a gp_live_ só vale em https://app.grinnypay.com/api/v1. Chave no endereço errado responde 403 (chave_de_teste_na_producao ou somente_chave_de_teste), sem criar nada. - O endereço de teste tem as rotas de cobrança (criar, consultar, listar) e simulate-payment. Saldo e saques respondem 403 recurso_indisponivel_em_teste. - Cada conta pode ter até 5 chaves de teste ativas, à parte das 5 de produção. ## O que muda e o que não muda | Chave de produção | Chave de teste | Pix | Real, gerado no banco | Fictício (copia e cola que não paga nada) | Pagamento | O cliente paga o Pix | Você chama POST /charges/{id}/simulate-payment | Saldo e extrato | Recebe a venda | Nunca é tocado | Taxa e líquido | Conta da sua taxa | A mesma conta, em centavos exatos | Painel e relatórios | Aparece | Não aparece | Webhooks | Webhook de produção, "livemode": true | Só webhook de teste, "livemode": false, assinados do mesmo jeito | link_pagamento | Página do Pix | null (não existe página de pagamento de teste) | Antifraude, push, Utmify e nota fiscal | Valem | Não rodam | Cobranças de teste e de produção ficam separadas dos dois lados: a chave de teste não enxerga cobrança real, e a de produção não enxerga cobrança de teste (404 nao_encontrado). ## Limites do teste - Retenção: a cobrança de teste é apagada sozinha depois de 7 dias. - Teto: até 200 cobranças de teste guardadas por conta. Passou disso, POST /charges responde 429 limite_cobrancas_teste e não grava nada, até abrir vaga. Repetir uma Idempotency-Key que já existe devolve a cobrança e não conta como nova. - Pedidos por minuto: a chave de teste tem limite por minuto próprio (429 muitas_requisicoes e limite_vendedor), à parte do da produção: um teste de carga não gasta a cota das vendas reais. Os dados de teste não são criptografados. Use só dados fictícios (nome, e-mail e CPF de mentira): nunca dado real de cliente. ## Webhook de teste Evento de teste nunca vai para o seu webhook de produção. Em Integrações › Ambiente de teste, crie um webhook de teste, com a URL do seu ambiente de testes. Ele recebe só eventos da chave de teste, e o webhook de produção só os de venda de verdade. Os eventos de teste saem depois dos reais na fila de envio. ## Fluxo completo ### Crie a cobrança de teste Igual à cobrança normal, com a chave gp_test_. A resposta traz "livemode": false. **Exemplo** ``` curl -X POST https://app.grinnypay.com/api/v1/sandbox/charges \ -H "Authorization: Bearer $GRINNY_TEST_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: teste-1042" \ -d '{ "valor": 9700, "descricao": "Curso de Marketing", "referencia": "teste-1042", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com", "cpf": "52998224725" } }' ``` ### Simule o pagamento Chame o endereço abaixo com o id da cobrança. Ela vira pago e o webhook venda.aprovada sai para a sua URL. **Exemplo** ``` curl -X POST https://app.grinnypay.com/api/v1/sandbox/charges/8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f/simulate-payment \ -H "Authorization: Bearer $GRINNY_TEST_KEY" ``` ### Confira o webhook O aviso chega no webhook de teste, com o mesmo formato e a mesma assinatura do real. Veja livemode para não tratar teste como venda de verdade. **Webhook de teste** ``` { "id": "evt_9124", "tipo": "venda.aprovada", "sequencia": 9124, "criado_em": "2026-10-15T14:32:10-03:00", "livemode": false, "dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pago", "valor": 9700, "livemode": false } } ``` No seu receptor de webhook, ignore ou separe os eventos com "livemode": false: eles não são vendas e não devem liberar acesso nem emitir nota. ## Repetir e vencer - Simular o pagamento de novo numa cobrança já paga devolve a mesma cobrança, sem um segundo webhook. - Cobrança de teste vence como a real (5 a 15 minutos). Simular uma vencida devolve 422 dados_invalidos: crie outra. - A Idempotency-Key funciona igual: a mesma chave devolve a mesma cobrança de teste. ## Ir para produção Troque a chave gp_test_ pela gp_live_ e o endereço https://app.grinnypay.com/api/v1/sandbox por https://app.grinnypay.com/api/v1. O formato das respostas é o mesmo. Antes de abrir as vendas, passe pela lista de produção. --- # Limites e repetição segura https://app.grinnypay.com/docs?p=limites Seção: Comece por aqui Limites de pedidos que protegem a sua conta e a plataforma, e como repetir um pedido sem criar nada em dobro. ## Limites de pedidos Limite | Valor hoje | Se passar | Pedidos por chave | 120 por minuto | 429 muitas_requisicoes | Pedidos por conta (todas as chaves juntas) | 300 por minuto | 429 limite_vendedor | Cobranças criadas pela API | 100 a cada 10 minutos | 429 muitas_requisicoes | Pix pendentes (sem pagar) ao mesmo tempo | teto por conta | 429 limite_pendentes | Movimento da plataforma no banco | teto por minuto | 429 banco_no_limite: tente em instantes | As respostas não trazem cabeçalhos de limite (X-RateLimit-* ou Retry-After). Ao receber 429, espere alguns segundos e tente de novo, aumentando a espera a cada nova falha. Consultar uma cobrança pendente pergunta ao banco na hora, mas no máximo a cada 20 segundos por cobrança. Prefira o webhook a ficar consultando sem parar. ## Repetição segura (Idempotency-Key) Se a conexão cair no meio do pedido, você não sabe se a cobrança ou o saque foi criado. Mande o cabeçalho Idempotency-Key com um código seu (por exemplo o número do pedido): repetir o mesmo pedido com a mesma chave devolve a mesma resposta, sem criar outro. **Cabeçalho** ``` Idempotency-Key: pedido-1042 ``` - Formato: de 1 a 80 caracteres entre letras, números e _ - : . - POST /charges: opcional. Valor fora do formato: 400 idempotency_key_invalida. - POST /withdrawals: obrigatória. Sem ela: 400 idempotency_key_obrigatoria. - Vale por chave de API. As respostas ficam guardadas por 7 dias. Situação | Resposta | Mesma chave e mesmo corpo, pedido já terminado | A mesma resposta da primeira vez (mesmo status HTTP) | Mesma chave e corpo diferente | 422 idempotency_key_reusada | Mesma chave enquanto o primeiro ainda está sendo feito | 409 em_andamento: tente de novo em instantes | Pedido recusado (dados inválidos, limites, antifraude) | A chave fica livre para você corrigir e mandar de novo | --- # Erros https://app.grinnypay.com/docs?p=erros Seção: Comece por aqui Todo erro volta com um status HTTP e um JSON com o codigo (fixo, para o seu sistema tratar) e a mensagem (texto em português, pode mudar). ## Formato **Resposta 422** ``` { "erro": { "codigo": "dados_invalidos", "mensagem": "CPF inválido.", "campos": { "cpf": "CPF inválido." } } } ``` - campos só aparece em dados_invalidos: diz qual campo está errado. - Nos dados do cliente, as chaves de campos saem como name, email, cpf e phone. - Trate pelo codigo, nunca pelo texto da mensagem. ## Códigos HTTP | Código | O que fazer | 400 | json_invalido | Corpo não é um JSON válido (ou, no saque, falta o valor inteiro). | 400 | idempotency_key_invalida | A Idempotency-Key está fora do formato. | 400 | idempotency_key_obrigatoria | Saque sem Idempotency-Key. | 401 | nao_autorizado | Chave errada ou revogada. | 401 | chave_expirada | Chave passou da validade: crie outra. | 403 | https_obrigatorio | Use https e troque a chave. | 403 | conta_nao_aprovada | Espere a aprovação da conta. | 403 | ip_nao_autorizado | Cadastre o IP do servidor no painel. | 403 | ip_obrigatorio | Saque exige pelo menos um IP autorizado. | 403 | sem_permissao | A chave não tem a permissão daquele endereço. | 403 | recurso_indisponivel_em_teste | Chave de teste (gp_test_) chamando saldo ou saque. | 403 | somente_chave_de_teste | Chave de produção (gp_live_) no endereço de teste (/sandbox). | 403 | chave_de_teste_na_producao | Chave de teste (gp_test_) no endereço de produção. | 429 | limite_cobrancas_teste | Mais de 200 cobranças de teste guardadas na conta. Elas saem sozinhas depois de 7 dias. | 404 | nao_encontrado | Cobrança ou saque não existe (ou é de outra conta). | 404 | rota_inexistente | Endereço errado. | 409 | em_andamento | O mesmo pedido ainda está sendo feito: tente de novo em instantes. | 422 | dados_invalidos | Algum campo errado: veja campos. | 422 | idempotency_key_reusada | A mesma Idempotency-Key com outro corpo: use outra chave. | 422 | valor_indisponivel | Este valor não está disponível agora para a sua conta. Tente outro valor ou fale com o suporte. | 422 | limite_vendedor_novo | Conta nova chegou ao limite de Pix do mês (a mensagem traz os detalhes). | 422 | recusado_antifraude | O antifraude recusou este Pix (ex.: comprador bloqueado ou muitos Pix seguidos do mesmo comprador). | 422 | 2fa_obrigatorio | Saque sem o 2FA ligado na conta do vendedor: ligue em Configurações › Segurança. | 422 | saque_recusado | Regra de saque (saldo, mínimo, saques pausados…): a mensagem diz o motivo. | 422 | sem_conta_bancaria, conta_bancaria_inexistente, conta_bancaria_em_analise, conta_bancaria_recusada, conta_bancaria_alterada | Problema na conta bancária do saque: confira em Financeiro. | 429 | muitas_requisicoes | Passou do limite da chave ou de cobranças em 10 minutos. Espere e tente de novo. | 429 | limite_vendedor | Passou do limite da conta (todas as chaves juntas). | 429 | limite_pendentes | Pix pendentes demais em aberto: espere alguns vencerem ou serem pagos. | 429 | banco_no_limite | Muitos Pix na plataforma agora: tente em instantes. | 429 | muitas_chaves_invalidas | Muitas chaves erradas da mesma rede: espere 1 minuto. | 500 | erro_interno | Falha nossa: tente de novo com a mesma Idempotency-Key. | 503 | pix_indisponivel | Nenhum banco Pix disponível agora: tente de novo com a mesma Idempotency-Key. | Trabalhamos com mais de um banco: se um cair, a cobrança é gerada em outro sem você perceber. O 503 só aparece se todos estiverem fora. --- # Status https://app.grinnypay.com/docs?p=status Seção: Comece por aqui Os status que a API devolve no campo status de cobranças e saques. ## Cobrança Status | Significa | pendente | Pix gerado, esperando o pagamento. Só neste status vem o pix_copia_e_cola. | pago | Pagamento confirmado pelo banco. Pode liberar o acesso. | expirado | Passou do tempo sem pagamento. Crie outra cobrança se o cliente ainda quiser pagar. | falhou | O banco não conseguiu gerar o Pix. | med | O banco do comprador abriu um MED (pedido de devolução por fraude ou golpe). O valor fica bloqueado até a decisão. | contestado | MED decidido a favor do comprador: o valor foi devolvido. | reembolsado | Venda devolvida ao comprador. | O filtro status de Listar cobranças aceita todos menos falhou. ## Saque Status | Significa | aguardando_sua_aprovacao | Chave com "Exigir minha aprovação": aprove o saque no painel, em Financeiro. | em_analise | Em conferência de segurança. Assim que terminar, o saque segue sozinho. | processando | Na fila ou sendo enviado ao banco. | concluido | Dinheiro enviado. concluido_em traz a hora. | cancelado | Não saiu (recusado ou falhou). O motivo diz por quê. Em geral o valor volta para o saldo (o extrato do painel mostra a devolução). | --- # Objeto cobrança https://app.grinnypay.com/docs?p=modelo-cobranca Seção: Modelos O objeto cobrança é o mesmo na criação, na consulta, na listagem e dentro de dados dos webhooks de venda. Esta página é a referência única dele. ## Exemplo **JSON** ``` { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pendente", "valor": 9700, "taxa": 371, "liquido": 9329, "descricao": "Curso de Marketing", "pix_copia_e_cola": "00020101021226...", "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": null, "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1042", "livemode": true } ``` ## Campos - id (texto): Identificador da cobrança: 32 caracteres, letras de a a f e números. Não muda nunca. - status (texto): Um de pendente, pago, expirado, falhou, med, contestado, reembolsado. Veja Status. - valor (inteiro): Valor cobrado, em centavos. R$ 97,00 é 9700. - taxa (inteiro): Taxa da Grinny Pay sobre a venda, em centavos. - liquido (inteiro): O que entra no seu saldo: valor menos taxa e menos a comissão de afiliado, se houver. Em centavos. - descricao (texto): Descrição que o comprador vê. - pix_copia_e_cola (texto ou null): Código Pix (QR Code e "copia e cola"). Só vem enquanto o status é pendente; depois é null. - link_pagamento (texto): Página pronta de pagamento, com QR Code e contador. - cliente (objeto): nome e email de quem paga. O CPF e o celular que você manda na criação não voltam. - expira_em (data): Até quando o Pix pode ser pago (ISO 8601 com fuso). - pago_em (data ou null): Quando o pagamento foi confirmado. null se ainda não foi pago. - criado_em (data): Quando a cobrança foi criada. - livemode (booleano): true em cobrança de produção, false em cobrança criada com a chave de teste. - referencia (texto ou null): O código seu que você mandou ao criar (até 100 caracteres). null se não mandou. ## Ciclo de vida Uma cobrança nasce pendente e termina de um dos jeitos abaixo. Os eventos de webhook correspondentes estão em Webhooks de venda. De | Para | Quando | Webhook | pendente | pago | O banco confirmou o Pix. | venda.aprovada | pendente | expirado | Passou o prazo (expira_em). | venda.expirada | pago | med | O banco do comprador abriu um MED. | med.aberto | med | pago | MED ganho. | med.encerrado | med | contestado | MED perdido. | med.encerrado e venda.contestada | pago | reembolsado | Devolução ao comprador. | venda.reembolsada | Guarde o id da cobrança junto com o seu pedido. É ele que liga o pedido ao pagamento em consultas, webhooks e MED. --- # Objeto saque https://app.grinnypay.com/docs?p=modelo-saque Seção: Modelos O objeto saque é o mesmo na criação, na consulta e na listagem da API. O webhook de saque usa um formato mais enxuto (veja o aviso no fim). ## Exemplo **JSON** ``` { "id": 482, "status": "concluido", "valor": 15000, "taxa": 367, "total_debitado": 15367, "destino": { "tipo": "chave_pix", "chave": "fornecedor@email.com" }, "motivo": null, "criado_em": "2026-10-15T14:40:00-03:00", "concluido_em": "2026-10-15T14:40:12-03:00" } ``` ## Campos - id (inteiro): Número do saque. Não muda nunca. - status (texto): Um de aguardando_sua_aprovacao, em_analise, processando, concluido, cancelado. Veja Status. - valor (inteiro): Valor que o destino recebe, em centavos. - taxa (inteiro): Taxa do saque, em centavos. - total_debitado (inteiro): O que saiu do seu saldo, em centavos. - destino.tipo (texto): chave_pix (chave de terceiro, liberada pelo suporte) ou conta_cadastrada (a sua conta bancária). - destino.chave (texto): A chave Pix do destino. - motivo (texto ou null): em_analise: "Em conferência de segurança". cancelado: por que não saiu. Nos outros status, null. - criado_em (data): Quando o saque foi pedido (ISO 8601 com fuso). - concluido_em (data ou null): Quando o dinheiro saiu. ## Ciclo de vida Status | Próximo passo | aguardando_sua_aprovacao | Aprovar no painel, em Financeiro (chave com "Exigir minha aprovação"). | em_analise | Esperar a conferência de segurança. | processando | Esperar o banco: chega o webhook saque.concluido ou saque.falhou. | concluido | Fim. | cancelado | Fim. O valor volta para o saldo. | O objeto dados do webhook de saque é outro: id com prefixo saq_, datas sem fuso e status interno. Veja Webhooks de saque. Para o objeto da API, consulte GET /withdrawals/{id}. --- # Conciliar pagamentos https://app.grinnypay.com/docs?p=conciliacao Seção: Boas práticas O webhook é o jeito principal de saber do pagamento. A conciliação é a rede de segurança: uma rotina sua que confere de tempos em tempos se nenhuma venda ficou sem tratar. ## Por que conciliar - O seu servidor pode ficar fora do ar por mais tempo do que as tentativas de reenvio cobrem (cerca de 22 horas). - Um erro no seu código pode ter tratado o evento pela metade. - Você pode ter ativado a integração depois de algumas vendas já existirem. A conciliação não substitui o webhook: ela só pega o que escapou. ## A rotina ### 1. Liste as cobranças pendentes do seu sistema Pegue no seu banco os pedidos que ainda estão aguardando pagamento e cuja cobrança já foi criada há mais de 2 minutos (dê tempo ao webhook chegar). ### 2. Consulte cada uma na API Chame GET /charges/{id}. Se está pendente, a consulta pergunta ao banco na hora (no máximo a cada 20 segundos por cobrança). Para muitas de uma vez, use GET /charges com status=pago e limite=100. ### 3. Trate o resultado como se fosse o webhook pago: libere o acesso (se ainda não liberou). expirado: cancele o pedido. med, contestado ou reembolsado: ajuste o acesso. O mesmo código de tratamento serve para os dois caminhos, e a conferência de repetição evita tratar duas vezes. ### 4. Repita num ritmo suave A cada 5 a 15 minutos para o que é recente e uma varredura maior uma vez por dia. Nunca em loop apertado: o limite de pedidos da chave existe (veja Limites). ## Espera crescente quando der erro Se a API devolver 429, 503 ou 500, espere e tente de novo, dobrando a espera a cada falha, com um pouco de variação aleatória. Erro 4xx que não é 429 não melhora tentando de novo: corrija o pedido. **PHP** ``` true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('GRINNY_KEY')]]); $corpo = curl_exec($ch); $http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); if ($http === 200) { return json_decode($corpo, true); } if (!in_array($http, [0, 429, 500, 503], true)) { throw new RuntimeException("Erro $http: não adianta repetir"); } sleep($espera + random_int(0, 1)); // 1, 2, 4, 8 s (+ até 1 s) $espera *= 2; } throw new RuntimeException('API indisponível: tente na próxima rodada'); } // Rotina: pedidos aguardando pagamento há mais de 2 minutos foreach ($pedidosPendentes as $pedido) { $c = consultar($pedido['cobranca_id']); if ($c['status'] === 'pago') { liberarAcesso($pedido, $c); // a mesma função que o webhook usa, com a conferência de repetição } elseif ($c['status'] === 'expirado') { cancelarPedido($pedido); } } ``` **Node.js** ``` async function consultar(id, max = 5) { let espera = 1000; for (let i = 1; i <= max; i++) { try { const r = await fetch(`https://app.grinnypay.com/api/v1/charges/${id}`, { headers: { Authorization: `Bearer ${process.env.GRINNY_KEY}` }, signal: AbortSignal.timeout(10000), }); if (r.status === 200) return await r.json(); if (![429, 500, 503].includes(r.status)) throw new Error(`Erro ${r.status}: não adianta repetir`); } catch (e) { if (e.message.startsWith('Erro ')) throw e; // 4xx: corrija o pedido } await new Promise((ok) => setTimeout(ok, espera + Math.random() * 1000)); // 1, 2, 4, 8 s espera *= 2; } throw new Error('API indisponível: tente na próxima rodada'); } for (const pedido of pedidosPendentes) { const c = await consultar(pedido.cobrancaId); if (c.status === 'pago') await liberarAcesso(pedido, c); // a mesma função do webhook else if (c.status === 'expirado') await cancelarPedido(pedido); } ``` ## Idempotência: o mesmo pedido nunca vira dois - Ao criar: mande sempre Idempotency-Key com um código do seu pedido (ex.: pedido-1042). Se a conexão cair, repita com a mesma chave: você recebe a mesma cobrança, não outra. Veja Repetição segura. - Ao receber: grave o id do evento e a sequencia. Webhook e conciliação podem trazer o mesmo pagamento: o segundo a chegar não faz nada. - Ao liberar: a trava deve ser o status do pedido no seu banco (UPDATE ... WHERE status = 'aguardando'), não só a memória do processo. ## Conferir o dinheiro No fim do dia, some o liquido das cobranças pago do período (use status=pago na listagem) e compare com o que o seu sistema registrou. Diferença quase sempre é uma venda não tratada, um MED ou um reembolso. O saldo da conta está em GET /balance; o extrato completo está no painel, em Relatórios. Ao achar uma venda pago que o seu sistema não tem, trate-a como um venda.aprovada atrasado e anote o motivo. Se acontece mais de uma vez, olhe o histórico de envios em Integrações › Webhooks: ali aparece o código que o seu servidor devolveu. --- # Antes de ir pra produção https://app.grinnypay.com/docs?p=producao Seção: Boas práticas Uma lista para conferir antes de receber vendas de verdade. Teste primeiro com a chave gp_test_ (Modo de teste), que não cria Pix de verdade. Com a chave de produção todo Pix é real: faça os testes abaixo com valores pequenos. ## Chaves e acesso - A chave está só em variável de ambiente ou cofre de segredos, nunca no código, no navegador, em app de celular ou no repositório. - Cada sistema tem a sua chave, com só as permissões de que precisa (transações, conta, saques). - Os IPs autorizados do seu servidor estão cadastrados em Integrações › API (obrigatório para saques). - A chave tem data de validade e você sabe como trocá-la sem parar o sistema (cadastre a nova, troque, revogue a antiga). Veja Autenticação. - O 2FA da conta está ligado (sem ele nem o painel de API abre e o saque é recusado). - Toda chamada vai por https://. ## Criando cobranças - O valor é inteiro, em centavos (nada de 97.00). - Toda criação leva Idempotency-Key própria do pedido e você a reutiliza ao repetir. Veja Repetição segura. - Você manda referencia com o número do seu pedido e guarda o id da cobrança no pedido. - O CPF, o nome e o e-mail vêm do cliente de verdade: dados inventados são recusados (422 dados_invalidos). - O seu código trata 422 mostrando a mensagem ao usuário e 429, 500, 503 repetindo com espera crescente. Veja Erros. ## Webhooks - O webhook está cadastrado com https, escolhendo os eventos de que você precisa. Veja Como funcionam. - O botão Testar devolveu sucesso. Veja Teste. - O segredo whsec_... está guardado com segurança e a assinatura é conferida (com o corpo cru e o limite de 5 minutos). - O seu receptor responde 2xx em até 5 segundos e faz o trabalho pesado depois. - Evento repetido e evento atrasado são ignorados (id e sequencia). Veja Receptor completo. - O acesso é liberado só no venda.aprovada (ou quando a consulta mostra pago), nunca quando o cliente volta ao seu site. - Você trata venda.reembolsada e venda.contestada tirando o acesso. ## Rede de segurança - Existe uma rotina de conciliação que confere as cobranças pendentes e a soma do dia. - Os limites da API foram considerados: a rotina não faz mais pedidos por minuto do que a chave aguenta. Veja Limites. - Você tem alerta quando o seu receptor de webhook devolve erro por muito tempo. ## Teste ponta a ponta com dinheiro real - Crie uma cobrança com o valor mínimo permitido (veja Criar cobrança). - Pague com o seu próprio Pix. Confirme: o webhook venda.aprovada chegou, o acesso foi liberado uma vez só e a consulta mostra pago. - Peça o reembolso pelo painel e confirme que o acesso foi tirado. - Deixe uma cobrança expirar e confirme o tratamento do venda.expirada. - Desligue o seu receptor por alguns minutos, gere uma venda e religue: o aviso deve chegar numa nova tentativa, ou a conciliação deve achar a venda. Se a chave de produção vazar (apareceu num repositório, num print, numa conversa): revogue na hora em Integrações › API e crie outra. Revogar é imediato. --- # Criar cobrança Pix https://app.grinnypay.com/docs?p=criar-cobranca Seção: Cobranças POST /api/v1/charges Cria uma cobrança Pix avulsa, com valor livre. Permissão: Criar/consultar transações. ## Cabeçalhos - Authorization (texto) [obrigatório]: Bearer + a sua chave privada. Veja Autenticação. - Content-Type (texto) [obrigatório]: application/json - Idempotency-Key (texto): Opcional. Um código seu (até 80 caracteres) para repetir o pedido sem criar outra cobrança. Veja Repetição segura. ## Corpo - valor (inteiro) [obrigatório]: Valor em centavos. Mínimo R$ 1,00 (100). - descricao (texto): Até 200 caracteres. Aparece para o cliente. Vazio ou maior que isso vira "Cobrança". - referencia (texto): Um código seu (ex.: número do pedido), até 100 caracteres. Volta igual na resposta e nos webhooks. - expira_em_segundos (inteiro): Tempo para pagar. Padrão 900 (15 min), de 300 (5 min) a 900 (15 min), arredondado para minutos inteiros. Valor maior vira 900. - cliente (objeto) [obrigatório]: Quem vai pagar. - cliente.nome (texto) [obrigatório]: Nome completo (nome e sobrenome), de 3 a 150 caracteres. - cliente.email (texto) [obrigatório]: E-mail válido. - cliente.cpf (texto) [obrigatório]: CPF válido, com ou sem pontuação. - cliente.celular (texto): DDD + número de celular (aceita o 55 na frente). : Números vão como número (9700), textos como texto. Tipo errado recebe 422 dados_invalidos com o campo em campos. ## Exemplo **cURL** ``` curl -X POST https://app.grinnypay.com/api/v1/charges \ -H "Authorization: Bearer $GRINNY_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pedido-1042" \ -d '{ "valor": 9700, "descricao": "Curso de Marketing", "referencia": "pedido-1042", "expira_em_segundos": 900, "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com", "cpf": "52998224725", "celular": "11987654321" } }' ``` **PHP** ``` true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('GRINNY_KEY'), 'Content-Type: application/json', 'Idempotency-Key: pedido-1042', ], CURLOPT_POSTFIELDS => json_encode([ 'valor' => 9700, 'descricao' => 'Curso de Marketing', 'referencia' => 'pedido-1042', 'cliente' => ['nome' => 'Carlos Silva', 'email' => 'carlos@email.com', 'cpf' => '52998224725'], ]), ]); $resposta = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 201 = criada ``` **Node.js** ``` const resp = await fetch('https://app.grinnypay.com/api/v1/charges', { method: 'POST', headers: { Authorization: `Bearer ${process.env.GRINNY_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'pedido-1042', }, body: JSON.stringify({ valor: 9700, descricao: 'Curso de Marketing', referencia: 'pedido-1042', cliente: { nome: 'Carlos Silva', email: 'carlos@email.com', cpf: '52998224725' }, }), }); const cobranca = await resp.json(); // resp.status === 201 ``` ## Resposta 201 **JSON** ``` { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pendente", "valor": 9700, "taxa": 371, "liquido": 9329, "descricao": "Curso de Marketing", "pix_copia_e_cola": "00020101021226...", "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": null, "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1042" } ``` ## O objeto cobrança - id (texto): Identificador da cobrança (32 caracteres). Use em GET /charges/{id}. - status (texto): Veja Status. - valor (inteiro): Valor cobrado, em centavos. - taxa (inteiro): Taxa da Grinny Pay, em centavos. - liquido (inteiro): O que entra no seu saldo (valor menos a taxa e a comissão de afiliado, se houver). - descricao (texto): A descrição da cobrança. - pix_copia_e_cola (texto ou null): Código Pix para o QR Code e o "copia e cola". Só vem com status pendente. - link_pagamento (texto): Página pronta de pagamento, com QR Code e contador. - cliente (objeto): nome e email de quem paga. - expira_em (data): Até quando o Pix pode ser pago. - pago_em (data ou null): Quando o pagamento foi confirmado. - criado_em (data): Quando a cobrança foi criada. - referencia (texto ou null): O código que você mandou. ## Erros mais comuns HTTP | Código | Quando | 400 | json_invalido | Corpo não é JSON. | 422 | dados_invalidos | Valor, CPF, e-mail ou nome inválido. | 422 | valor_indisponivel | Este valor não está disponível agora para a sua conta. | 422 | recusado_antifraude | O antifraude recusou o Pix. | 429 | limite_pendentes, muitas_requisicoes, banco_no_limite | Limites: espere e tente de novo. | 503 | pix_indisponivel | Nenhum banco disponível: repita com a mesma Idempotency-Key. | Lista completa em Erros. ## Exemplos de resposta de erro **422 dados_invalidos** ``` { "erro": { "codigo": "dados_invalidos", "mensagem": "CPF inválido.", "campos": { "cpf": "CPF inválido." } } } ``` **422 tipo errado** ``` { "erro": { "codigo": "dados_invalidos", "mensagem": "valor: número inteiro em centavos (ex.: 9700 = R$ 97,00).", "campos": { "valor": "número inteiro em centavos" } } } ``` **429 limite_pendentes** ``` { "erro": { "codigo": "limite_pendentes", "mensagem": "A conta chegou ao teto de Pix pendentes em aberto. Espere alguns Pix serem pagos ou vencerem e tente de novo." } } ``` **503 pix_indisponivel** ``` { "erro": { "codigo": "pix_indisponivel", "mensagem": "Pix indisponível no momento. Tente de novo." } } ``` --- # Consultar cobrança https://app.grinnypay.com/docs?p=consultar-cobranca Seção: Cobranças GET /api/v1/charges/{id} Devolve uma cobrança da sua conta pelo id. Permissão: Criar/consultar transações. ## Parâmetros - id (texto (no caminho)) [obrigatório]: O id que veio ao criar a cobrança (32 caracteres). Se a cobrança ainda está pendente, a consulta pergunta ao banco na hora se ela foi paga (no máximo a cada 20 segundos por cobrança). Mesmo assim, o jeito certo de saber do pagamento é o webhook. ## Exemplo **cURL** ``` curl https://app.grinnypay.com/api/v1/charges/8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f \ -H "Authorization: Bearer $GRINNY_KEY" ``` **PHP** ``` true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('GRINNY_KEY')], ]); $cobranca = json_decode(curl_exec($ch), true); ``` **Node.js** ``` const resp = await fetch('https://app.grinnypay.com/api/v1/charges/8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f', { headers: { Authorization: `Bearer ${process.env.GRINNY_KEY}` }, }); const cobranca = await resp.json(); ``` ## Resposta 200 O objeto cobrança, igual ao da criação, com o status de agora. **JSON** ``` { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pago", "valor": 9700, "taxa": 371, "liquido": 9329, "descricao": "Curso de Marketing", "pix_copia_e_cola": null, "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": "2026-10-15T14:32:08-03:00", "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1042" } ``` : Cobrança que não existe (ou é de outra conta): 404 nao_encontrado. ## Exemplos de resposta de erro **404 nao_encontrado** ``` { "erro": { "codigo": "nao_encontrado", "mensagem": "Cobrança não encontrada." } } ``` --- # Listar cobranças https://app.grinnypay.com/docs?p=listar-cobrancas Seção: Cobranças GET /api/v1/charges Lista as cobranças da sua conta, da mais nova para a mais antiga. Permissão: Criar/consultar transações. ## Parâmetros (na URL) - limite (inteiro): Quantas por página. Padrão 20, de 1 a 100. - status (texto): Só um status: pendente, pago, expirado, med, contestado ou reembolsado. Outro valor é ignorado. - antes_de (texto): O id da última cobrança da página anterior: traz as que vieram antes dela. ## Exemplo **cURL** ``` curl "https://app.grinnypay.com/api/v1/charges?status=pago&limite=20" \ -H "Authorization: Bearer $GRINNY_KEY" ``` **Node.js** ``` const resp = await fetch('https://app.grinnypay.com/api/v1/charges?status=pago&limite=20', { headers: { Authorization: `Bearer ${process.env.GRINNY_KEY}` }, }); const { dados, tem_mais } = await resp.json(); ``` ## Resposta 200 **JSON** ``` { "dados": [ { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pago", "valor": 9700, "...": "..." }, { "id": "3a9d0c2e7b1f4e6d9c8b7a6f5e4d3c2b", "status": "pago", "valor": 4990, "...": "..." } ], "tem_mais": true } ``` - dados: lista de objetos cobrança. - tem_mais: true se existe outra página. Para buscá-la, mande antes_de com o id da última cobrança desta página. --- # Simular pagamento (teste) https://app.grinnypay.com/docs?p=simular-pagamento Seção: Cobranças POST /api/v1/charges/{id}/simulate-payment Marca uma cobrança de teste como paga e dispara o webhook venda.aprovada. Só existe com a chave de teste (gp_test_); veja o guia do modo de teste. ## Parâmetros - id (texto (no caminho)) [obrigatório]: O id da cobrança de teste (32 caracteres). Não tem corpo. ## Exemplo **cURL** ``` curl -X POST https://app.grinnypay.com/api/v1/sandbox/charges/8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f/simulate-payment \ -H "Authorization: Bearer $GRINNY_TEST_KEY" ``` **Node.js** ``` const resp = await fetch('https://app.grinnypay.com/api/v1/sandbox/charges/8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f/simulate-payment', { method: 'POST', headers: { Authorization: `Bearer ${process.env.GRINNY_TEST_KEY}` }, }); const cobranca = await resp.json(); ``` ## Resposta 200 com a cobrança já com status pago, pago_em preenchido e "livemode": false. Repetir a chamada devolve a mesma cobrança, sem novo webhook. ## Erros HTTP | Código | Quando | 403 | somente_chave_de_teste | Chave de produção (gp_live_) no endereço de teste. Cobrança real só é paga pelo Pix. | 404 | nao_encontrado | Cobrança de teste inexistente, de outra conta, ou é uma cobrança de produção. | 422 | dados_invalidos | A cobrança de teste já venceu: crie outra. | --- # Consultar saldo https://app.grinnypay.com/docs?p=saldo Seção: Conta GET /api/v1/balance Mostra o saldo da sua conta. Permissão: Consultar dados da conta e saldo. ## Exemplo **cURL** ``` curl https://app.grinnypay.com/api/v1/balance \ -H "Authorization: Bearer $GRINNY_KEY" ``` **Node.js** ``` const resp = await fetch('https://app.grinnypay.com/api/v1/balance', { headers: { Authorization: `Bearer ${process.env.GRINNY_KEY}` }, }); const saldo = await resp.json(); ``` ## Resposta 200 **JSON** ``` { "disponivel": 152340, "a_liberar": 48700, "total": 201040 } ``` - disponivel (inteiro): Pode sacar agora, em centavos. - a_liberar (inteiro): Vendas pagas que ainda vão ficar disponíveis (prazo de liberação), em centavos. - total (inteiro): disponivel + a_liberar. ## Exemplos de resposta de erro **403 sem_permissao** ``` { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem a permissão \"Consultar dados da conta e saldo\". Crie uma chave com ela em Integrações → API." } } ``` --- # Criar saque https://app.grinnypay.com/docs?p=criar-saque Seção: Saques POST /api/v1/withdrawals Pede um saque do seu saldo disponível: para a sua conta bancária cadastrada ou para uma chave Pix de outra pessoa. Permissão: Criar/consultar saques. Saque pela API só funciona com: chave com a permissão de saques (ela sempre tem validade), pelo menos um IP autorizado cadastrado em Integrações › API e o cabeçalho Idempotency-Key. Repetir o pedido com a mesma Idempotency-Key nunca cria dois saques. ## Cabeçalhos - Authorization (texto) [obrigatório]: Bearer + chave com a permissão de saques. - Content-Type (texto) [obrigatório]: application/json - Idempotency-Key (texto) [obrigatório]: Um código seu, único por saque (até 80 caracteres). Sem ele: 400 idempotency_key_obrigatoria. ## Corpo - valor (inteiro) [obrigatório]: Valor em centavos que a pessoa vai receber. A taxa de saque é cobrada à parte do seu saldo (veja total_debitado na resposta). - chave (texto): Chave Pix de terceiro (e-mail, celular, CPF, CNPJ ou chave aleatória). Só com a liberação do suporte (peça ao suporte); sem a liberação, o pedido com chave é recusado (422 saque_recusado). Sem ela, o dinheiro vai para a sua conta bancária cadastrada e aprovada. - documento (texto) [com chave de e-mail, celular ou aleatória]: CPF ou CNPJ do dono da chave. Conferimos com o dono antes de enviar. - descricao (texto): Até 140 caracteres, para você identificar o saque. - taxa_do_destinatario (true ou false): Só com chave: true desconta a taxa do valor enviado. Precisa ser booleano de verdade (sem aspas). ## Exemplo **cURL** ``` curl -X POST https://app.grinnypay.com/api/v1/withdrawals \ -H "Authorization: Bearer $GRINNY_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: saque-2026-10-15-1" \ -d '{ "valor": 15000, "chave": "fornecedor@email.com", "documento": "52998224725", "descricao": "Pagamento do fornecedor" }' ``` **PHP** ``` true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('GRINNY_KEY'), 'Content-Type: application/json', 'Idempotency-Key: saque-2026-10-15-1', ], CURLOPT_POSTFIELDS => json_encode(['valor' => 15000]), // sem "chave": vai pra sua conta cadastrada ]); $saque = json_decode(curl_exec($ch), true); ``` ## Resposta 201 **JSON** ``` { "id": 482, "status": "processando", "valor": 15000, "taxa": 367, "total_debitado": 15367, "destino": { "tipo": "chave_pix", "chave": "fornecedor@email.com" }, "motivo": null, "criado_em": "2026-10-15T14:40:00-03:00", "concluido_em": null } ``` ## O objeto saque - id (inteiro): Número do saque. Use em GET /withdrawals/{id}. - status (texto): aguardando_sua_aprovacao, em_analise, processando, concluido ou cancelado. Veja Status. - valor (inteiro): Valor do saque, em centavos. - taxa (inteiro): Taxa do saque, em centavos. - total_debitado (inteiro): Quanto saiu do seu saldo. - destino (objeto): tipo: chave_pix ou conta_cadastrada; chave: a chave Pix de destino. - motivo (texto ou null): Em análise: "Em conferência de segurança". Cancelado: por que não saiu. - criado_em (data): Quando o saque foi pedido. - concluido_em (data ou null): Quando o dinheiro saiu. ## Erros mais comuns HTTP | Código | Quando | 400 | idempotency_key_obrigatoria | Faltou a Idempotency-Key. | 400 | json_invalido | Corpo não é JSON ou falta o valor inteiro. | 403 | ip_obrigatorio | Nenhum IP autorizado cadastrado. | 403 | sem_permissao | A chave não tem a permissão de saques. | 422 | 2fa_obrigatorio | O vendedor não ligou o 2FA (verificação em 2 etapas) na conta. Sem ele, não há saque, nem pela API. Ligue em Configurações › Segurança. | 422 | saque_recusado | Saldo insuficiente, abaixo do mínimo, saques pausados, pedido repetido…: a mensagem diz o motivo. | 422 | sem_conta_bancaria e parecidos | Problema na sua conta bancária cadastrada. | ## Exemplos de resposta de erro **400 idempotency_key_obrigatoria** ``` { "erro": { "codigo": "idempotency_key_obrigatoria", "mensagem": "Saque pela API exige o cabeçalho Idempotency-Key (até 80 letras, números, - _ : .)." } } ``` **403 ip_obrigatorio** ``` { "erro": { "codigo": "ip_obrigatorio", "mensagem": "Saque pela API precisa de pelo menos um IP autorizado em Integrações → API." } } ``` **422 saque_recusado** ``` { "erro": { "codigo": "saque_recusado", "mensagem": "Saldo disponível insuficiente: você tem R$ 100,00 e o saque + taxa dá R$ 153,67." } } ``` --- # Consultar saque https://app.grinnypay.com/docs?p=consultar-saque Seção: Saques GET /api/v1/withdrawals/{id} Devolve um saque da sua conta pelo número. Permissão: Criar/consultar saques. ## Parâmetros - id (inteiro (no caminho)) [obrigatório]: O id que veio ao criar o saque. ## Exemplo **cURL** ``` curl https://app.grinnypay.com/api/v1/withdrawals/482 \ -H "Authorization: Bearer $GRINNY_KEY" ``` ## Resposta 200 **JSON** ``` { "id": 482, "status": "concluido", "valor": 15000, "taxa": 367, "total_debitado": 15367, "destino": { "tipo": "chave_pix", "chave": "fornecedor@email.com" }, "motivo": null, "criado_em": "2026-10-15T14:40:00-03:00", "concluido_em": "2026-10-15T14:40:12-03:00" } ``` : Campos explicados em O objeto saque. Saque que não existe (ou é de outra conta): 404 nao_encontrado. ## Exemplos de resposta de erro **404 nao_encontrado** ``` { "erro": { "codigo": "nao_encontrado", "mensagem": "Saque não encontrado." } } ``` --- # Listar saques https://app.grinnypay.com/docs?p=listar-saques Seção: Saques GET /api/v1/withdrawals Lista os saques mais recentes da sua conta. Permissão: Criar/consultar saques. ## Parâmetros (na URL) - limite (inteiro): Quantos trazer. Padrão 20, de 1 a 100. Esta lista não tem paginação: traz só os mais recentes. ## Exemplo **cURL** ``` curl "https://app.grinnypay.com/api/v1/withdrawals?limite=20" \ -H "Authorization: Bearer $GRINNY_KEY" ``` ## Resposta 200 **JSON** ``` { "dados": [ { "id": 482, "status": "concluido", "valor": 15000, "...": "..." }, { "id": 471, "status": "cancelado", "valor": 5000, "motivo": "Saldo insuficiente", "...": "..." } ] } ``` : dados é uma lista de objetos saque. --- # Como funcionam https://app.grinnypay.com/docs?p=webhooks Seção: Webhooks Webhook é um aviso que a Grinny Pay manda para o seu servidor quando algo acontece: Pix gerado, Pix pago, MED aberto, saque concluído. Assim você não precisa ficar consultando a API. ## Como cadastrar - No painel, em Integrações › Webhooks (pede a verificação em duas etapas). Até 5 webhooks por conta. - A URL precisa ser https na porta padrão (443), com um domínio (não vale IP digitado nem localhost), até 500 caracteres. - Escolha os eventos que quer receber. Veja Eventos. - Ao criar, aparece o segredo do webhook (começa com whsec_) uma única vez. Guarde: é com ele que você confere a assinatura. ## O que chega no seu servidor Um POST com o corpo em JSON e estes cabeçalhos: **Cabeçalhos** ``` POST /seu/endereco HTTP/1.1 Content-Type: application/json User-Agent: GrinnyPay-Webhook/1 X-Grinny-Event: venda.aprovada X-Grinny-Signature: t=1760549530,v1=5f2b8c...e91a ``` **Corpo** ``` { "id": "evt_5821", "tipo": "venda.aprovada", "sequencia": 5821, "criado_em": "2026-10-15T14:32:10-03:00", "dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pago", "valor": 9700, "...": "o mesmo objeto cobrança da API" } } ``` - id (texto): Identificador do evento. Use para não processar o mesmo evento duas vezes. - tipo (texto): O evento. Veja Eventos. - sequencia (inteiro): Cresce na ordem em que os eventos aconteceram. Use para ignorar evento atrasado. - criado_em (data): Quando o evento aconteceu. - dados (objeto): A cobrança, o saque ou o MED como estava no momento do evento (mesmo numa nova tentativa de entrega). ## Como responder - Responda com qualquer status 2xx em até 5 segundos. Só isso conta como entregue. - Faça o trabalho pesado depois de responder (por exemplo, numa fila). - Lemos no máximo 64 KB da sua resposta: não precisa mandar corpo. ## Novas tentativas Se o seu servidor não responder 2xx a tempo, tentamos de novo depois de cerca de 1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 12 h. São 8 tentativas no total (a primeira e mais 7). Depois disso, o envio fica como falhou e você pode reenviar pelo painel. Detalhes em Entrega e reenvio. As entregas podem chegar fora de ordem e repetidas. Guarde o id dos eventos já processados e, para a mesma cobrança, ignore evento com sequencia menor que a do último que você processou. Exemplo: um venda.expirada atrasado chegando depois do venda.aprovada. ## Testar O botão Testar do painel manda um evento teste.ping (sem sequencia) para a sua URL. Ele não tenta de novo sozinho. **teste.ping** ``` { "id": "evt_5830", "tipo": "teste.ping", "criado_em": "2026-10-15T14:50:00-03:00", "dados": { "mensagem": "Envio de teste da Grinny Pay. Pode ignorar.", "webhook": 12 } } ``` --- # Todos os eventos https://app.grinnypay.com/docs?p=webhooks-eventos Seção: Webhooks Todos os eventos que o seu servidor pode receber. Cada família tem uma página com a tabela de campos e o JSON completo de cada evento. ## Lista de eventos Evento | Quando | dados | Detalhes | venda.criada | Venda criada (Pix gerado) | Cobrança | Ver JSON | venda.aprovada | Venda aprovada | Cobrança | Ver JSON | venda.expirada | Pix expirado | Cobrança | Ver JSON | venda.reembolsada | Venda reembolsada | Cobrança | Ver JSON | med.aberto | MED aberto | MED | Ver JSON | med.encerrado | MED encerrado | MED | Ver JSON | saque.concluido | Saque concluído | Saque | Ver JSON | saque.falhou | Saque não realizado | Saque | Ver JSON | venda.contestada | Venda contestada (MED perdido) | Cobrança | Ver JSON | teste.ping | Botão Testar do painel. | Mensagem | Ver JSON | ## Famílias Página | Eventos | dados | Venda | venda.criada, venda.aprovada, venda.expirada, venda.reembolsada, venda.contestada | Objeto cobrança | MED | med.aberto, med.encerrado | Disputa (med_) | Saque | saque.concluido, saque.falhou | Saque (saq_) | Teste | teste.ping | Mensagem | ## Formato de todo evento Todo aviso chega no mesmo envelope. Só o conteúdo de dados muda de uma família para outra. **Envelope** ``` { "id": "evt_5821", "tipo": "venda.aprovada", "sequencia": 5821, "criado_em": "2026-10-15T14:32:10-03:00", "livemode": true, "dados": { "...": "depende do evento" } } ``` - id (texto): Identificador do evento (evt_ + número). Não muda nas novas tentativas: use para ignorar repetição. - tipo (texto): O nome do evento, igual ao cabeçalho X-Grinny-Event. - sequencia (inteiro): Cresce na ordem em que os eventos aconteceram. Não vem no teste.ping. - criado_em (data): Quando o evento aconteceu. - livemode (booleano): true em venda de verdade, false em evento da chave de teste (veja Modo de teste). Não vem no teste.ping. - dados (objeto): O conteúdo do evento, como estava naquele momento (mesmo numa nova tentativa). Ao cadastrar o webhook no painel você escolhe quais eventos quer receber. Evento que você não escolheu nunca é enviado para aquela URL. --- # Venda https://app.grinnypay.com/docs?p=webhooks-venda Seção: Eventos por família Eventos de venda: o Pix foi gerado, pago, venceu, foi devolvido ou contestado. Em todos eles dados é o objeto cobrança, como estava no momento do evento. ## Eventos desta família Evento | Quando chega | dados.status | O que fazer | venda.criada | Um Pix foi gerado (checkout, link, painel ou API). | pendente | Guardar o pedido como "aguardando pagamento". | venda.aprovada | O banco confirmou o pagamento. | pago | Liberar o acesso. | venda.expirada | O Pix venceu sem pagamento. | expirado | Cancelar o pedido ou criar outra cobrança. | venda.reembolsada | A venda foi devolvida ao comprador. | reembolsado | Tirar o acesso. | venda.contestada | Um MED foi decidido a favor do comprador: o valor foi devolvido. | contestado | Tirar o acesso. | venda.contestada sai do mesmo fato que o med.encerrado com status: "perdida" (veja MED). Você recebe os dois, em eventos diferentes: um sobre a disputa e outro sobre a venda. ## Campos de dados - id (texto): Identificador da cobrança (32 caracteres). - status (texto): Veja Status. - valor (inteiro): Valor cobrado, em centavos. - taxa (inteiro): Taxa da Grinny Pay, em centavos. - liquido (inteiro): O que entra no seu saldo, em centavos. - descricao (texto): Descrição da cobrança. - pix_copia_e_cola (texto ou null): Só vem no venda.criada (cobrança pendente). - link_pagamento (texto): Página de pagamento. - cliente (objeto): nome e email. - expira_em (data): Limite para pagar. - pago_em (data ou null): Hora do pagamento (null antes de pagar). - criado_em (data): Hora em que a cobrança foi criada. - referencia (texto ou null): O código que você mandou ao criar (ex.: número do pedido). Use para achar o pedido no seu sistema. ## venda.criada **venda.criada** ``` { "id": "evt_5820", "tipo": "venda.criada", "sequencia": 5820, "criado_em": "2026-10-15T14:30:01-03:00", "dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pendente", "valor": 9700, "taxa": 371, "liquido": 9329, "descricao": "Curso de Marketing", "pix_copia_e_cola": "00020101021226...", "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": null, "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1042" } } ``` ## venda.aprovada **venda.aprovada** ``` { "id": "evt_5821", "tipo": "venda.aprovada", "sequencia": 5821, "criado_em": "2026-10-15T14:32:10-03:00", "dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "pago", "valor": 9700, "taxa": 371, "liquido": 9329, "descricao": "Curso de Marketing", "pix_copia_e_cola": null, "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": "2026-10-15T14:32:08-03:00", "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1042" } } ``` ## venda.expirada **venda.expirada** ``` { "id": "evt_5822", "tipo": "venda.expirada", "sequencia": 5822, "criado_em": "2026-10-15T14:46:00-03:00", "dados": { "id": "3a9d0c2e7b1f4e6d9c8b7a6f5e4d3c2b", "status": "expirado", "valor": 4990, "taxa": 191, "liquido": 4799, "descricao": "Ebook de Receitas", "pix_copia_e_cola": null, "link_pagamento": "https://app.grinnypay.com/pix?c=3a9d0c2e7b1f4e6d9c8b7a6f5e4d3c2b", "cliente": { "nome": "Maria Souza", "email": "maria@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": null, "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1043" } } ``` ## venda.reembolsada **venda.reembolsada** ``` { "id": "evt_5990", "tipo": "venda.reembolsada", "sequencia": 5990, "criado_em": "2026-10-18T10:05:00-03:00", "dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "reembolsado", "valor": 9700, "taxa": 371, "liquido": 9329, "descricao": "Curso de Marketing", "pix_copia_e_cola": null, "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": "2026-10-15T14:32:08-03:00", "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1042" } } ``` ## venda.contestada **venda.contestada** ``` { "id": "evt_6015", "tipo": "venda.contestada", "sequencia": 6015, "criado_em": "2026-10-22T16:20:00-03:00", "dados": { "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "status": "contestado", "valor": 9700, "taxa": 371, "liquido": 9329, "descricao": "Curso de Marketing", "pix_copia_e_cola": null, "link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "cliente": { "nome": "Carlos Silva", "email": "carlos@email.com" }, "expira_em": "2026-10-15T14:45:00-03:00", "pago_em": "2026-10-15T14:32:08-03:00", "criado_em": "2026-10-15T14:30:00-03:00", "referencia": "pedido-1042" } } ``` Quando uma disputa é aberta, o aviso que chega é o med.aberto, com dados da disputa (não da cobrança). --- # MED https://app.grinnypay.com/docs?p=webhooks-med Seção: Eventos por família MED é o pedido de devolução que o banco do comprador abre (fraude ou golpe). O valor da venda fica bloqueado no seu saldo até a decisão. Aqui dados descreve a disputa, não a cobrança. ## Eventos desta família Evento | Quando chega | dados.status | med.aberto | O banco do comprador abriu o MED. | aberta | med.encerrado | O MED foi decidido. | ganha (valor liberado) ou perdida (valor devolvido ao comprador) | Se o MED é perdido, chega também o venda.contestada, com a cobrança. ## Campos de dados - id (texto): Identificador do MED: med_ + número. - cobranca (texto): O id da cobrança contestada. - valor (inteiro): Valor contestado, em centavos. - status (texto): Situação do MED no momento do aviso: aberta, em_defesa, ganha ou perdida. ## med.aberto **med.aberto** ``` { "id": "evt_6010", "tipo": "med.aberto", "sequencia": 6010, "criado_em": "2026-10-20T09:12:00-03:00", "dados": { "id": "med_37", "cobranca": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "valor": 9700, "status": "aberta" } } ``` ## med.encerrado **Perdido** ``` { "id": "evt_6014", "tipo": "med.encerrado", "sequencia": 6014, "criado_em": "2026-10-22T16:19:50-03:00", "dados": { "id": "med_37", "cobranca": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f", "valor": 9700, "status": "perdida" } } ``` **Ganho** ``` { "id": "evt_6030", "tipo": "med.encerrado", "sequencia": 6030, "criado_em": "2026-10-23T11:00:00-03:00", "dados": { "id": "med_38", "cobranca": "3a9d0c2e7b1f4e6d9c8b7a6f5e4d3c2b", "valor": 4990, "status": "ganha" } } ``` Use o campo cobranca para achar o pedido no seu sistema (pelo id da cobrança guardado quando você a criou). A defesa do MED é feita pelo painel, em Transações: a API ainda não tem rota para isso. --- # Saque https://app.grinnypay.com/docs?p=webhooks-saque Seção: Eventos por família Eventos de saque: o dinheiro saiu ou o saque não foi realizado. Valem para saques pedidos pelo painel e pela API. ## Eventos desta família Evento | Quando chega | dados.status | saque.concluido | O banco confirmou o envio do dinheiro. | concluido | saque.falhou | O saque foi recusado ou não pôde ser realizado. O valor volta para o seu saldo. | falhou ou recusado | ## Campos de dados - id (texto): Identificador do saque: saq_ + número. Na API o mesmo saque tem id só com o número (482). - valor (inteiro): Valor do saque, em centavos. - taxa (inteiro): Taxa do saque, em centavos. - status (texto): Status interno do saque: concluido, falhou ou recusado. - criado_em (texto): Quando o saque foi pedido, no formato AAAA-MM-DD HH:MM:SS (horário de Brasília). - concluido_em (texto ou null): Quando o dinheiro saiu, no mesmo formato. null se não saiu. O objeto de saque do webhook é diferente do objeto da API: o id traz o prefixo saq_, as datas não têm fuso e o status é o interno. Para o formato da API, consulte Consultar saque com o número. ## saque.concluido **saque.concluido** ``` { "id": "evt_6122", "tipo": "saque.concluido", "sequencia": 6122, "criado_em": "2026-10-15T14:40:12-03:00", "dados": { "id": "saq_482", "valor": 15000, "taxa": 367, "status": "concluido", "criado_em": "2026-10-15 14:40:00", "concluido_em": "2026-10-15 14:40:12" } } ``` ## saque.falhou **saque.falhou** ``` { "id": "evt_6140", "tipo": "saque.falhou", "sequencia": 6140, "criado_em": "2026-10-16T09:02:30-03:00", "dados": { "id": "saq_483", "valor": 5000, "taxa": 367, "status": "falhou", "criado_em": "2026-10-16 09:00:00", "concluido_em": null } } ``` : O motivo não vem no aviso. Consulte GET /withdrawals/{id}: o campo motivo do saque cancelado diz por que não saiu. --- # Teste (teste.ping) https://app.grinnypay.com/docs?p=webhooks-teste Seção: Eventos por família Para conferir se o seu endereço recebe e valida os avisos antes de uma venda de verdade, use o botão Testar do webhook no painel (Integrações › Webhooks). ## Como funciona - O botão manda na hora um evento teste.ping, com a mesma assinatura e os mesmos cabeçalhos dos eventos reais. - O endereço passa pela mesma checagem (https, domínio que aponta para um servidor público). - O teste não tenta de novo sozinho: se o seu servidor falhar, o painel mostra o código HTTP ou o erro. - Existe um limite de testes seguidos (10 a cada 10 minutos por conta). - O teste não vira venda, não mexe em saldo e não vai para os outros webhooks nem para o celular. ## O evento teste.ping **teste.ping** ``` { "id": "evt_5830", "tipo": "teste.ping", "criado_em": "2026-10-15T14:50:00-03:00", "dados": { "mensagem": "Envio de teste da Grinny Pay. Pode ignorar.", "webhook": 12 } } ``` - id (texto): Identificador do evento (evt_ + número). - tipo (texto): Sempre teste.ping. - criado_em (data): Hora do envio. - dados.mensagem (texto): Texto fixo de teste. - dados.webhook (inteiro): Número do seu webhook no painel. O teste.ping não tem o campo sequencia. Se o seu código lê sequencia de todo evento, trate a falta dele. Responda 2xx e ignore o conteúdo. ## O que conferir no teste - O seu endereço respondeu 2xx em até 5 segundos. - A assinatura bateu (o teste usa o mesmo segredo dos eventos reais). - O corpo foi lido cru antes de virar JSON. - O seu código não quebra com evento que não conhece. --- # Conferir a assinatura https://app.grinnypay.com/docs?p=webhooks-assinatura Seção: Receber com segurança Todo webhook vem assinado. Confira a assinatura antes de confiar no conteúdo: assim ninguém finge ser a Grinny Pay para liberar um acesso. ## Como funciona O cabeçalho X-Grinny-Signature traz o horário do envio (t, em segundos desde 1970) e a assinatura (v1): **Cabeçalho** ``` X-Grinny-Signature: t=1760549530,v1=5f2b8c0d...e91a ``` - Pegue o corpo cru do pedido, exatamente como chegou (antes de transformar em JSON). - Monte o texto t + "." + corpo. - Calcule o HMAC-SHA256 desse texto com o segredo do webhook (whsec_...), em hexadecimal. - Compare com o v1 usando uma comparação segura (tempo constante). - Recuse se o t estiver a mais de 5 minutos do seu relógio. - Ignore se já processou um evento com o mesmo id. ## Exemplos **PHP** ``` 300) { http_response_code(401); exit; } $evento = json_decode($corpo, true); // Já processou este $evento['id']? Responda 200 e pare aqui. if ($evento['tipo'] === 'venda.aprovada') { // libere o acesso do pedido $evento['dados']['referencia'] } http_response_code(200); ``` **Node.js** ``` import crypto from 'node:crypto'; import express from 'express'; const app = express(); // Corpo cru: a assinatura é calculada sobre os bytes exatos que chegaram. app.post('/webhooks/grinny', express.raw({ type: 'application/json' }), (req, res) => { const partes = Object.fromEntries( String(req.get('X-Grinny-Signature') || '').split(',').map((p) => p.split('=')) ); const esperado = crypto .createHmac('sha256', process.env.GRINNY_WEBHOOK_SECRET) .update(`${partes.t}.${req.body}`) .digest('hex'); const ok = partes.v1 && partes.v1.length === esperado.length && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1)); if (!ok || Math.abs(Date.now() / 1000 - Number(partes.t)) > 300) return res.sendStatus(401); const evento = JSON.parse(req.body); // Já processou evento.id? Responda 200 e pare aqui. if (evento.tipo === 'venda.aprovada') { // libere o acesso do pedido evento.dados.referencia } res.sendStatus(200); }); ``` **Python** ``` import hashlib import hmac import os import time from flask import Flask, request app = Flask(__name__) def assinatura_valida(corpo: bytes, cabecalho: str) -> bool: partes = dict(p.split("=", 1) for p in cabecalho.split(",") if "=" in p) t, v1 = partes.get("t", ""), partes.get("v1", "") if not t.isdigit() or abs(time.time() - int(t)) > 300: return False esperado = hmac.new( os.environ["GRINNY_WEBHOOK_SECRET"].encode(), t.encode() + b"." + corpo, hashlib.sha256, ).hexdigest() return hmac.compare_digest(esperado, v1) @app.post("/webhooks/grinny") def webhook(): # get_data() devolve os bytes exatos que chegaram (antes de virar JSON). corpo = request.get_data() if not assinatura_valida(corpo, request.headers.get("X-Grinny-Signature", "")): return "", 401 evento = request.get_json(force=True) # Já processou evento["id"]? Responda 200 e pare aqui. if evento["tipo"] == "venda.aprovada": pass # libere o acesso do pedido evento["dados"]["referencia"] return "", 200 ``` **Go** ``` package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "encoding/json" "io" "net/http" "os" "strconv" "strings" "time" ) func assinaturaValida(corpo []byte, cabecalho string) bool { var t, v1 string for _, p := range strings.Split(cabecalho, ",") { kv := strings.SplitN(p, "=", 2) if len(kv) != 2 { continue } switch kv[0] { case "t": t = kv[1] case "v1": v1 = kv[1] } } ts, err := strconv.ParseInt(t, 10, 64) if err != nil || time.Now().Unix()-ts > 300 || ts-time.Now().Unix() > 300 { return false } mac := hmac.New(sha256.New, []byte(os.Getenv("GRINNY_WEBHOOK_SECRET"))) mac.Write([]byte(t + "." + string(corpo))) esperado := hex.EncodeToString(mac.Sum(nil)) return hmac.Equal([]byte(esperado), []byte(v1)) } func webhook(w http.ResponseWriter, r *http.Request) { corpo, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20)) if err != nil || !assinaturaValida(corpo, r.Header.Get("X-Grinny-Signature")) { w.WriteHeader(http.StatusUnauthorized) return } var evento struct { ID string `json:"id"` Tipo string `json:"tipo"` Dados json.RawMessage `json:"dados"` } if json.Unmarshal(corpo, &evento) != nil { w.WriteHeader(http.StatusBadRequest) return } // Já processou evento.ID? Responda 200 e pare aqui. if evento.Tipo == "venda.aprovada" { // libere o acesso do pedido (leia "referencia" em evento.Dados) } w.WriteHeader(http.StatusOK) } func main() { http.HandleFunc("/webhooks/grinny", webhook) http.ListenAndServe(":3000", nil) } ``` Nunca libere acesso só porque chegou um POST no seu endereço. Sem conferir a assinatura, qualquer pessoa que descobrir a URL consegue mandar um falso venda.aprovada. ## Se o segredo vazar Exclua o webhook no painel e cadastre de novo: nasce um segredo novo. Atualize o seu servidor antes de apagar o antigo para não perder avisos. --- # Receptor completo https://app.grinnypay.com/docs?p=webhooks-exemplo Seção: Receber com segurança Um receptor completo, do pedido chegando até a resposta: confere a assinatura, ignora evento repetido, ignora evento atrasado e responde rápido. Copie e troque só o trecho "libere o acesso". ## O que o código faz - Lê o corpo cru do pedido. - Confere a assinatura e a hora (até 5 minutos de diferença). Falhou: 401. - Grava o id do evento. Já existia: responde 200 sem fazer nada (repetição). - Compara a sequencia com a última já processada daquela cobrança. Menor: ignora (evento atrasado). - Trata o evento e responde 200 em até 5 segundos. ## Código **PHP** ``` PDO::ERRMODE_EXCEPTION]); $corpo = file_get_contents('php://input'); parse_str(str_replace(',', '&', $_SERVER['HTTP_X_GRINNY_SIGNATURE'] ?? ''), $s); $esperado = hash_hmac('sha256', ($s['t'] ?? '') . '.' . $corpo, getenv('GRINNY_WEBHOOK_SECRET')); if (!hash_equals($esperado, $s['v1'] ?? '') || abs(time() - (int) ($s['t'] ?? 0)) > 300) { http_response_code(401); exit; } $evento = json_decode($corpo, true); if (!is_array($evento) || !isset($evento['id'], $evento['tipo'])) { http_response_code(400); exit; } if ($evento['tipo'] === 'teste.ping') { http_response_code(200); // botão Testar do painel exit; } // Qual cobrança, MED ou saque é este evento? $d = $evento['dados']; $recurso = $d['cobranca'] ?? $d['id']; $seq = (int) ($evento['sequencia'] ?? 0); $pdo->beginTransaction(); // 1) Repetição: o mesmo id nunca é tratado duas vezes. $novo = $pdo->prepare('INSERT IGNORE INTO eventos_grinny (id, recurso, sequencia) VALUES (?, ?, ?)'); $novo->execute([$evento['id'], $recurso, $seq]); if ($novo->rowCount() === 0) { $pdo->commit(); http_response_code(200); exit; } // 2) Atrasado: já tratei um evento mais novo deste mesmo recurso? $mais = $pdo->prepare('SELECT MAX(sequencia) FROM eventos_grinny WHERE recurso = ? AND id <> ?'); $mais->execute([$recurso, $evento['id']]); if ((int) $mais->fetchColumn() > $seq) { $pdo->commit(); http_response_code(200); exit; } switch ($evento['tipo']) { case 'venda.aprovada': // libere o acesso do pedido $d['referencia'] (valor pago: $d['valor'] centavos) break; case 'venda.reembolsada': case 'venda.contestada': // tire o acesso do pedido $d['referencia'] break; case 'venda.expirada': // cancele o pedido $d['referencia'] break; case 'med.aberto': case 'med.encerrado': case 'saque.concluido': case 'saque.falhou': // registre no seu financeiro break; } $pdo->commit(); http_response_code(200); ``` **Node.js** ``` // webhook.js: Node 18+ com Express. Troque o Map por uma tabela no seu banco. import crypto from 'node:crypto'; import express from 'express'; const app = express(); const vistos = new Set(); // ids de evento já tratados const ultimaSequencia = new Map(); // recurso -> maior sequência tratada function assinaturaValida(req) { const p = Object.fromEntries( String(req.get('X-Grinny-Signature') || '').split(',').map((x) => x.split('=')), ); const esperado = crypto .createHmac('sha256', process.env.GRINNY_WEBHOOK_SECRET) .update(`${p.t}.${req.body}`) .digest('hex'); const iguais = p.v1 && p.v1.length === esperado.length && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(p.v1)); return iguais && Math.abs(Date.now() / 1000 - Number(p.t)) <= 300; } // express.raw: o corpo chega como Buffer, sem virar JSON antes da conferência. app.post('/webhooks/grinny', express.raw({ type: 'application/json' }), (req, res) => { if (!assinaturaValida(req)) return res.sendStatus(401); const evento = JSON.parse(req.body); if (evento.tipo === 'teste.ping') return res.sendStatus(200); // 1) Repetição if (vistos.has(evento.id)) return res.sendStatus(200); vistos.add(evento.id); // 2) Atrasado const d = evento.dados; const recurso = d.cobranca || d.id; if ((ultimaSequencia.get(recurso) || 0) > evento.sequencia) return res.sendStatus(200); ultimaSequencia.set(recurso, evento.sequencia); switch (evento.tipo) { case 'venda.aprovada': // libere o acesso do pedido d.referencia (valor pago: d.valor centavos) break; case 'venda.reembolsada': case 'venda.contestada': // tire o acesso do pedido d.referencia break; case 'venda.expirada': // cancele o pedido d.referencia break; default: // med.* e saque.*: registre no seu financeiro } res.sendStatus(200); // responda rápido; trabalho pesado vai para uma fila }); app.listen(3000); ``` ## Cuidados - Responda primeiro, trabalhe depois. Se o trabalho demora (e-mail, nota fiscal), grave numa fila e responda 200 na hora. Passou de 5 segundos conta como falha e o evento volta. - A conferência de repetição precisa ser atômica. No exemplo PHP o INSERT IGNORE com chave primária faz isso: dois avisos iguais ao mesmo tempo não passam os dois. - Erro seu = devolva 5xx. Se o banco do seu sistema caiu, responda 500 (e desfaça o registro do evento): assim ele volta mais tarde. Responder 200 sem ter tratado perde a venda. - Evento desconhecido: responda 200 e ignore. Novos eventos podem surgir. No exemplo PHP, o 200 do "já vi este evento" só vale porque o tratamento anterior terminou. Se o seu código gravar o id e depois falhar, desfaça (rollBack) e responda 500, como a transação do exemplo faz quando uma exceção sobe. --- # Entrega e reenvio https://app.grinnypay.com/docs?p=webhooks-reentregas Seção: Receber com segurança O que acontece quando o seu servidor não responde, quando o mesmo aviso chega duas vezes e como reenviar um aviso pelo painel. ## O que conta como entregue Um aviso só está entregue se o seu servidor responder com status 2xx em até 5 segundos. Qualquer outra coisa (4xx, 5xx, demora, erro de conexão, certificado inválido) conta como falha e o aviso entra na fila de novas tentativas. Lemos no máximo 64 KB da resposta e guardamos só o começo dela, para você ver no painel. ## Novas tentativas São até 8 tentativas no total: a primeira e mais 7. Entre uma e outra a espera cresce: Tentativa | Quando acontece | 1ª | Logo depois do evento | 2ª | cerca de 1 minuto depois da 1ª | 3ª | cerca de 5 minutos depois da 2ª | 4ª | cerca de 15 minutos depois da 3ª | 5ª | cerca de 1 hora depois da 4ª | 6ª | cerca de 3 horas depois da 5ª | 7ª | cerca de 6 horas depois da 6ª | 8ª (última) | cerca de 12 horas depois da 7ª | Os horários são aproximados (a fila roda em ciclos curtos). Depois da 8ª falha o envio fica como falhou e não tenta mais sozinho. Com todas as tentativas, o seu servidor tem cerca de 22 horas para voltar. Passou disso, use o reenvio do painel e a conciliação para recuperar o que perdeu. ## Repetição e ordem - O mesmo aviso pode chegar mais de uma vez (a sua resposta se perdeu no caminho, por exemplo). O id do evento é sempre o mesmo: guarde os já tratados. - Os avisos podem chegar fora de ordem. Um venda.expirada que falhou e foi reenviado pode chegar depois do venda.aprovada da mesma cobrança. Use a sequencia: ignore o evento com sequência menor que a última que você tratou daquele recurso. - O conteúdo de dados é o do momento do evento, também nas novas tentativas. Para saber como a cobrança está agora, consulte GET /charges/{id}. - id (texto): Mesmo valor em todas as tentativas do mesmo evento: é a chave da sua idempotência. - sequencia (inteiro): Ordem em que os eventos aconteceram na conta. Evento mais novo tem número maior. - X-Grinny-Event (cabeçalho): O tipo do evento, para você roteirizar antes de ler o corpo. - X-Grinny-Signature (cabeçalho): Horário e assinatura. A assinatura é nova a cada tentativa (muda o t): confira sempre a que veio no pedido. ## Reenviar pelo painel - Em Integrações › Webhooks você vê os envios, o código que o seu servidor respondeu e o começo da resposta. - O botão de reenvio põe o aviso de volta na fila, com a contagem de tentativas zerada. - Existe um limite de reenvios seguidos por conta (para ninguém derrubar o próprio servidor por engano). - Webhook pausado não recebe nada: os avisos esperam e saem quando você ativa de novo. - Webhook excluído para na hora e as entregas pendentes dele são descartadas. ## Por quanto tempo guardamos O conteúdo dos avisos enviados (que inclui o nome e o e-mail do comprador) fica guardado por tempo limitado e depois é apagado. O histórico de que o envio aconteceu continua. Por isso, não conte com o painel como arquivo: grave o que importa no seu sistema.