> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Assinatura da ordem de pagamento

> Configure o plugin Pix para assinar as ordens de pagamento de saída quando a JD exige uma ordem de pagamento assinada: crie a chave e o certificado, cadastre o certificado no JDPI Cabine, confira os arquivos, configure o plugin, confirme e troque a chave.

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

**1. 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 |

Cada participante direto assina as suas ordens de pagamento com o seu próprio par de chaves. O plugin Pix 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`.

> [tab] ECDSA P-256 (padrão)
>
> ```bash theme={null}
> 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
> ```

> [tab] ECDSA P-384
>
> ```bash theme={null}
> 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
> ```

> [tab] RSA 3072
>
> ```bash theme={null}
> 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:

```bash theme={null}
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.

**2. 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.

1. No JDPI Cabine, abra **Gestão de Certificados**.
2. Clique em **Incluir**.
3. Em **Tipo Certificado**, selecione **Certificados Hash – Assinatura Payload**.
4. Envie `payment-signing.crt`.
5. 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](#replace-the-key).

**3. Conferir o thumbprint**

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

```bash theme={null}
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:

```bash theme={null}
openssl x509 -in payment-signing.crt -outform DER | openssl dgst -sha1 -r | cut -d' ' -f1 | tr a-f A-F
```

**4. 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.

> [tab] Self-hosted (single-tenant)
>
> 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.

> [tab] Hospedado pela Lerian
>
> 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. 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.

**5. 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](#if-something-fails).

## 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 terminam 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:

1. Crie uma chave nova e um certificado novo.
2. Cadastre o certificado novo no JDPI Cabine. Mantenha o certificado antigo ativo.
3. Entregue a chave nova e o certificado novo ao trilho. Em um deploy hospedado pela Lerian, entregue à Lerian.
4. 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.
5. Envie um Pix para outra instituição. Confirme que ele liquida.
6. Espere até que cada Pix enviado antes da mudança tenha um status final.
7. Exclua o certificado antigo do JDPI Cabine.

## Páginas relacionadas

* [Variáveis de ambiente](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md)
* [Configurar o trilho](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-setup.md)
* Para fazer o deploy do plugin, consulte o [README do chart plugin-br-pix-jd](https://github.com/LerianStudio/helm/tree/main/charts/plugin-br-pix-jd).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.