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

# Firma de la orden de pago

> Configura el plugin Pix para firmar las órdenes de pago de salida cuando JD exige una orden de pago firmada: crea la clave y el certificado, registra el certificado en JDPI Cabine, revisa los archivos, configura el plugin, confirma y cambia la clave.

Esta página configura la firma de la orden de pago en el plugin Pix (el riel). Es opcional. La necesitas solo si la firma de la orden de pago está habilitada para tu institución en JD, según el manual JDPI de JD (mecanismos de seguridad). Confírmalo con JD. Sin los valores de firma, nada cambia.

## Configurar la firma

<Steps>
  <Step title="Crear la clave y el certificado">
    Elige el algoritmo. Usa el predeterminado, a menos que tengas un motivo para cambiarlo.

    | Algoritmo | Clave |
    | - | - |
    | `ECDSA_P256_SHA256` (predeterminado) | ECDSA en la curva P-256 |
    | `ECDSA_P384_SHA384` | ECDSA en la curva P-384 |
    | `RSA_PKCS1_SHA256` | RSA, 3072 bits o más |

    Crea un par de claves para tu institución. Firma todas las órdenes de pago enviadas por tu conexión con JD, incluidas las de los participantes indirectos que alojas. Se acepta un certificado autofirmado. Ejecuta el bloque de tu algoritmo. Cada bloque escribe la clave privada en `payment-signing.key` y el certificado en `payment-signing.crt`.

    <Tabs>
      <Tab title="ECDSA P-256 (predeterminado)">
        ```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>

    El riel lee una clave privada en formato PKCS#8, SEC 1 o PKCS#1. Los comandos de arriba escriben PKCS#8. El tipo de la clave debe coincidir con el algoritmo.

    Antes de registrar el certificado, confirma que la clave privada es la clave del 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"
    ```

    Si la salida es `the key does NOT match the certificate`, la clave y el certificado no coinciden, o un archivo no se puede leer. Crea el par de nuevo. El riel rechaza un par que no coincide con `409 PIX-0136`, antes de llamar a JD.
  </Step>

  <Step title="Registrar el certificado en JD">
    El plugin Pix firma cada orden de pago. Para que JD la acepte, JD debe conocer tu certificado: regístralo en JDPI Cabine. Sube solo el certificado, que es público. Nunca subas ni envíes la clave privada: va solo al plugin Pix.

    1. En JDPI Cabine, abre **Gestão de Certificados**.
    2. Haz clic en **Incluir**.
    3. En **Tipo Certificado**, selecciona **Certificados Hash – Assinatura Payload**.
    4. Sube `payment-signing.crt`.
    5. Anota el thumbprint que JDPI Cabine muestra para el certificado.

    Entrega al plugin Pix el mismo certificado en el paso 4. Más de un certificado puede estar activo al mismo tiempo, lo que permite cambiar una clave sin interrupción. Consulta [Cambiar la clave](#replace-the-key).
  </Step>

  <Step title="Revisar el thumbprint">
    Confirma que el certificado que entregas al riel es el que está registrado en JDPI Cabine. Calcula su thumbprint:

    ```bash theme={null}
    openssl x509 -in payment-signing.crt -noout -fingerprint -sha1
    ```

    La salida tiene la forma `sha1 Fingerprint=40:C0:3F:...`. Quita los dos puntos. El resultado debe ser igual al thumbprint en JDPI Cabine. Para obtener el valor sin dos puntos directamente:

    ```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 el plugin Pix">
    La configuración tiene tres valores. Define la clave y el certificado juntos, o ninguno. Con solo uno de ellos, el riel rechaza cada pago a otra institución con `409 PIX-0136`. Un valor PEM puede tener saltos de línea reales, o estar en una línea con un `\n` literal en cada salto de línea.

    <Tabs>
      <Tab title="Self-hosted (single-tenant)">
        Define las tres variables de entorno en la API. Las tres son opcionales. El worker no envía órdenes de pago, así que no las necesita.

        | Variable | Obligatorio | Predeterminado | Descripción |
        | - | - | - | - |
        | `JD_PAYMENT_SIGNING_PRIVATE_KEY` | Opcional. Defínela junto con el certificado | — | PEM de la clave privada. Un secreto. |
        | `JD_PAYMENT_SIGNING_CERTIFICATE` | Opcional. Defínelo junto con la clave | — | PEM del certificado registrado en JDPI Cabine para esa clave. |
        | `JD_PAYMENT_SIGNING_ALGORITHM` | Opcional | `ECDSA_P256_SHA256` | `ECDSA_P256_SHA256`, `ECDSA_P384_SHA384` o `RSA_PKCS1_SHA256`. |

        Guarda la clave privada en un secreto, nunca en configuración abierta.

        Los valores aplican cuando la API inicia.
      </Tab>

      <Tab title="Alojado por Lerian">
        Entrega a Lerian los mismos tres valores durante la configuración: la clave privada, el certificado que registraste en JDPI Cabine y el algoritmo, si no es `ECDSA_P256_SHA256`. Lerian aplica los valores cuando aprovisiona el servicio para tu tenant. Aplican en segundos. No haces despliegue ni reinicias nada.

        Envía la clave privada solo por el canal seguro que Lerian te da para credenciales durante la configuración.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Confirmar que funciona">
    Envía un Pix a otra institución. Confirma que se liquida. Si el pago se rechaza o termina en `ERROR`, consulta [Si algo falla](#if-something-fails).
  </Step>
</Steps>

<h2 id="if-something-fails">
  Si algo falla
</h2>

| Qué ves | Causa | Qué hacer |
| - | - | - |
| `409 PIX-0136` | Falta un valor de firma o no sirve. Por ejemplo: solo la clave o solo el certificado está definido, el algoritmo no es uno de los tres, la clave no coincide con el algoritmo, o el certificado no es el certificado de la clave. | Lee el mensaje. Nombra el valor a corregir. |
| La transacción termina en `ERROR` con `JDPISPI017`, o la API responde `422 PIX-1035` | JD no aceptó la firma. | Calcula el thumbprint del certificado configurado y compáralo con los certificados en JDPI Cabine. Una diferencia significa que el riel firma con un certificado que JD no conoce. Si la firma no está configurada, configúrala. |
| La transacción termina en `ERROR` con `JDPISPI018`, o la API responde `422 PIX-1035` | JD bloquea los débitos de tu institución después de fallas repetidas de firma. | Corrige primero la causa del `JDPISPI017`. Más órdenes no terminan el bloqueo antes. |

En cada caso, el riel libera el monto que reservó, y no se mueve dinero. El riel no envía de nuevo la orden rechazada. `409 PIX-0136` rechaza solo órdenes de pago. Las otras llamadas a JD, como DICT y códigos QR, siguen funcionando.

<h2 id="replace-the-key">
  Cambiar la clave
</h2>

JDPI Cabine acepta más de un certificado activo. Cambia la clave en esta secuencia, para que ninguna orden salga con un certificado que JD no conoce:

1. Crea una clave nueva y un certificado nuevo.
2. Registra el certificado nuevo en JDPI Cabine. Mantén activo el certificado antiguo.
3. Entrega la clave nueva y el certificado nuevo al riel. En un despliegue alojado por Lerian, entrégalos a Lerian.
4. Espera a que el cambio aplique. En un despliegue self-hosted, reinicia todas las instancias de la API en ejecución, para que ninguna siga firmando con la clave anterior. En un despliegue alojado por Lerian, espera a que Lerian confirme el cambio.
5. Envía un Pix a otra institución. Confirma que se liquida.
6. Espera a que cada Pix enviado antes del cambio tenga un estado final.
7. Elimina el certificado antiguo de JDPI Cabine.

## Páginas relacionadas

* [Variables de entorno](/es/interfaces/pix-jd/pix-jd-environment-variables)
* [Configurar el riel](/es/interfaces/pix-jd/pix-jd-setup)
* Para desplegar el plugin, consulta el [README del 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.