Documentação da API

Autenticação

Envie o Client ID e a secret em toda requisição. As credenciais ficam em Painel → API, após o KYC aprovado.

Authorization: Basic base64(client_id:secret)
# ou
Authorization: Bearer client_id:secret

Criar cobrança PIX

nome_pagador é opcional na cobrança avulsa (o mesmo nome que o checkout do link grava nas entradas). No PIX recorrente, nome e CPF continuam obrigatórios.

POST /api/v1/charges
Content-Type: application/json

{
  "amount": 19.9,
  "description": "Pedido 1024",
  "nome_pagador": "Maria Silva"
}

# Resposta:
{
  "id": 123,
  "txid": "...",
  "status": "ATIVA",
  "copy_paste": "...",
  "amount": 19.9,
  "description": "Pedido 1024",
  "nome_pagador": "Maria Silva",
  "saldo_liquido": 19.3,
  "taxa_matriz": 3,
  "taxa_matriz_fixa": 0,
  "taxa_matriz_minima": 0,
  "retencao_matriz": 0.6,
  "saldo_liquido_matriz": 19.3
}

# saldo_liquido já vem com o desconto das taxas da conta.
# Em franquia também entram taxa_franquia*, retencao_franquia e saldo_liquido_franquia.

Criar PIX com vencimento (pix_boleto)

QR Code que permanece aberto até o vencimento e continua pagável depois, com multa (%) e juros (% ao mês). Não pode ser combinado com recurring.

POST /api/v1/charges
Content-Type: application/json

{
  "amount": 150.0,
  "description": "Fatura março",
  "pix_boleto": true,
  "data_vencimento": "15-04-2026",
  "multa": 2.0,
  "juros": 1.0,
  "pagador": {
    "nome": "Maria Silva",
    "cpf": "00000000000"
  }
}

# pix_boleto=true exige data_vencimento, multa, juros e pagador (nome + CPF)
# multa: percentual sobre o valor (ex.: 2.00 = 2%); 0 = sem multa
# juros: percentual ao mês, dias corridos (ex.: 1.00 = 1% a.m.); 0 = sem juros
# Após o vencimento o QR segue válido por 30 dias, com encargos
# Incompatível com recurring: true

Criar PIX recorrente

Gera a primeira cobrança e o QR composto do Pix Automático. O pagador paga agora e autoriza as próximas no app do banco. Exige nome e CPF.

POST /api/v1/charges
Content-Type: application/json

{
  "amount": 49.9,
  "description": "Assinatura mensal",
  "recurring": true,
  "periodicity": "MENSAL",
  "retry": true,
  "pagador": {
    "nome": "Maria Silva",
    "cpf": "00000000000"
  }
}

# periodicity: SEMANAL | MENSAL | TRIMESTRAL | SEMESTRAL | ANUAL
# retry (opcional): true = até 3 retentativas em 7 dias
# end_date (opcional): "2027-12-31"
# nome_pagador também pode ser enviado no topo; pagador.nome tem o mesmo efeito

Consultar saldo

Retorna saldo disponível para saque, bloqueios cautelares (infrações abertas ou deferidas) e saldo total. Inclui as chaves PIX cadastradas para uso no saque via API.

GET /api/v1/balance

# Resposta:
{
  "saldo_disponivel": 850.0,
  "bloqueio_cautelar": 150.0,
  "saldo_total": 1000.0,
  "chaves_pix": [
    {
      "id": 1,
      "tipo": "cnpj",
      "chave": "00000000000191",
      "rotulo": "Principal"
    }
  ]
}

Solicitar saque

Só é possível sacar até o saldo disponível (valores em bloqueio cautelar não entram). O PIX vai para uma chave cadastrada no perfil; use o id retornado em chaves_pix no GET de saldo.

POST /api/v1/withdrawals
Content-Type: application/json

{
  "valor": 500.0,
  "chave_pix_id": 1
}

# Resposta:
{
  "id": 42,
  "valor": 500.0,
  "status": "pendente",
  "chave_pix_id": 1,
  "automatico": false,
  "pix_tipo": "cnpj",
  "pix_chave": "00000000000191",
  "created_at": "2026-09-16T13:00:00Z"
}

# status: pendente (aguarda gerente) ou pago (saque automático)
# A chave PIX é consultada no DICT antes do saque. Se não existir, a API recusa.
# Também aceita amount e pix_key_id como aliases em inglês.

Consultar saques

Lista os saques da conta autenticada (mais recentes primeiro) ou consulta um saque pelo id.

GET /api/v1/withdrawals

# Resposta:
{
  "items": [
    {
      "id": 42,
      "valor": 500.0,
      "status": "pago",
      "pix_tipo": "cnpj",
      "pix_chave": "00000000000191",
      "created_at": "2026-09-16T13:00:00Z",
      "processado_at": "2026-09-16T13:05:00Z",
      "destinatario_nome": "Loja Centro",
      "destinatario_documento": "00000000000191",
      "destinatario_banco": "NU PAGAMENTOS",
      "destinatario_ispb": "18236120",
      "destinatario_agencia": "0001",
      "destinatario_conta": "123456",
      "end_to_end_id": "E123..."
    }
  ]
}

GET /api/v1/withdrawals/{id}

# Resposta:
{
  "id": 42,
  "valor": 500.0,
  "status": "pendente",
  "pix_tipo": "cnpj",
  "pix_chave": "00000000000191",
  "created_at": "2026-09-16T13:00:00Z"
}

# status: pendente | pago | recusado | falhou
# Quando pago, a resposta inclui a conta de destino e o end_to_end_id.

GET /api/v1/withdrawals/{id}/receipt
# Página do comprovante CashPay. Só quando status = pago.
# 409 se o saque ainda não foi pago ou não tem comprovante.

Consultar cobrança

GET /api/v1/charges/{id}
# ou GET /api/v1/charges/{txid}

# Resposta:
{
  "id": 123,
  "txid": "...",
  "status": "CONCLUIDA",
  "copy_paste": "...",
  "amount": 19.9,
  "description": "Pedido 1024",
  "nome_pagador": "Maria Silva",
  "saldo_liquido": 19.3,
  "taxa_matriz": 3,
  "taxa_matriz_fixa": 0,
  "taxa_matriz_minima": 0,
  "retencao_matriz": 0.6,
  "saldo_liquido_matriz": 19.3
}

Webhooks

A CashPay envia um POST para cada URL cadastrada em Painel → API quando cobranças PIX, saques ou bloqueios cautelares (infrações) são atualizados. Identifique o tipo pelo campo event.

POST {cada_webhook_cadastrado}
Content-Type: application/json

# --- PIX (entrada) ---
{
  "event": "pix.updated",
  "id": 123,
  "txid": "...",
  "status": "CONCLUIDA",
  "amount": 10,
  "saldo_liquido": 6.03,
  "taxa_matriz": 3,
  "taxa_matriz_fixa": 0,
  "taxa_matriz_minima": 0,
  "retencao_matriz": 0.3,
  "saldo_liquido_matriz": 3.67,
  "taxa_franquia": 10,
  "taxa_franquia_fixa": 2.97,
  "taxa_franquia_minima": 0,
  "retencao_franquia": 3.97,
  "saldo_liquido_franquia": 6.03,
  "description": "Pedido 1024",
  "nome_pagador": "Maria Silva"
}

# --- PIX com vencimento (pix_boleto), pago com atraso ---
{
  "event": "pix.updated",
  "id": 124,
  "txid": "...",
  "status": "CONCLUIDA",
  "amount": 100,
  "amount_pago": 105,
  "valor_multa": 3,
  "valor_juros": 2,
  "pix_boleto": true,
  "description": "Fatura março",
  "nome_pagador": "Maria Silva"
}
# amount = valor original da cobrança
# amount_pago = total recebido (original + multa + juros)
# valor_multa / valor_juros = valores em R$ efetivamente pagos

# Cobrança da matriz: só entram taxa_matriz, taxa_matriz_fixa,
# taxa_matriz_minima, retencao_matriz e saldo_liquido_matriz.
# saldo_liquido é o mesmo que saldo_liquido_matriz.
#
# Cobrança da franquia (exemplo: franquia 10% + R$ 2,97, matriz 3%):
# retencao_matriz = taxa da matriz sobre o amount (fica com a plataforma)
# saldo_liquido_matriz = o que a matriz recebe nesta venda
# retencao_franquia = retenção total da franquia
# saldo_liquido_franquia = o que a franquia recebe
# saldo_liquido = saldo_liquido_franquia
# A taxa é percentual + fixa, respeitando a mínima e limitada ao amount.

# Cada ciclo do PIX recorrente gera uma nova entrada e o mesmo POST
# quando a cobrança daquele período for paga.

# --- Saque ---
{
  "event": "withdrawal.updated",
  "id": 42,
  "valor": 500.0,
  "status": "pago",
  "pix_tipo": "cnpj",
  "pix_chave": "00000000000191"
}

# Disparado ao solicitar, pagar, recusar, cancelar ou falhar o saque.
# status: pendente | pago | recusado | falhou
# observacao traz o motivo da Nixfin em cancelamento/falha
# (ex.: conta recebedora bloqueada).

# --- Infração / bloqueio cautelar ---
{
  "event": "infraction.updated",
  "id": 7,
  "status": "OPEN",
  "motivo": "Contestação Pix",
  "transacao_id": 123,
  "valor": 19.9,
  "tipo": "FRAUD"
}

# Disparado ao abrir, atualizar, resolver ou defender a infração.
# status pode ser aberta, deferida, indeferida ou os status Nixfin
# (OPEN, ACKNOWLEDGED, DEFENDED, CLOSED, CANCELLED, ...).