Central de ajuda
Documentação

Como funciona a API de Transferência (Saques) da CN Pay

Atualizado em 31 de julho de 2026

Perfil: Produtor
​Área: Documentação API

O que é a API de Transferência

A API de Transferência permite que sistemas externos realizem saques programáticos, enviando valores disponíveis em saldo para uma conta PIX informada, respeitando todas as regras de segurança, validação de titularidade e antifraude definidas pela CN Pay e pelo próprio gateway.

Essa API é indicada para cenários como:

  • Plataformas que automatizam repasses financeiros

  • Sistemas que precisam realizar payouts em larga escala

  • Marketplaces e soluções financeiras

  • Fluxos financeiros sem dependência do painel administrativo

Endpoint de criação de transferência

A criação de uma transferência é feita por meio de um endpoint autenticado:

  • Método: POST

  • URL:

    https://app.seugateway.com/api/v1/gateway/transfers

  • Autenticação obrigatória via chaves de API

Autenticação da API

Todas as requisições exigem autenticação por headers:

  • x-public-key: chave pública da conta

  • x-secret-key: chave secreta da conta

Essas chaves identificam exatamente qual gateway e qual conta está solicitando o saque.

Segurança adicional: IPs autorizados para saque

Além das chaves de API, a rota de saques possui uma camada extra de segurança baseada em IP.

Como funciona:

  • No painel do produtor, é necessário cadastrar os IPs autorizados

  • Esses IPs representam os servidores que podem chamar a API de saques

  • A requisição só é aceita se:

    • Vier de um IP autorizado e

    • Estiver autenticada com as chaves corretas

Regra importante:

  • É obrigatório cadastrar ao menos um IP autorizado

  • O IP precisa ser v4, IPv6 não é aceito

  • Caso nenhum IP esteja cadastrado:

    • Nenhuma transferência poderá ser realizada

    • A API retornará erro de autorização

Essa medida reduz drasticamente riscos de uso indevido das credenciais.

Dados obrigatórios da transferência

Para criar uma transferência, o body da requisição deve conter informações completas sobre:

  • Identificação da operação (identifier)

  • Valor do saque (amount)

  • Dados do recebedor PIX

  • Dados do proprietário da conta (owner)

  • URL de callback para notificações

Regras importantes sobre a chave PIX e o owner

A API de Transferência possui validações rígidas de titularidade, especialmente quando a chave PIX é baseada em documento.

Regra de titularidade (crítica):

Se a chave PIX for do tipo:

  • CPF

  • CNPJ

Então:

  • O documento informado em owner.document deve ser do mesmo titular

  • Não é permitido:

    • Chave PIX CPF diferente do CPF do owner

    • Chave PIX CNPJ diferente do CNPJ do owner

Exemplos inválidos:

  • owner CPF 123 → chave PIX CPF 456

  • owner CPF → chave PIX CNPJ

  • owner CNPJ A → chave PIX CNPJ B

Essas combinações são bloqueadas automaticamente pela API.

Por quê isso existe?

Essa regra garante:

  • Conformidade regulatória

  • Redução de fraudes

  • Prevenção de repasses indevidos para terceiros

Dados do owner (proprietário da conta)

O objeto owner representa o titular da conta que está recebendo a transferência e deve conter:

  • IP do usuário final que originou a ação

    • Deve ser diferente do IP da aplicação

  • Nome completo:

    • Apenas letras

    • Sem acentos

    • Máximo de 100 caracteres

  • Documento (CPF ou CNPJ)

Esses dados são usados para validação, auditoria e compliance.

Status da transferência

Após a criação da transferência, ela pode assumir diferentes status:

  • PENDING

  • PROCESSING

  • TRANSFERRING

  • COMPLETED

  • CANCELED

Atualizações de status são enviadas para a callbackUrl informada no momento da criação.

Webhooks e acompanhamento

Ao criar uma transferência, a API retorna:

  • Um webhookToken

  • Os dados completos da retirada

Esse token deve ser usado para validar notificações recebidas no webhook, garantindo que os eventos são legítimos.

Tratamento de erros

Em caso de falha, a API pode retornar:

  • Status CANCELED

  • Campo rejectedReason preenchido com:

    • Mensagem de erro

    • Ou mensagem informativa sobre o motivo do bloqueio

Exemplos comuns:

  • Chave PIX inválida

  • IP não autorizado

  • Divergência entre documento do owner e chave PIX

  • Saldo insuficiente

Boas práticas de implementação

  • Sempre cadastre IPs fixos e confiáveis

  • Nunca utilize IPs dinâmicos ou locais

  • Não exponha chaves reais em logs ou ferramentas de IA

  • Valide respostas e status via webhook

  • Teste exaustivamente antes de produção

Resumo final

A API de Transferência da CN Pay é um módulo avançado que oferece:

  • Saques via PIX totalmente automatizados

  • Segurança reforçada com IP autorizado + chaves

  • Validação rigorosa de titularidade

  • Webhooks para acompanhamento em tempo real

  • Operação white label integrada ao seu gateway

Quando corretamente configurada, ela permite que plataformas realizem transferências de forma segura, escalável e em conformidade com as regras financeiras.

Importante:

Nem todas as plataformas possuem esse módulo ativo. É necessário adquirir esse módulo a parte. Caso tenha interesse favor entrar em contato com o setor comercial.