Gerenciador de pagamentos Pix¶

Versão br.dev.bcp.pix 2026-07-14 usa esquema schemas/handlers/pix/pix.json.

Visão geral¶

Esse manipulador modela cobranças dinâmicas únicas do Pix. O PSP do beneficiário cria um valor fixo quantidade de cobrança dinâmica; o pagador envia o pagamento de qualquer financeira habilitada para Pix instituição digitalizando ou copiando o payload do Código BR.

Pix inverte o fluxo habitual dos manipuladores de cartões. Com os cartões, uma plataforma muitas vezes adquire um credencial e a envia para a empresa. No Pix, a cobrança é criada pelo lado comercial por meio de seu PSP e retornado na resposta de checkout para exibição. A confirmação da liquidação chega à empresa por meio do webhook do PSP.

Este manipulador está limitado a cobranças únicas. Pagamento recorrente Pix ou Open Finance a iniciação requer um manipulador separado.

Participantes¶

Participante	Função
Pagador	Paga no aplicativo do banco digitalizando ou copiando a carga do Pix.
Plataforma	Descobre o manipulador, seleciona Pix e exibe a cobrança.
Negócios	Cria a cobrança através do seu PSP, recebe notificações de liquidação e reconcilia.
Beneficiário PSP	Emite a cobrança dinâmica e notifica a empresa após a liquidação.

Pré-requisitos¶

Comercial: contrata um PSP beneficiário e armazena credenciais de API do provedor em seu back-end. As credenciais PSP nunca viajam em cargas úteis de descoberta ou resposta.
Plataforma: não é necessária integração com PSP. A plataforma só precisa suportar exibindo a cobrança do Pix devolvida.

Declaração do manipulador¶

Declaração de descoberta de negócios:json { "payment_handlers": { "br.dev.bcp.pix": [ { "id": "pix_recebedor_001", "version": "2026-07-14", "available_instruments": [{ "type": "pix" }], "config": { "environment": "production" } } ] } }Declaração da plataforma:json { "id": "pix_platform_001", "version": "2026-07-14", "spec": "https://bcp.dev.br/2026-07-14/specification/pix-payment-handler", "schema": "https://bcp.dev.br/2026-07-14/schemas/handlers/pix/pix.json", "available_instruments": [{ "type": "pix" }], "config": { "environment": "production", "platform_id": "plat_abc" } }As declarações de resposta carregam a configuração do tempo de execução. A carga real viaja como um pix_payment_instrument em payment.instruments.

Aquisição de instrumentos¶

A plataforma seleciona Pix durante a finalização da compra.
A empresa liga para seu PSP para criar uma cobrança dinâmica para o total do checkout.
O PSP retorna provider_payment_id, copia_e_cola e expires_at.
A empresa devolve um instrumento de pagamento Pix com tipo de credencial pix_charge.
A plataforma exibe o payload QR ou copiar e colar até expires_at.

A carga útil copia_e_cola é uma carga útil do Código BR (EMV) que já codifica o beneficiário e quantidade. A reconciliação usa provider_payment_id.

Processamento¶

O pagador preenche o Pix no aplicativo do banco.
A rede Pix liquida ao PSP beneficiário.
O PSP notifica a empresa por webhook.
A empresa verifica a vinculação e o valor antes de aceitar a liquidação.
A ordem avança após a confirmação da liquidação.

Mapeamento de erros¶

Situação	`error_code` sugerido
A cobrança expirou sem pagamento	`payment_expired`
Descasamento do montante liquidado ou falha genérica	`payment_failed`
Beneficiário PSP indisponível	`processor_unavailable`

O estado de reembolso é representado pela capacidade de devolução, não por este manipulador.

Segurança¶

A credencial pode incluir binding para associar a cobrança do Pix ao check-out e identidade do beneficiário.
As credenciais da API PSP permanecem no back-end da empresa e nunca entram na descoberta, esquema ou cargas úteis de resposta.
As plataformas NÃO DEVEM apresentar cobrança após expires_at.