Open Finance

O Open Finance (pagamento por iniciação, regulado pelo Banco Central) permite que o cliente pague debitando direto da conta do banco dele, sem precisar copiar um código PIX. Ao escolher o banco, ele é redirecionado para o ambiente do próprio banco, autoriza a transferência e retorna ao checkout — a confirmação chega de forma assíncrona.

É um método de débito instantâneo: não há cartão, não há QR Code para copiar e a liquidação ocorre de conta a conta.

Quando usar

Você quer uma taxa de conversão alta com débito direto, sem fricção de copiar/colar código.
O cliente prefere autorizar o pagamento dentro do app do banco dele.
Você já recebe via PIX e quer oferecer uma alternativa de iniciação de pagamento.

📘
Habilitação
O Open Finance precisa estar habilitado para o seu produto/loja e uma adquirente de iniciação configurada na sua conta. Fale com o suporte para ativar.

Fluxo de ponta a ponta

1. Cliente seleciona "Open Finance" e escolhe o banco
2. Sua aplicação cria um Payin com paymentMethod = OPEN_FINANCE
3. A Legacy retorna openFinanceRedirectUrl
4. Você redireciona o cliente para essa URL (nova aba)
5. O cliente autoriza a transferência no app/site do banco
6. O banco confirma → a Legacy recebe a confirmação e atualiza o status
7. Você é notificado por webhook (e/ou consulta o status do Payin)

A transação nasce com status PENDING e só passa para APPROVED após a autorização do cliente no banco. Confie sempre no webhook ou na consulta de status — nunca trate o redirecionamento como confirmação de pagamento.

Criando o pagamento

Envie um Payin com paymentMethod igual a OPEN_FINANCE. Opcionalmente, informe bankId para já direcionar o cliente ao banco escolhido na tela do checkout.

{
  "paymentMethod": "OPEN_FINANCE",
  "amount": 10000,
  "referenceId": "pedido-001",
  "isPhysicalProduct": false,
  "payerIp": "200.150.0.1",
  "bankId": "nubank",
  "webhookUrl": "https://sua-api.com/webhooks/legacy",
  "customer": {
    "name": "Maria Silva",
    "document": "12345678909",
    "email": "[email protected]",
    "phone": "5511999999999"
  },
  "items": [
    { "title": "Plano Premium", "quantity": 1, "unitPrice": 10000 }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`paymentMethod`	`string`	✅	Use `OPEN_FINANCE`
`bankId`	`string`	❌	Identificador do banco escolhido pelo cliente. Quando ausente, o cliente seleciona o banco no ambiente de autorização
`amount`	`integer`	✅	Valor total em centavos

📘
Lista de bancos
Os bancos disponíveis dependem do parceiro bancário configurado na sua conta. O checkout já recebe a lista correta automaticamente; em integrações próprias, consulte Listar Bancos (Open Finance) e use o id do banco como bankId.

Resposta

A resposta inclui o campo openFinanceRedirectUrl, para onde você deve enviar o cliente:

{
  "transactionId": "of_1A2B3C",
  "status": "PENDING",
  "openFinanceRedirectUrl": "https://autorizacao.banco.com.br/consent/abc123"
}

Confirmação por webhook

Após a autorização (ou recusa) no banco, a Legacy atualiza o status do Payin e dispara o webhook configurado em webhookUrl. Os estados terminais possíveis:

Status	Significado
`APPROVED`	Cliente autorizou e a transferência foi confirmada
`FAILED`	Pagamento recusado ou não autorizado
`REFUNDED`	Pagamento devolvido/estornado
`CANCELED`	Autorização cancelada

O payload do webhook segue o mesmo formato dos demais Payins — veja o guia de Webhooks. Você também pode consultar o status a qualquer momento em Obter Payin.

❗
Não confie no redirecionamento
O retorno do cliente ao checkout não garante que o pagamento foi concluído. Considere a venda aprovada apenas quando o status do Payin for APPROVED.

Boas práticas

Abra o link em nova aba e mantenha o checkout aberto aguardando a confirmação.
Aguarde o webhook (ou faça polling do status) antes de liberar o produto.
Trate o timeout: se o cliente não concluir a autorização, a transação permanece PENDING — ofereça reabrir o link ou trocar de método.