API de Pagamentos — Intenção de Pagamento (Payment Intent)

Visão geral

A intenção de pagamento (payment intent) é o registro que você cria antes de mover dinheiro: ela guarda o que será pago, passa por aprovação e autorização e só então é enviada para liquidação.

Tipo	Quando usar
PIX	Pagamento instantâneo, por chave, por QR Code ou com dados bancários informados manualmente
TED	Transferência para conta em outro banco, com dados bancários completos
TEF	Transferência entre contas da mesma instituição

Todos os valores são inteiros em centavos: R$ 150,75 é enviado como 15075. A taxa é calculada na criação, de acordo com o plano da conta, e devolvida em feeAmount. O campo totalAmount é sempre amount + feeAmount.

O fluxo, do início ao fim:

Fluxo de pagamento

O fluxo de pagamentos PIX ocorre de acordo com os passos abaixo:

Iniciação ou Intenção de pagamento PIX

A iniciação do PIX é responsável por validar os dados da transação e gerar uma solicitação de pagamento. O destinatário pode ser identificado por meio de chave PIX, QR Code ou dados bancários. Após a validação, a transação será criada com status inicial de pendente (pending) de confirmação.

Confirmação do PIX

A confirmação do PIX autoriza a liquidação financeira da transação. Após a confirmação, o valor será debitado da conta de origem e enviado para processamento pela instituição financeira responsável. O status da transação será atualizado até sua conclusão, recusa ou eventual devolução.
Essa etapa pode ser assíncrona e a confirmação será recebida via webhook.

Recebimento do resultado via Webhook

Receber o resultado por webhook, ou consultar a intenção a qualquer momento.

Webhooks

A BrasilCash avisa o seu sistema por HTTP POST quando uma operação muda de estado, e o customerRef informado na criação volta no evento para você identificar o pedido.

Para cadastrar um webhook, chame POST /api-keys/{apiKeyId}/webhooks com a url e a lista eventTypes. A resposta traz o secret (formato whsec_...) uma única vez. Guarde-o: ele é a base da validação descrita abaixo.

Evento	Significado
`pix.out`	PIX enviado pela sua conta
`ted.out`	TED enviada pela sua conta
`tef.out`	TEF enviada pela sua conta
`pix.in`	PIX recebido na sua conta
`ted.in`	TED recebida na sua conta
`tef.in`	TEF recebida na sua conta

Validar a origem

Cada envio inclui o header X-Signature, com o hash SHA-256, em hexadecimal minúsculo, do secret do webhook. Para validar, calcule o SHA-256 do secret que você guardou e compare com o header em tempo constante, nunca com ==.

Se a validação falhar, responda 401 e não processe o evento. Responda 2xx o mais rápido possível quando o evento for válido e faça o processamento pesado depois.

A assinatura é a mesma em todos os envios do mesmo webhook, porque não depende do corpo da mensagem. Ela confirma que o evento veio da BrasilCash, mas não detecta alteração do conteúdo no caminho, por isso use sempre uma URL HTTPS. Se o secret vazar ou for perdido, gere um novo em POST /api-keys/{apiKeyId}/webhooks/{id}/regenerate-secret; o anterior deixa de valer.

Erros e boas práticas

A maioria dos erros vem de dados inválidos ou de uma ação fora do momento certo do ciclo de vida, e a API responde com um status HTTP e uma mensagem.

Status	Quando acontece
`400 Bad Request`	Dado inválido ou regra violada: valor zero, senha transacional inválida ou expirada, intenção expirada, ação que o status atual não permite
`401 Unauthorized`	Credenciais inválidas, token ausente ou expirado
`403 Forbidden`	Chave autenticada, mas sem permissão para a operação
`404 Not Found`	Intenção inexistente

Boas práticas

Envie idempotencyKey em toda criação e reutilize a mesma chave ao repetir uma chamada que deu timeout. Sem ela, uma nova tentativa pode gerar um pagamento duplicado.

Use customerRef para ligar a intenção ao pedido do seu sistema. Ele volta nos webhooks e no comprovante.

Trate cada webhook como se pudesse chegar mais de uma vez, e confirme o estado com GET /payments/{id} se um evento não chegar.

Crie uma intenção nova quando a anterior expirar: ela fica expired após 24 horas sem aprovação ou 5 minutos sem autorização.

Guarde clientSecret, password e o secret do webhook em um cofre de segredos, nunca no código-fonte.

Status da Intenção de Pagamento

As transações PIX podem assumir os seguintes status durante seu ciclo de vida:

Status	Descrição
Authorized	PIX iniciado e aguardando confirmação do pagamento.
Processing	PIX enviado para processamento junto à instituição financeira.
Completed	Pagamento PIX realizado com sucesso.
Failed	Pagamento PIX recusado pela instituição financeira.
Refunded	Valor do PIX devolvido ao pagador.

API de Pagamentos — Intenção de Pagamento (Payment Intent)

Visão geral#

Fluxo de pagamento#

Webhooks#

Validar a origem#

Erros e boas práticas#

Boas práticas#

Status da Intenção de Pagamento#

Fluxo de status#