Migração da API de Pagamentos V4 para V5

Guia de referência para times que consomem a API de Pagamentos (Open Finance Brasil) integrada via JCR (Jornada Com Redirecionamento - fluxo HYBRID_FLOW) ou JSR (Jornada Sem Redirecionamento - fluxo FIDO_FLOW) e que precisam migrar suas integrações da v4 para a v5.

Sumário

Visão geral
Período de coexistência e regras de compatibilidade
O que muda em todos os endpoints
Mapa de endpoints: v4 → v5
Migração - Fluxo JCR (Jornada Com Redirecionamento)
Migração - Fluxo JSR (Jornada Sem Redirecionamento)
Novos objetos e parâmetros
Mudanças de padrão (regex) em campos existentes
Consulta de recursos criados na v4 através da v5
Novos códigos de rejeição e erro
Checklist de migração
Referências

Visão geral

A versão 5.0.0 da API de Pagamentos do Open Finance Brasil introduz suporte a Pix Saque, Pix Troco e ao instrumento de pagamento por NFC, além de formalizar o fluxo de rejeição de pagamentos. Isso exige um novo campo de finalidade (purpose) em toda iniciação de pagamento Pix, a expansão do enum localInstrument, e o suporte a QR Codes dinâmicos autenticados (payloadJWS).

Na Celcoin, essas mudanças afetam da mesma forma os dois modelos de integração:

Sigla	Nome	Fluxo de autorização	Endpoints (prefixo)
JCR	Jornada Com Redirecionamento	`HYBRID_FLOW` (redirecionamento do usuário para autorização)	`/open-keys/itp/api/v2/payments/v{versão}/...`
JSR	Jornada Sem Redirecionamento	`FIDO_FLOW` (autorização via enrollment FIDO, sem redirect)	`/open-keys/itp/api/v2/payments/v{versão}/...`

Em ambos os modelos, a migração v4 → v5 é, na essência, aditiva: os endpoints, métodos HTTP e headers de autenticação permanecem os mesmos - muda o número de versão no path e são adicionados novos campos e valores de enum. Não há remoção de funcionalidade, exceto a reorganização de schedule.custom.additionalInformation, que passa a viver na raiz de schedule (ver Novos objetos e parâmetros).

Período de coexistência e regras de compatibilidade

Conforme a página de estrutura do Open Finance Brasil "Adaptações para Consultas de Recursos na API Pagamentos entre Versões 4.0.1 e 5.0.0":

Coexistência temporária: as versões v4 e v5 ficam disponíveis simultaneamente por um período de transição. Instituições Transmissoras de Pagamento (ITPs) devem migrar integralmente para a v5 antes do desligamento (sunset) da v4.
Vínculo consentimento ↔ pagamento: um consentimento criado em uma versão não pode iniciar pagamento em outra versão. A tentativa retorna HTTP 422 com code: PAGAMENTO_DIVERGENTE_CONSENTIMENTO e detail: "Divergência entre versões de consentimento e pagamento".
Consentimento é de uso único: após a autorização/criação do pagamento, o consentimento passa a CONSUMED, permanecendo disponível apenas para consulta (somente leitura).
Direção da consulta importa:
- Recursos criados na v4.0.1 continuam consultáveis pelos endpoints v5.0.0 (GET /consents/{consentId} e GET /pix/payments/{paymentId}) durante e após a coexistência.
- Recursos criados na v5.0.0 não podem ser consultados pelos endpoints v4.0.1 - a tentativa retorna HTTP 400.
- Pagamentos agendados criados em versões anteriores podem ser cancelados via PATCH /pix/payments/{paymentId} da v5.0.0 durante toda a coexistência.

Recomendação prática: ao planejar o corte, garanta que toda nova iniciação de pagamento e criação de jornada passe a usar os endpoints v5, mas mantenha a capacidade de consultar (GET) pagamentos e jornadas antigas normalmente - o histórico não precisa ser migrado, apenas consultado pela rota nova.

O que muda em todos os endpoints

Item	v4	v5
Path	`.../payments/v4/...`	`.../payments/v5/...`
Método HTTP	inalterado	inalterado
Headers de autenticação	`Authorization: Bearer {access_token}`, `Content-Type: application/json`	inalterados
Escopos OAuth2	`app` e/ou `journey` (conforme endpoint)	inalterados
`paymentInitiationApi` (campo de resposta)	`"PAYMENTS_V4"`	`"PAYMENTS_V5"`
`payment.purpose`	não existe	novo - obrigatório para pagamentos Pix
`payment.details.payloadJWS`	não existe	novo - obrigatório quando `localInstrument` é `APDN` ou `QRDN`
`payment.details.localInstrument` (enum)	`MANU`, `DICT`, `QRDN`, `QRES`, `INIC`	`APDN`, `APES`
`transactionIdentification` (endpoint de criação de pagamento Pix)	não existe	novo - opcional, obrigatório para `INIC` ou QR Codes com TxId
`schedule.custom.additionalInformation`	dentro de `schedule.custom`	movido para `schedule.additionalInformation` (raiz), obrigatório para todos os tipos de agendamento

Nenhum endpoint muda de método HTTP (POST continua POST, GET continua GET) e nenhuma rota é removida ou renomeada - a migração é feita trocando o segmento de versão no path e adaptando o corpo das requisições/respostas.

Mapa de endpoints: v4 → v5

JCR - Jornada Com Redirecionamento

Operação	v4	v5
Criar iniciação de pagamento	`POST /open-keys/itp/api/v2/payments/v4/payment-initiation`	`POST /open-keys/itp/api/v2/payments/v5/payment-initiation`
Criar pagamento Pix	`POST /open-keys/itp/api/v2/payments/v4/payment-initiation/{paymentInitiationId}/pix`	`POST /open-keys/itp/api/v2/payments/v5/payment-initiation/{paymentInitiationId}/pix`
Criar jornada de pagamento	`POST /open-keys/itp/api/v2/payments/v4/journeys-sessions`	`POST /open-keys/itp/api/v2/payments/v5/journeys-sessions`
Listar jornadas de pagamento	`GET /open-keys/itp/api/v2/payments/v4/journeys-sessions`	`GET /open-keys/itp/api/v2/payments/v5/journeys-sessions`
Buscar jornada de pagamento	`GET /open-keys/itp/api/v2/payments/v4/journeys-sessions/{id}`	`GET /open-keys/itp/api/v2/payments/v5/journeys-sessions/{id}`

JSR - Jornada Sem Redirecionamento

Operação	v4	v5
Criar iniciação de pagamento	`POST /open-keys/itp/api/v2/payments/v4/payment-initiation`	`POST /open-keys/itp/api/v2/payments/v5/payment-initiation`
Criar pagamento Pix	`POST /open-keys/itp/api/v2/payments/v4/payment-initiation/{paymentInitiationId}/pix`	`POST /open-keys/itp/api/v2/payments/v5/payment-initiation/{paymentInitiationId}/pix`
Criar jornada de pagamento	`POST /open-keys/itp/api/v2/payments/v4/journeys-sessions`	`POST /open-keys/itp/api/v2/payments/v5/journeys-sessions`
Listar jornadas de pagamento	`GET /open-keys/itp/api/v2/payments/v4/journeys-sessions`	`GET /open-keys/itp/api/v2/payments/v5/journeys-sessions`
Buscar jornada de pagamento	`GET /open-keys/itp/api/v2/payments/v4/journeys-sessions/{id}`	`GET /open-keys/itp/api/v2/payments/v5/journeys-sessions/{id}`

Os paths de JCR e JSR são idênticos; a diferença entre os dois fluxos está no corpo da requisição (JSR exige o objeto enrollment de FIDO) e no valor de authorisationFlow retornado/enviado (HYBRID_FLOW para JCR, FIDO_FLOW para JSR).

Migração - Fluxo JCR (Jornada Com Redirecionamento)

1. Criar iniciação de pagamento

POST /open-keys/itp/api/v2/payments/v{versão}/payment-initiation

Headers: Authorization: Bearer {access_token} · Content-Type: application/json · escopo journey ou app (sem alteração).

Campo	v4	v5
`brandId`, `redirectUrl`, `directoryCallback`	inalterados	inalterados
`data.loggedUser`, `data.creditor`, `data.remittanceInformation`	inalterados	inalterados
`data.payment.type`, `.date`, `.currency`, `.amount`	obrigatórios	obrigatórios (mantidos)
`data.payment.purpose`	-	novo, condicional (obrigatório quando `type` é `"PIX"`) - enum `IMMEDIATE`, `SINGLE_SCHEDULED`, `RECURRENT_SCHEDULED`, `WITHDRAW`, `CHANGE`
`data.payment.schedule`	suportava `single`/`daily`/`weekly`/`monthly`/`custom`	mesma estrutura, mas `additionalInformation` agora fica na raiz de `schedule` e é obrigatório para todos os tipos
`data.payment.details.localInstrument`	`DICT`, `MANU`, `QRDN`, `QRES`, `INIC`	`APDN`, `APES`
`data.payment.details.payloadJWS`	-	novo, obrigatório quando `localInstrument` é `APDN` ou `QRDN`
`data.payment.details.proxy`, `.creditorAccount`	inalterados	inalterados

Referências: v4 · v5

2. Criar pagamento Pix

POST /open-keys/itp/api/v2/payments/v{versão}/payment-initiation/{paymentInitiationId}/pix

Campo	v4	v5
`data[].localInstrument`	`DICT`, `MANU`, `QRDN`, `QRES`, `INIC` (exemplos documentados: `DICT`, `INIC`)	`APDN`, `APES`
`data[].payment.amount`, `.currency`	inalterados	inalterados
`data[].creditorAccount`	inalterado	inalterado
`data[].cnpjInitiator`	formato `^\d{14}$`	atenção: no recurso de consulta o padrão evolui para `^[0-9A-Z]{12}[0-9]{2}$` (ver mudanças de padrão)
`data[].proxy`	condicional (DICT/INIC)	inalterado
`data[].endToEndId`	obrigatório, padrão `E` + 8 dígitos numéricos + ...	mesmo formato de entrada; padrão de leitura evolui para aceitar ISPB alfanumérico (ver abaixo)
`data[].authorisationFlow`	`"HYBRID_FLOW"`	`"HYBRID_FLOW"` (inalterado)
`data[].transactionIdentification`	-	novo, opcional; obrigatório para `INIC` ou QR Codes com TxId

Resposta (200 OK): mesma estrutura (id, paymentInitiationApi, ofPayments[], ofConsent, updatedAt), com paymentInitiationApi passando a "PAYMENTS_V5".

Referências: v4 · v5

3. Criar jornada de pagamento

POST /open-keys/itp/api/v2/payments/v{versão}/journeys-sessions

Campo	v4	v5
`journeyId`, `redirectUrl`, `settings`, `tags`	inalterados	inalterados (v5 documenta `settings`/`JOURNEY_RULES` com granularidade por campo, mas a estrutura já existia)
`paymentInitiationData.payment.purpose`	-	novo (segue a mesma regra do endpoint de iniciação)
Resposta `paymentInitiationApi`	`"PAYMENTS_V4"`	`"PAYMENTS_V5"`

Referências: v4 · v5

4. Listar jornadas de pagamento

GET /open-keys/itp/api/v2/payments/v{versão}/journeys-sessions

Query params page e pageSize inalterados. Resposta (data[], meta) com mesma estrutura; paymentInitiationApi passa a "PAYMENTS_V5".

Referências: v4 · v5

5. Buscar jornada de pagamento

GET /open-keys/itp/api/v2/payments/v{versão}/journeys-sessions/{id}

Parâmetro de path id inalterado. Resposta com mesma estrutura (journeyId, applicationId, tokenId, journeySessionStageId, journeySessionUrl, status, application, journey, token); paymentInitiationApi passa a "PAYMENTS_V5".

Referências: v4 · v5

Migração - Fluxo JSR (Jornada Sem Redirecionamento)

O fluxo JSR segue o mesmo conjunto de mudanças do JCR (campos purpose, payloadJWS, transactionIdentification, expansão de localInstrument), com as seguintes particularidades específicas do modelo de autenticação FIDO:

1. Criar iniciação de pagamento

POST /open-keys/itp/api/v2/payments/v{versão}/payment-initiation

Campo	v4	v5
`enrollment.rp`, `.platform`, `.enrollmentId`	obrigatório (dados de vínculo FIDO)	obrigatório, sem alteração
`data.payment.purpose`	-	novo, condicional (PIX)
`data.payment.details.localInstrument`	`DICT`, `MANU`, `QRDN`, `QRES`, `INIC`	`APDN`, `APES`
`data.payment.details.payloadJWS`	-	novo, obrigatório para `APDN`/`QRDN`

Referências: v4 · v5

2. Criar pagamento Pix

POST /open-keys/itp/api/v2/payments/v{versão}/payment-initiation/{paymentInitiationId}/pix

Campo	v4	v5
`data[].authorisationFlow`	`"FIDO_FLOW"`	`"FIDO_FLOW"` (inalterado)
`data[].localInstrument`	`DICT`, `MANU`, `QRDN`, `QRES`, `INIC`	`APDN`, `APES`
`data[].transactionIdentification`	-	novo, opcional; obrigatório para `INIC`/QR com TxId

Referências: v4 · v5

3. Criar jornada de pagamento

POST /open-keys/itp/api/v2/payments/v{versão}/journeys-sessions

A documentação da v5 (JSR) reforça que o token OAuth2 deve conter o claim azp com o clientId do aplicativo - comportamento de autenticação já esperado, mas explicitado na versão nova. Demais campos seguem o mesmo padrão do JCR (purpose novo em paymentInitiationData.payment).

Referências: v4 · v5

4. Listar jornadas de pagamento

GET /open-keys/itp/api/v2/payments/v{versão}/journeys-sessions

Sem mudanças estruturais além de paymentInitiationApi: "PAYMENTS_V5".

Referências: v4 · v5

5. Buscar jornada de pagamento

GET /open-keys/itp/api/v2/payments/v{versão}/journeys-sessions/{id}

Sem mudanças estruturais além de paymentInitiationApi: "PAYMENTS_V5". A documentação identifica este fluxo como parte da "JSR - Jornada Sem Redirecionamento".

Referências: v4 · v5

Novos objetos e parâmetros

Campo	Onde aparece	Tipo	Obrigatoriedade	Descrição
`payment.purpose`	Criar iniciação de pagamento, Criar jornada de pagamento	enum `IMMEDIATE` \| `SINGLE_SCHEDULED` \| `RECURRENT_SCHEDULED` \| `WITHDRAW` \| `CHANGE`	Obrigatório para pagamentos do tipo `PIX`	Declara a finalidade do pagamento. `WITHDRAW` (Pix Saque) e `CHANGE` (Pix Troco) são finalidades novas, não suportadas na v4.
`payment.details.payloadJWS`	Criar iniciação de pagamento (corpo), consulta de consentimento (resposta)	string (padrão JWT `xxx.yyy.zzz`)	Obrigatório quando `localInstrument` é `APDN` ou `QRDN`	Payload assinado do QR Code dinâmico, usado para autenticação do recebedor.
`data[].transactionIdentification`	Criar pagamento Pix	string	Opcional; obrigatório para `INIC` ou QR Codes com TxId	Identificador de transação (txid) do Pix.
`payment.schedule.additionalInformation`	Criar iniciação de pagamento / jornada, quando há agendamento	string (máx. 255 caracteres)	Obrigatório para todos os tipos de agendamento (`single`, `daily`, `weekly`, `monthly`, `custom`)	Antes só existia dentro de `schedule.custom`; agora fica na raiz de `schedule` e vale para qualquer tipo de agendamento.
`localInstrument` - novos valores	Criar iniciação de pagamento, Criar pagamento Pix, consulta de consentimento/pagamento	enum	-	`APDN` (Pix Automático via QR Dinâmico, conforme contexto) e `APES` somam-se a `MANU`, `DICT`, `QRDN`, `QRES`, `INIC`.

Mudanças de padrão (regex) em campos existentes

Estas mudanças afetam principalmente a leitura de recursos (consultas de consentimento e pagamento), mas os times que validam esses campos no cliente devem atualizar suas expressões regulares para não rejeitar respostas válidas da v5:

Campo	Padrão v4.0.1	Padrão v5.0.0
`businessEntity.document.identification`	`^\d{14}$`	`^[0-9A-Z]{12}[0-9]{2}$`
`creditor.cpfCnpj`	`^\d{11}$\|^\d{14}$`	`^([0-9]{11})$\|^([0-9A-Z]{12}[0-9]{2})$`
`creditor.name`	`^([A-Za-zÀ-ÖØ-öø-ÿ,.@:&*+_<>()!?/\$%\d' -]+)$`	`^[ -~¡-ÿ]+$`
`debtorAccount.ispb` / `creditorAccount.ispb`	`^[0-9]{8}$`	`^[0-9A-Z]{8}$`
`cnpjInitiator`	`^\d{14}$`	`^[0-9A-Z]{12}[0-9]{2}$`
`endToEndId`	`E` + 8 dígitos numéricos + ...	`E` + 8 caracteres alfanuméricos + ...

Essas alterações refletem a evolução do formato de CNPJ (CNPJ alfanumérico) e do código ISPB no Open Finance Brasil, e não são exclusivas da API de Pagamentos - times que já ajustaram parsers para outras APIs (Consentimentos, Contas etc.) podem reaproveitar a mesma lógica.

Consulta de recursos criados na v4 através da v5

Ao consultar, pela v5, um consentimento ou pagamento criado originalmente na v4.0.1, os campos novos da v5 são preenchidos com valores derivados ou sentinela, já que a informação original não existia:

Campo consultado	Regra de preenchimento quando a origem é v4.0.1
`payment.purpose`	Derivado da estrutura v4.0.1: `data.payment.date` presente (sem `schedule`) → `IMMEDIATE`; `schedule.single` presente → `SINGLE_SCHEDULED`; `schedule.daily`/`weekly`/`monthly`/`custom` presente → `RECURRENT_SCHEDULED`. Os valores `WITHDRAW` e `CHANGE` nunca se aplicam a recursos v4.0.1, pois Pix Saque/Troco não existiam nessa versão.
`payment.details.payloadJWS`	Retorna o valor sentinela `inexistente.inexistente.inexistente` (respeita o padrão de JWT, mas não é um JWS decodificável) - a API não consegue reconstruir o payload original.
`payment.schedule.additionalInformation` (para agendamentos que não eram `custom`)	Retorna o texto sentinela `"Informação não disponível para consentimentos originados em versão anterior"`.
`localInstrument`	Retorna o valor original informado na criação do consentimento/pagamento (não há necessidade de conversão).
Campos de padrão alfanumérico (`document.identification`, `cpfCnpj`, `ispb`, `endToEndId`)	Retornam o valor original armazenado, que continua compatível com o novo padrão (mais permissivo).

Novos códigos de rejeição e erro

Contexto	Código	Descrição
Divergência de versão	`422` - `PAGAMENTO_DIVERGENTE_CONSENTIMENTO`	Retornado ao tentar iniciar pagamento com consentimento de outra versão da API.
`data.rejectionReason.code` (consulta de consentimento)	`AUTENTICACAO_DIVERGENTE`, `PERMISSAO_INSUFICIENTE`	Novos motivos de rejeição adicionados na v5.0.0.
`data.rejectionReason.code` (consulta de pagamento)	Inclui códigos antes ausentes: `CHAVE_PIX_DIVERGENTE_AGENDAMENTO_LIQUIDACAO`, `CONTA_NAO_PERMITE_PAGAMENTO`, `QRCODE_INVALIDO`, além de códigos granulares de `FALHA_INFRAESTRUTURA_*`	O conjunto de motivos de rejeição foi ampliado para refletir os novos instrumentos (Pix Saque/Troco, QR Code dinâmico autenticado).
Consulta cruzada indevida	`400`	Retornado ao tentar consultar, pelo endpoint v4.0.1, um recurso criado na v5.0.0.

Checklist de migração

Atualizar o path de todos os endpoints consumidos (v4 → v5) nos dois fluxos utilizados (JCR e/ou JSR).
Enviar payment.purpose em toda iniciação de pagamento Pix (IMMEDIATE, SINGLE_SCHEDULED, RECURRENT_SCHEDULED e, se aplicável ao seu caso de uso, WITHDRAW/CHANGE).
Tratar payloadJWS ao usar localInstrument APDN ou QRDN.
Atualizar parsers/regex de document.identification, cpfCnpj, ispb, endToEndId e creditor.name para os novos padrões alfanuméricos mais amplos.
Mover additionalInformation de schedule.custom para a raiz de schedule e passar a enviá-lo para todos os tipos de agendamento, não só custom.
Tratar os novos valores de localInstrument (APDN, APES) na lógica de exibição/roteamento de instrumento de pagamento.
Enviar transactionIdentification ao criar pagamentos Pix com localInstrument INIC ou QR Codes com TxId.
Tratar o novo erro 422 PAGAMENTO_DIVERGENTE_CONSENTIMENTO e garantir que o consentimento usado pertence à mesma versão do endpoint de pagamento.
Não tentar consultar recursos v5.0.0 pelos endpoints v4.0.1 (retornará 400) - direcionar toda consulta nova para os endpoints v5.
Atualizar tratamento de data.rejectionReason.code para reconhecer os novos motivos de rejeição.
Validar o comportamento de campos sentinela ao consultar, pela v5, recursos antigos criados na v4 (payloadJWS e schedule.additionalInformation).
Planejar o corte dentro do período de coexistência anunciado pela Celcoin/Open Finance Brasil, considerando o desligamento (sunset) futuro da v4.

Referências

Estrutura de Governança do Open Finance Brasil

Adaptações para Consultas de Recursos na API Pagamentos entre Versões 4.0.1 e 5.0.0

Documentação Celcoin - JCR (Jornada Com Redirecionamento)

Criar iniciação de pagamento: v4 · v5
Criar pagamento Pix: v4 · v5
Criar jornada de pagamento: v4 · v5
Listar jornadas de pagamento: v4 · v5
Buscar jornada de pagamento: v4 · v5

Documentação Celcoin - JSR (Jornada Sem Redirecionamento)

Criar iniciação de pagamento: v4 · v5
Criar pagamento Pix: v4 · v5
Criar jornada de pagamento: v4 · v5
Listar jornadas de pagamento: v4 · v5
Buscar jornada de pagamento: v4 · v5

Updated about 7 hours ago

Did this page help you?