PIX manual

Contrato da API#Link direto para a seção Contrato da API

Use POST /api/v1/manual-pix com uma API key que tenha o escopo selecionável manual-pix. Esse escopo não é concedido automaticamente a chaves novas ou existentes.

pixKey aceita somente chaves DICT válidas: CPF, CNPJ, telefone, e-mail ou EVP. Chave CNPJ: 14 caracteres, numérica ou alfanumérica (modelo novo, como 12ABC34501DE35), com ou sem máscara; a API guarda sem máscara e em maiúsculas. receiverName tem máximo 25 e city tem máximo 15.

transactionId é alfanumérico, tem máximo 25 e, quando omitido, usa ***. amount é opcional, deve ser positivo, ter no máximo 2 casas decimais e ser menor ou igual a 9.999.999.999,99. No Sicoob, customerName tem máximo 200.

Escolha o modo de saída#Link direto para a seção Escolha o modo de saída

{
  "mode": "code_only",
  "pixKey": "financeiro@empresa.com.br",
  "receiverName": "Empresa Ltda",
  "city": "Sao Paulo"
}

{
  "mode": "code_only",
  "pix_code": "000201..."
}

{
  "mode": "qr_only",
  "pixKey": "financeiro@empresa.com.br",
  "receiverName": "Empresa Ltda",
  "city": "Sao Paulo"
}

{
  "mode": "qr_only",
  "qr_code_data_url": "data:image/png;base64,..."
}

{
  "mode": "both",
  "pixKey": "financeiro@empresa.com.br",
  "receiverName": "Empresa Ltda",
  "city": "Sao Paulo",
  "amount": 149.9
}

{
  "mode": "both",
  "pix_code": "000201...",
  "qr_code_data_url": "data:image/png;base64,..."
}

{
  "mode": "link",
  "pixKey": "financeiro@empresa.com.br",
  "receiverName": "Empresa Ltda",
  "city": "Sao Paulo",
  "domain": "canonical"
}

{
  "mode": "link",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "pay_url": "https://meu.casepay.com.br/pay/550e8400-e29b-41d4-a716-446655440000",
  "canonical_pay_url": "https://meu.casepay.com.br/pay/550e8400-e29b-41d4-a716-446655440000",
  "receipt_received": false
}

Somente o modo link exige Idempotency-Key; os demais modos são stateless. link retorna 201; os demais modos retornam 200. O campo domain só existe em link e aceita canonical, casepay_subdomain ou custom. O padrão é canonical; a API não aceita hostname arbitrário.

O PIX manual fica sem confirmação bancária: não há status pago nem conciliação. Um comprovante não confirma o pagamento. No link, o webhook manual_pix/receipt_received avisa quando o pagador envia um comprovante e manual_pix/receipt_removed, quando a equipe o remove; eles tratam do comprovante, não do pagamento.

Comprovante opcional

No link, envie o campo multipart receipt por POST /api/pay/[id]/receipt. São aceitos PNG, JPEG ou PDF até 4 MiB. Sem Content-Length, a resposta é 411; tamanho acima do limite retorna 413; MIME ou magic bytes incompatíveis retornam 415.

A resposta pública contém somente receipt_received. O público não pode visualizar nem baixar. A equipe usa GET e DELETE autenticados em /api/workspaces/[wsId]/manual-pix/[id]/receipt.