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

<Steps>
  <Step title="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`.

    <Tabs>
      <Tab title="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>

      <Tab title="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>

      <Tab title="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
        ```
      </Tab>
    </Tabs>

    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.
  </Step>

  <Step title="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.

    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).
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="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.

    <Tabs>
      <Tab title="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>

      <Tab title="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. 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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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).
  </Step>
</Steps>

<h2 id="if-something-fails">
  Se algo falhar
</h2>

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

<h2 id="replace-the-key">
  Trocar a chave
</h2>

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](/pt/interfaces/pix-jd/pix-jd-environment-variables)
* [Configurar o trilho](/pt/interfaces/pix-jd/pix-jd-setup)
* 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.