A Cifra como a sua adquirente Pix.

1. 01Você cria a conta na Cifra e faz a verificação de identidade da empresa, como qualquer conta.
2. 02A Cifra habilita a conta como gateway parceiro e define as suas condições: taxas, limites, reserva de segurança e travas. Você vê tudo em Painel › Parceiro.
3. 03Você cria as cobranças Pix dos seus clientes pela API. Cada venda paga entra no seu saldo já sem a taxa, e uma parte pode ficar na reserva de segurança até o prazo.
4. 04Você saca o saldo pela API, para a chave cadastrada no painel ou, se a sua conta permitir, para a chave que informar em cada saque.

A chave vai no cabeçalho x-cifra-api-key. Crie em Painel › API, depois de a conta virar parceira, com os escopos:

• payments:write

  criar cobranças Pix

• payments:read

  consultar cobranças

• payouts:read

  consultar saldo e saques

• payouts:write

  pedir saques

• webhooks:manage

  cadastrar o webhook (vendas e saques)

Se a conta tiver lista de IPs, as chamadas só funcionam a partir desses endereços.

• GET/api/v1/saldopayouts:read

  Saldo disponível, valor na reserva de segurança, valor em saque e as próximas liberações.

{
  "disponivelCentavos": 1284390,
  "retidoCentavos": 142050,
  "emSaqueCentavos": 50000,
  "bloqueado": false,
  "proximasLiberacoes": [
    {
      "liberaEm": "2026-11-10T00:00:00.000Z",
      "valorCentavos": 38200
    },
    {
      "liberaEm": "2026-11-13T00:00:00.000Z",
      "valorCentavos": 61850
    }
  ],
  "carteiras": [
    {
      "subcontaId": "3f2a9c1e-5b7d-4e8f-a1b2-c3d4e5f6a7b8",
      "nome": "Velani",
      "disponivelCentavos": 1284390,
      "retidoCentavos": 142050,
      "emSaqueCentavos": 50000
    }
  ]
}

retidoCentavos é a reserva de segurança: não pode ser sacado e volta sozinho ao disponível nas datas de proximasLiberacoes.

Em carteiras vem o saldo de cada adquirente. Se houver mais de uma, mande o subcontaId no saque para dizer de qual sai. Com uma só, não precisa.

• POST/api/v1/saquespayouts:write

  Pede um saque. Exige o cabeçalho idempotency-key.

• GET/api/v1/saquespayouts:read

  Os 50 saques mais recentes.

• GET/api/v1/saques/{id}payouts:read

  Um saque, com o estado atual.

curl -X POST https://api.cifra-pay.com/api/v1/saques \
  -H "x-cifra-api-key: $CIFRA_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"valorCentavos":500000}'

{
  "valorCentavos": 500000
}

{
  "valorCentavos": 250000,
  "destino": {
    "chavePix": "recebedor@example.com",
    "tipoChavePix": "email",
    "titular": {
      "nome": "Loja Exemplo Ltda",
      "documento": "11222333000181"
    }
  }
}

{
  "id": "7c1e2d3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "valorCentavos": 500000,
  "taxaCentavos": 300,
  "estado": "PENDENTE",
  "aguardandoAprovacao": false,
  "criadoEm": "2026-11-08T14:00:00.000Z"
}

RESERVADA

Valor reservado. Com aguardandoAprovacao: true, espera a aprovação da Cifra.

ENVIANDO / PENDENTE

Enviado à adquirente, esperando o banco.

INCERTA

Sem resposta definitiva ainda; a Cifra confirma sozinha.

CONCLUIDA

Dinheiro na chave de destino. Chega o webhook saque.concluido.

RECUSADA

Não saiu. Valor e taxa voltam ao saldo. Chega o webhook saque.recusado.

• •Valores sempre em centavos, inteiros.
• •A taxa do saque sai do saldo além do valor pedido: o saque de R$ 100,00 com taxa de R$ 3,00 tira R$ 103,00 do saldo.
• •O valor na reserva de segurança não pode ser sacado; ele volta sozinho ao disponível na data de liberação.
• •Repetir o mesmo saque com a mesma idempotency-key devolve o mesmo saque, nunca dois. Use um UUID novo por pedido.
• •Chave de destino trocada no painel só recebe saque depois da carência da conta.

Cadastre com POST /api/v1/webhooks incluindo saque.concluido e saque.recusado (a chave precisa de escopo de saque). A assinatura é a mesma das vendas: Cifra-Webhook-Signature, com janela de 300 s. Detalhes em Webhooks.

{
  "id": "2b3c4d5e-6f70-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "saque.concluido",
  "apiVersion": "2026-09-20",
  "createdAt": "2026-11-08T14:02:10.000Z",
  "organizationId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "data": {
    "id": "7c1e2d3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "valorCentavos": 500000,
    "ocorridoEm": "2026-11-08T14:02:09.000Z"
  }
}

• 403conta_nao_parceiraa conta não é de gateway parceiro
• 403chave_anterior_ao_parceiroa chave foi criada antes de a conta virar parceira; crie outra
• 403ip_nao_autorizadoa chamada veio de um IP fora da lista da conta
• 409destino_nao_cadastradofalta cadastrar a chave Pix de destino no painel
• 409destino_em_carenciaa chave de destino foi trocada há pouco e ainda não recebe saque
• 422destino_nao_permitidoa conta saca só para a chave cadastrada; envie apenas o valor
• 422destino_obrigatorioa conta exige destino e titular em cada saque
• 422titular_invalidoCPF ou CNPJ do titular inválido
• 400subconta_obrigatoriaa conta tem saldo em mais de uma adquirente; envie o subcontaId
• 422saque_acima_do_limiteo valor passa do saque máximo da conta
• 422saque_acima_do_limite_diarioo valor passa do limite de saque em 24 horas
• 429saque_em_intervaloainda não passou o intervalo mínimo entre saques
• 403saldo_indisponivelsaldo insuficiente (valor + taxa) ou saldo bloqueado para conferência
• 409idempotency_conflicta mesma idempotency-key com outro pedido