Cobranças

Criar cobrança Pix

POST/api/v1/charges

Cria uma cobrança Pix avulsa, com valor livre. Permissão: Criar/consultar transações.

Cabeçalhos

Authorizationtextoobrigatório

Bearer + a sua chave privada. Veja Autenticação.

Content-Typetextoobrigatório

application/json

Idempotency-Keytexto

Opcional. Um código seu (até 80 caracteres) para repetir o pedido sem criar outra cobrança. Veja Repetição segura.

Corpo

valorinteiroobrigatório

Valor em centavos. Mínimo R$ 1,00 (100).

descricaotexto

Até 200 caracteres. Aparece para o cliente. Vazio ou maior que isso vira "Cobrança".

referenciatexto

Um código seu (ex.: número do pedido), até 100 caracteres. Volta igual na resposta e nos webhooks.

expira_em_segundosinteiro

Tempo para pagar. Padrão 900 (15 min), de 300 (5 min) a 900 (15 min), arredondado para minutos inteiros. Valor maior vira 900.

clienteobjetoobrigatório

Quem vai pagar.

cliente.nometextoobrigatório

Nome completo (nome e sobrenome), de 3 a 150 caracteres.

cliente.emailtextoobrigatório

E-mail válido.

cliente.cpftextoobrigatório

CPF válido, com ou sem pontuação.

cliente.celulartexto

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 -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": "[email protected]",
      "cpf": "52998224725",
      "celular": "11987654321"
    }
  }'

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": "[email protected]" },
  "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

idtexto

Identificador da cobrança (32 caracteres). Use em GET /charges/{id}.

statustexto

Veja Status.

valorinteiro

Valor cobrado, em centavos.

taxainteiro

Taxa da Grinny Pay, em centavos.

liquidointeiro

O que entra no seu saldo (valor menos a taxa e a comissão de afiliado, se houver).

descricaotexto

A descrição da cobrança.

pix_copia_e_colatexto ou null

Código Pix para o QR Code e o "copia e cola". Só vem com status pendente.

link_pagamentotexto

Página pronta de pagamento, com QR Code e contador.

clienteobjeto

nome e email de quem paga.

expira_emdata

Até quando o Pix pode ser pago.

pago_emdata ou null

Quando o pagamento foi confirmado.

criado_emdata

Quando a cobrança foi criada.

referenciatexto ou null

O código que você mandou.

Erros mais comuns

HTTPCódigoQuando
400json_invalidoCorpo não é JSON.
422dados_invalidosValor, CPF, e-mail ou nome inválido.
422valor_indisponivelEste valor não está disponível agora para a sua conta.
422recusado_antifraudeO antifraude recusou o Pix.
429limite_pendentes, muitas_requisicoes, banco_no_limiteLimites: espere e tente de novo.
503pix_indisponivelNenhum banco disponível: repita com a mesma Idempotency-Key.

Lista completa em Erros.

Exemplos de resposta de erro

{
  "erro": {
    "codigo": "dados_invalidos",
    "mensagem": "CPF inválido.",
    "campos": { "cpf": "CPF inválido." }
  }
}