Payment-order signing

This page sets up payment-order signing in the Pix plugin (the rail). It is optional. You need it only if payment-order signature is enabled for your institution at JD, as defined in JD’s JDPI manual (security mechanisms). Confirm this with JD. Without the signing values, nothing changes.

Set up signing

Create the key and the certificate

Choose the algorithm. Use the default unless you have a reason to change it.

Algorithm	Key
`ECDSA_P256_SHA256` (default)	ECDSA on the P-256 curve
`ECDSA_P384_SHA384`	ECDSA on the P-384 curve
`RSA_PKCS1_SHA256`	RSA, 3072 bits or more

Create one key pair for your institution. It signs every payment order sent through your JD connection, including those of the indirect participants you host. A self-signed certificate is accepted. Run the block for your algorithm. Each block writes the private key to payment-signing.key and the certificate to payment-signing.crt.

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

The rail reads a private key in PKCS#8, SEC 1, or PKCS#1 format. The commands above write PKCS#8. The key type must agree with the algorithm.Before you register the certificate, make sure that the private key is the key of the certificate:

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"

If the output is the key does NOT match the certificate, the key and the certificate do not agree, or a file cannot be read. Create the pair again. The rail refuses a pair that does not agree with 409 PIX-0136, before it calls JD.

The Pix plugin signs each payment order. For JD to accept it, JD must know your certificate: register it in JDPI Cabine. Upload only the certificate, which is public. Never upload or send the private key: it goes only to the Pix plugin.

In JDPI Cabine, open Gestão de Certificados.
Click Incluir.
In Tipo Certificado, select Certificados Hash – Assinatura Payload.
Upload payment-signing.crt.
Write down the thumbprint that JDPI Cabine shows for the certificate.

Give the Pix plugin the same certificate in step 4. More than one certificate can be active at the same time, which lets you replace a key with no interruption. See Replace the key.

Check the thumbprint

Make sure that the certificate that you give to the rail is the one registered in JDPI Cabine. Calculate its thumbprint:

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

The output has the form sha1 Fingerprint=40:C0:3F:.... Remove the colons. The result must be the same as the thumbprint in JDPI Cabine. To get the value without colons directly:

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

Configure the Pix plugin

The configuration has three values. Set the key and the certificate together, or neither. With only one of them, the rail refuses each payment to another institution with 409 PIX-0136. A PEM value can have real line breaks, or be on one line with a literal \n at each line break.

Self-hosted (single-tenant)
Lerian-hosted

Set the three environment variables on the API. All three are optional. The worker does not send payment orders, so it does not need them.

Variable	Required	Default	Description
`JD_PAYMENT_SIGNING_PRIVATE_KEY`	Optional. Set it together with the certificate	—	PEM of the private key. A secret.
`JD_PAYMENT_SIGNING_CERTIFICATE`	Optional. Set it together with the key	—	PEM of the certificate registered in JDPI Cabine for that key.
`JD_PAYMENT_SIGNING_ALGORITHM`	Optional	`ECDSA_P256_SHA256`	`ECDSA_P256_SHA256`, `ECDSA_P384_SHA384`, or `RSA_PKCS1_SHA256`.

Keep the private key in a secret, never in plain configuration.The values take effect when the API starts.

Give Lerian the same three values during setup: the private key, the certificate that you registered in JDPI Cabine, and the algorithm if it is not ECDSA_P256_SHA256. Lerian applies them when it provisions the service for your tenant. They take effect in seconds. You do not deploy or restart anything.Send the private key only through the secure channel that Lerian gives you for credentials during setup.

Confirm that it works

Send a Pix to another institution. Make sure that it settles. If the payment is refused or ends in ERROR, see If something fails.

If something fails

What you see	Cause	What to do
`409 PIX-0136`	A signing value is missing or not usable. For example: only the key or only the certificate is set, the algorithm is not one of the three, the key does not agree with the algorithm, or the certificate is not the certificate of the key.	Read the message. It names the value to correct.
The transaction ends in `ERROR` with `JDPISPI017`, or the API answers `422 PIX-1035`	JD did not accept the signature.	Calculate the thumbprint of the configured certificate and compare it with the certificates in JDPI Cabine. A difference means that the rail signs with a certificate that JD does not know. If signing is not configured, configure it.
The transaction ends in `ERROR` with `JDPISPI018`, or the API answers `422 PIX-1035`	JD blocks the debits of your institution after repeated signature failures.	Correct the cause of `JDPISPI017` first. More orders do not end the block sooner.

In each case, the rail releases the amount that it reserved, and no money moves. The rail does not send the refused order again. 409 PIX-0136 refuses only payment orders. The other JD calls, such as DICT and QR codes, continue to work.

Replace the key

JDPI Cabine accepts more than one active certificate. Replace the key in this sequence, so that no order goes out with a certificate that JD does not know:

Create a new key and a new certificate.
Register the new certificate in JDPI Cabine. Keep the old certificate active.
Give the new key and the new certificate to the rail. On a Lerian-hosted deployment, give them to Lerian.
Wait until the change takes effect. On a self-hosted deployment, restart every running API instance, so none keeps signing with the old key. On a Lerian-hosted deployment, wait until Lerian confirms the change.
Send a Pix to another institution. Make sure that it settles.
Wait until every Pix sent before the change has a final status.
Delete the old certificate from JDPI Cabine.

Environment variables
Setting up the rail
To deploy the plugin, see the plugin-br-pix-jd chart README.

Overview

Setup

Optional capabilities

Payment-order signing

Set up signing

If something fails

Replace the key

​Set up signing

​If something fails

​Replace the key

​Related pages

Set up signing

If something fails

Replace the key

Related pages