Firma de la orden de pago

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

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.

ECDSA P-256 (predeterminado)
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

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:

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.

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.

En JDPI Cabine, abre Gestão de Certificados.
Haz clic en Incluir.
En Tipo Certificado, selecciona Certificados Hash – Assinatura Payload.
Sube payment-signing.crt.
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.

Revisar el thumbprint

Confirma que el certificado que entregas al riel es el que está registrado en JDPI Cabine. Calcula su thumbprint:

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:

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

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.

Self-hosted (single-tenant)
Alojado por Lerian

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.

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.

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.

Si algo falla

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.

Cambiar la clave

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:

Crea una clave nueva y un certificado nuevo.
Registra el certificado nuevo en JDPI Cabine. Mantén activo el certificado antiguo.
Entrega la clave nueva y el certificado nuevo al riel. En un despliegue alojado por Lerian, entrégalos a Lerian.
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.
Envía un Pix a otra institución. Confirma que se liquida.
Espera a que cada Pix enviado antes del cambio tenga un estado final.
Elimina el certificado antiguo de JDPI Cabine.

Páginas relacionadas

Variables de entorno
Configurar el riel
Para desplegar el plugin, consulta el README del chart plugin-br-pix-jd.

Resumen

Configuración

Capacidades opcionales

Firma de la orden de pago

Configurar la firma

Si algo falla

Cambiar la clave

Páginas relacionadas

​Configurar la firma

​Si algo falla

​Cambiar la clave

​Páginas relacionadas

Configurar la firma

Si algo falla

Cambiar la clave

Páginas relacionadas