Criar cobrança Pix
/api/v1/chargesCria uma cobrança Pix avulsa, com valor livre. Permissão: Criar/consultar transações.
Cabeçalhos
AuthorizationtextoobrigatórioBearer + a sua chave privada. Veja Autenticação.
Content-Typetextoobrigatórioapplication/json
Idempotency-KeytextoOpcional. Um código seu (até 80 caracteres) para repetir o pedido sem criar outra cobrança. Veja Repetição segura.
Corpo
valorinteiroobrigatórioValor em centavos. Mínimo R$ 1,00 (100).
descricaotextoAté 200 caracteres. Aparece para o cliente. Vazio ou maior que isso vira "Cobrança".
referenciatextoUm código seu (ex.: número do pedido), até 100 caracteres. Volta igual na resposta e nos webhooks.
expira_em_segundosinteiroTempo para pagar. Padrão 900 (15 min), de 300 (5 min) a 900 (15 min), arredondado para minutos inteiros. Valor maior vira 900.
clienteobjetoobrigatórioQuem vai pagar.
cliente.nometextoobrigatórioNome completo (nome e sobrenome), de 3 a 150 caracteres.
cliente.emailtextoobrigatórioE-mail válido.
cliente.cpftextoobrigatórioCPF válido, com ou sem pontuação.
cliente.celulartextoDDD + 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"
}
}'<?php
$ch = curl_init('https://app.grinnypay.com/api/v1/charges');
curl_setopt_array($ch, [
CURLOPT_POST => 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' => '[email protected]', 'cpf' => '52998224725'],
]),
]);
$resposta = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 201 = criadaconst 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: '[email protected]', cpf: '52998224725' },
}),
});
const cobranca = await resp.json(); // resp.status === 201Resposta 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
idtextoIdentificador da cobrança (32 caracteres). Use em GET /charges/{id}.
statustextoVeja Status.
valorinteiroValor cobrado, em centavos.
taxainteiroTaxa da Grinny Pay, em centavos.
liquidointeiroO que entra no seu saldo (valor menos a taxa e a comissão de afiliado, se houver).
descricaotextoA descrição da cobrança.
pix_copia_e_colatexto ou nullCódigo Pix para o QR Code e o "copia e cola". Só vem com status pendente.
link_pagamentotextoPágina pronta de pagamento, com QR Code e contador.
clienteobjetonome e email de quem paga.
expira_emdataAté quando o Pix pode ser pago.
pago_emdata ou nullQuando o pagamento foi confirmado.
criado_emdataQuando a cobrança foi criada.
referenciatexto ou nullO 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
{
"erro": {
"codigo": "dados_invalidos",
"mensagem": "CPF inválido.",
"campos": { "cpf": "CPF inválido." }
}
}{
"erro": {
"codigo": "dados_invalidos",
"mensagem": "valor: número inteiro em centavos (ex.: 9700 = R$ 97,00).",
"campos": { "valor": "número inteiro em centavos" }
}
}{
"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."
}
}{
"erro": {
"codigo": "pix_indisponivel",
"mensagem": "Pix indisponível no momento. Tente de novo."
}
}