Personal Identifiable Information (PII) 3 min read

The PersonalIdentifiableInformation field MUST be sent as a compact JWE — a signed-then-encrypted token (Nested JWT). The process is:

• Build the PII JSON — construct the PII object for the stage you are at (POST/par or POST/payments). See The PII payload structure below.
• Sign — sign the PII payload as a JWS using your TPP signing key. The JWS MUST include standard claims (iat, exp, jti, iss, sub, aud).
• Fetch the LFI's encryption key — retrieve the LFI's JWKS and select the key where "use": "enc".
• Encrypt — encrypt the signed JWS into a compact JWE using RSA-OAEP-256 / A256GCM.
• Embed — place the resulting JWE string in the PersonalIdentifiableInformation field of your request.

Example

import { SignJWT, importJWK, CompactEncrypt } from 'jose'
import { v4 as uuidv4 } from 'uuid'

async function encryptPII(
  piiPayload: Record<string, unknown>,
  signingKey: KeyLike,
  signingKeyId: string,
  signingAlg: string,
  clientId: string,
  audience: string,
  jwksUri: string
): Promise<string> {
  const now = Math.floor(Date.now() / 1000)

  // 1. Sign the PII payload
  const jws = await new SignJWT(piiPayload)
    .setProtectedHeader({ alg: signingAlg, kid: signingKeyId })
    .setIssuedAt(now)
    .setExpirationTime(now + 300)
    .setJti(uuidv4())
    .setIssuer(clientId)
    .setSubject(clientId)
    .setAudience(audience)
    .sign(signingKey)

  // 2. Fetch the LFI's JWKS and find the encryption key
  const response = await fetch(jwksUri)
  const { keys } = await response.json()
  const encKeyJwk = keys.find((k: any) => k.use === 'enc')
  if (!encKeyJwk) throw new Error('No encryption key (use: enc) found in JWKS')

  // 3. Encrypt the signed JWS into a JWE
  const publicKey = await importJWK(encKeyJwk, 'RSA-OAEP-256')
  const jwe = await new CompactEncrypt(new TextEncoder().encode(jws))
    .setProtectedHeader({
      alg: 'RSA-OAEP-256',
      enc: 'A256GCM',
      kid: encKeyJwk.kid,
    })
    .encrypt(publicKey)

  return jwe // → place this string in PersonalIdentifiableInformation
}

For the full breakdown of JWKS discovery, key selection, and JWE structure, see Message Encryption.

The structure of the unencrypted PII differs between the two stages.

At POST/par (consent staging)

{
  "Initiation": {
    "DebtorAccount": { ... },       // optional — see Debtor Account
    "Creditor": [                   // array of creditor entries — see Creditor
      {
        "CreditorAgent": { ... },
        "Creditor": { "Name": "..." },
        "CreditorAccount": { ... },
        "ConfirmationOfPayeeResponse": "..."
      }
      // ... up to 10 entries; omit array entirely for open beneficiary
    ]
  },
  "Risk": { ... }                   // required — see Risk
}

At POST/payments (payment creation)

{
  "Initiation": {
    "CreditorAgent": { ... },               // flat on Initiation — not inside an array
    "Creditor": { "Name": "..." },
    "CreditorAccount": { ... },
    "ConfirmationOfPayeeResponse": "..."
  },
  "Risk": { ... }
}

The key difference: at POST/par the creditor data is inside an Initiation.Creditor[] array (allowing 1–10 entries, or omitted for open beneficiary). At POST/payments the same fields sit directly on Initiation as a single creditor.

See the sub-pages for full schema and rules:

• Debtor Account — optional at POST/par only; not part of the POST/payments PII
• Creditor — consent-time models (single/multiple/open), payment-time structure, and match requirements
• Risk — debtor and creditor risk indicators