Assinatura da ordem de pagamento

Esta página configura a assinatura da ordem de pagamento no plugin Pix (o trilho). Ela é opcional. Você precisa dela apenas se a assinatura da ordem de pagamento estiver habilitada para a sua instituição na JD, conforme o manual JDPI da JD (mecanismos de segurança). Confirme isso com a JD. Sem os valores de assinatura, nada muda.

Configurar a assinatura

Criar a chave e o certificado

Escolha o algoritmo. Use o padrão, a menos que você tenha um motivo para mudar.

Algoritmo	Chave
`ECDSA_P256_SHA256` (padrão)	ECDSA na curva P-256
`ECDSA_P384_SHA384`	ECDSA na curva P-384
`RSA_PKCS1_SHA256`	RSA, 3072 bits ou mais

Crie um par de chaves para a sua instituição. Ele assina todas as ordens de pagamento enviadas pela sua conexão com a JD, inclusive as dos participantes indiretos que você hospeda. Um certificado autoassinado é aceito. Rode o bloco do seu algoritmo. Cada bloco grava a chave privada em payment-signing.key e o certificado em payment-signing.crt.

ECDSA P-256 (padrão)
ECDSA P-384
RSA 3072

openssl ecparam -name prime256v1 -genkey -noout \
  | openssl pkcs8 -topk8 -nocrypt -out payment-signing.key
openssl req -new -x509 -key payment-signing.key -sha256 -days 730 \
  -subj "/CN=Example Institution Pix payment signing" -out payment-signing.crt

openssl ecparam -name secp384r1 -genkey -noout \
  | openssl pkcs8 -topk8 -nocrypt -out payment-signing.key
openssl req -new -x509 -key payment-signing.key -sha384 -days 730 \
  -subj "/CN=Example Institution Pix payment signing" -out payment-signing.crt

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out payment-signing.key
openssl req -new -x509 -key payment-signing.key -sha256 -days 730 \
  -subj "/CN=Example Institution Pix payment signing" -out payment-signing.crt

O trilho lê uma chave privada no formato PKCS#8, SEC 1 ou PKCS#1. Os comandos acima gravam PKCS#8. O tipo da chave deve combinar com o algoritmo.Antes de cadastrar o certificado, confirme que a chave privada é a chave do certificado:

key_pub=$(openssl pkey -in payment-signing.key -pubout) \
  && cert_pub=$(openssl x509 -in payment-signing.crt -noout -pubkey) \
  && [ -n "$key_pub" ] && [ "$key_pub" = "$cert_pub" ] \
  && echo "the key matches the certificate" \
  || echo "the key does NOT match the certificate"

Se a saída é the key does NOT match the certificate, a chave e o certificado não combinam, ou um arquivo não pode ser lido. Crie o par de novo. O trilho recusa um par que não combina com 409 PIX-0136, antes de chamar a JD.

Cadastrar o certificado na JD

O plugin Pix assina cada ordem de pagamento. Para a JD aceitar a ordem, a JD precisa conhecer o seu certificado: cadastre o certificado no JDPI Cabine. Envie apenas o certificado, que é público. Nunca envie a chave privada: ela vai apenas para o plugin Pix.

No JDPI Cabine, abra Gestão de Certificados.
Clique em Incluir.
Em Tipo Certificado, selecione Certificados Hash – Assinatura Payload.
Envie payment-signing.crt.
Anote o thumbprint que o JDPI Cabine mostra para o certificado.

Entregue ao plugin Pix o mesmo certificado no passo 4. Mais de um certificado pode estar ativo ao mesmo tempo, o que permite trocar uma chave sem interrupção. Veja Trocar a chave.

Conferir o thumbprint

Confirme que o certificado que você entrega ao trilho é o que está cadastrado no JDPI Cabine. Calcule o thumbprint dele:

openssl x509 -in payment-signing.crt -noout -fingerprint -sha1

A saída tem a forma sha1 Fingerprint=40:C0:3F:.... Tire os dois-pontos. O resultado deve ser igual ao thumbprint no JDPI Cabine. Para obter o valor sem dois-pontos direto:

openssl x509 -in payment-signing.crt -outform DER | openssl dgst -sha1 -r | cut -d' ' -f1 | tr a-f A-F

Configurar o plugin Pix

A configuração tem três valores. Defina a chave e o certificado juntos, ou nenhum dos dois. Com apenas um deles, o trilho recusa cada pagamento para outra instituição com 409 PIX-0136. Um valor PEM pode ter quebras de linha reais, ou ficar em uma linha com um \n literal em cada quebra de linha.

Self-hosted (single-tenant)
Hospedado pela Lerian

Defina as três variáveis de ambiente na API. As três são opcionais. O worker não envia ordens de pagamento, então não precisa delas.

Variável	Obrigatório	Padrão	Descrição
`JD_PAYMENT_SIGNING_PRIVATE_KEY`	Opcional. Defina junto com o certificado	—	PEM da chave privada. Um segredo.
`JD_PAYMENT_SIGNING_CERTIFICATE`	Opcional. Defina junto com a chave	—	PEM do certificado cadastrado no JDPI Cabine para essa chave.
`JD_PAYMENT_SIGNING_ALGORITHM`	Opcional	`ECDSA_P256_SHA256`	`ECDSA_P256_SHA256`, `ECDSA_P384_SHA384` ou `RSA_PKCS1_SHA256`.

Guarde a chave privada em um segredo, nunca em configuração aberta.Os valores passam a valer quando a API inicia.

Entregue à Lerian os mesmos três valores durante a configuração: a chave privada, o certificado que você cadastrou no JDPI Cabine e o algoritmo, se não for ECDSA_P256_SHA256. A Lerian aplica os valores quando provisiona o serviço para o seu tenant. Eles valem em segundos. Você não faz deploy nem reinicia nada.Envie a chave privada apenas pelo canal seguro que a Lerian fornece para credenciais durante a configuração.

Confirmar que funciona

Envie um Pix para outra instituição. Confirme que ele liquida. Se o pagamento for recusado ou terminar em ERROR, veja Se algo falhar.

Se algo falhar

O que você vê	Causa	O que fazer
`409 PIX-0136`	Um valor de assinatura falta ou não serve. Por exemplo: só a chave ou só o certificado está definido, o algoritmo não é um dos três, a chave não combina com o algoritmo, ou o certificado não é o certificado da chave.	Leia a mensagem. Ela nomeia o valor a corrigir.
A transação termina em `ERROR` com `JDPISPI017`, ou a API responde `422 PIX-1035`	A JD não aceitou a assinatura.	Calcule o thumbprint do certificado configurado e compare com os certificados no JDPI Cabine. Uma diferença significa que o trilho assina com um certificado que a JD não conhece. Se a assinatura não está configurada, configure.
A transação termina em `ERROR` com `JDPISPI018`, ou a API responde `422 PIX-1035`	A JD bloqueia os débitos da sua instituição depois de falhas repetidas de assinatura.	Corrija primeiro a causa do `JDPISPI017`. Mais ordens não encerram o bloqueio antes.

Em cada caso, o trilho libera o valor que reservou, e nenhum dinheiro se move. O trilho não envia de novo a ordem recusada. 409 PIX-0136 recusa apenas ordens de pagamento. As outras chamadas JD, como DICT e QR codes, continuam funcionando.

Trocar a chave

O JDPI Cabine aceita mais de um certificado ativo. Troque a chave nesta sequência, para que nenhuma ordem saia com um certificado que a JD não conhece:

Crie uma chave nova e um certificado novo.
Cadastre o certificado novo no JDPI Cabine. Mantenha o certificado antigo ativo.
Entregue a chave nova e o certificado novo ao trilho. Em um deploy hospedado pela Lerian, entregue à Lerian.
Espere a mudança valer. Em um deploy self-hosted, reinicie todas as instâncias da API em execução, para nenhuma continuar assinando com a chave antiga. Em um deploy hospedado pela Lerian, espere a Lerian confirmar a mudança.
Envie um Pix para outra instituição. Confirme que ele liquida.
Espere até que cada Pix enviado antes da mudança tenha um status final.
Exclua o certificado antigo do JDPI Cabine.

Páginas relacionadas

Variáveis de ambiente
Configurar o trilho
Para fazer o deploy do plugin, consulte o README do chart plugin-br-pix-jd.

Visão geral

Configuração

Capacidades opcionais

Assinatura da ordem de pagamento

Configurar a assinatura

Se algo falhar

Trocar a chave

Páginas relacionadas

​Configurar a assinatura

​Se algo falhar

​Trocar a chave

​Páginas relacionadas

Configurar a assinatura

Se algo falhar

Trocar a chave

Páginas relacionadas