Encrypted FinanceRates 7 min read

The FinanceRates field on GET /accounts/{AccountId}/product is defined as anyOf a structured AEProductFinanceRates object or an AEJwe compact string. LFIs MAY decide, per product, whether to return the rate in cleartext or as a JWE. Encryption is typically applied to credit cards, finance accounts, and mortgages where the finance rate is commercially sensitive; deposit account interest rates are returned in cleartext.

• The LFI MUST NOT encrypt any field other than FinanceRates on this endpoint. Charges, DepositRates, ProductName, Tenor, and every other property stay cleartext on both the encrypted and unencrypted shapes.
• The LFI MUST NOT encrypt any data from any other Open Finance endpoint — this mechanism exists solely for FinanceRates on GET /accounts/{AccountId}/product.
• A single LFI MAY choose to encrypt for some product types and not others. The TPP detects the shape at runtime by checking whether FinanceRates is an object or a string — the LFI does not need to advertise its choice ahead of time.

Before doing anything else — before deciding to encrypt, before generating an OTP, before delivering the code, before building a JWE — the LFI MUST check that the consent underlying this request includes ReadProductFinanceRates. If the permission is absent, the LFI MUST omit the FinanceRates field from the response entirely. The rest of the product payload (Charges, DepositRates, ProductName, etc.) is returned as usual.

How to read the permission

The API Hub sets the o3-consent-id header on every Ozone Connect call made under a consent. That ID identifies the consent the customer authorised; the LFI's job is to retrieve the consent, read the Permissions array off it, and check that ReadProductFinanceRates is present. The LFI does NOT re-validate the access token — that is the Hub's responsibility.

There are two valid ways to obtain the consent record. Pick whichever fits your architecture; both are first-class:

Whichever option you use, the check itself is the same: permissions.includes('ReadProductFinanceRates'). If false — omit FinanceRates. If true — proceed to the cleartext or encrypted path based on LFI policy for the product type.

• The check applies equally to the cleartext and encrypted paths. If ReadProductFinanceRates is missing, the LFI MUST NOT return cleartext rates and MUST NOT trigger the code-generation, delivery, or JWE flow.
• When the field is omitted, do not substitute null, an empty object, or a placeholder JWE. The FinanceRates key simply does not appear on the Product object.
• The same o3-consent-id header is used to attribute the call for logging, rate-limit accounting (Step 6), and audit. Read it once and carry it through the request handler.

import type { Request } from 'express'

const HUB_CONSENT_MANAGER_BASE = process.env.HUB_CONSENT_MANAGER_BASE!
// e.g. 'https://cm.altareq1.apihub.openfinance.ae'

// Option A — read from your local consent store.
// You populated it via /consent/event/{operation} during the consent-events
// flow at authorization time.
function readPermissionsLocal(consentId: string): ReadonlyArray<string> {
  const consent = consentStore.get(consentId)
  return consent.Permissions
}

// Option B — fetch the consent from the Hub's Consent Manager.
// Authenticate using your LFI's Ozone Connect JWT credentials.
async function readPermissionsFromHub(consentId: string): Promise<ReadonlyArray<string>> {
  const response = await fetch(
    `${HUB_CONSENT_MANAGER_BASE}/consents/${consentId}`,
    {
      headers: {
        Authorization: `Bearer ${await getOzoneConnectJwt()}`,
      },
    },
  )
  if (!response.ok) {
    throw new Error(`Hub /consents/${consentId} failed: ${response.status}`)
  }
  const consent = await response.json()
  return consent.Permissions
}

// Pick whichever fits your architecture; both are first-class.
const readPermissions = readPermissionsLocal  // or readPermissionsFromHub

async function buildFinanceRates(
  req: Request,
  product: Product,
): Promise<AEProductFinanceRates | EncryptedFinanceRates | undefined> {
  const consentId = req.header('o3-consent-id')
  if (!consentId) {
    // Defensive — the Hub always sets this on Ozone Connect calls under a
    // consent. A missing header is a misconfiguration, not a customer issue.
    throw new Error('o3-consent-id header missing on Ozone Connect request')
  }

  const permissions = await readPermissions(consentId)

  // Gate the entire FinanceRates field on this single permission.
  if (!permissions.includes('ReadProductFinanceRates')) {
    // Omit the field entirely. Do not generate an OTP, do not deliver a code,
    // do not build a JWE — and do not return an empty object placeholder.
    return undefined
  }

  // Permission is present — choose between cleartext and the encrypted path
  // based on LFI policy for this product type.
  return shouldEncrypt(product)
    ? encryptedFinanceRatesFor(product)
    : product.financeRates
}

The LFI MUST deliver the OTP to the customer directly, through a channel the LFI controls and the customer can reach without involving the TPP. The LFI chooses the channel: an SMS to the customer's registered mobile number, an email to their registered address, or a push notification or message in the LFI's own mobile banking app are all acceptable. The LFI MUST NOT deliver the OTP through the TPP — the entire point is that the TPP never holds the decryption key.

Whichever channel the LFI uses, it MUST actively deliver the code to the customer — the customer must be sent the code, not asked to go and find it. A push notification that surfaces the code, or that deep-links the customer straight to it, meets this bar; a design that requires the customer to independently open the banking app and hunt for the code does not. The LFI provides the code to the customer; the customer never has to retrieve it.

Message content requirements

• The OTP itself.
• The LFI's brand name as a recognisable sender or in the first line of the body, so the customer can identify who sent the message.
• The TPP's TradingName (from the consent), so the customer knows which app to enter the code into. This is the part of the message the customer uses to bridge the LFI-sent message with the TPP-presented form.
• The product name or a short product description, so the customer understands which rate they are about to view.
• An expiry indication — "Valid 30 min" is the canonical wording.
• An explicit anti-fraud line for the customer who did not start this journey — "If you didn't request this, ignore this message and never share this rate." The wording matters: it tells an unsuspecting customer to disregard the message, and warns every customer never to read the code aloud to anyone — while leaving them free to type it into the TPP form themselves.

Message template

A recommended template the LFI substitutes from the request context — the TPP_TRADING_NAME comes from the consent's TPP organisation registration, the PRODUCT_NAME from the product the call is for, and OTP from Step 2. The example is written for SMS; the same content requirements apply whatever channel the LFI delivers on:

{LFI_BRAND}: You requested your {PRODUCT_NAME} finance rate via {TPP_TRADING_NAME}. Your code is {OTP}. Valid 30 min. If you didn't request this, ignore this message and never share this rate.

Example SMS as the customer receives it

ALTAREQ BANK: You requested your Platinum Credit Card finance rate via BudgetBuddy. Your code is 482915. Valid 30 min. If you didn't request this, ignore this message and never share this rate.

The wording is intentionally explicit about where the code is to be entered — the message arrives from the bank but the form sits inside the TPP application, and the customer needs to bridge those two contexts. Naming the TPP makes that connection.

The OpenAPI schema makes the response trivial to assemble: FinanceRates is either an AEProductFinanceRates object or an AEJwe string. Replace the cleartext object with the compact JWE produced in Step 4 and leave every other field untouched.

// Build the GET /accounts/{AccountId}/product response.
// Only the FinanceRates field is encrypted — every other field
// (Charges, DepositRates, Tenor, ProductName, ...) stays cleartext.
function buildProductResponse(
  account: Account,
  product: Product,
  encryptedFinanceRatesJwe: string | undefined,
) {
  return {
    Data: {
      Product: [
        {
          AccountId:     account.id,
          ProductId:     product.id,
          ProductType:   product.type,
          ProductName:   product.name,
          Charges:       product.charges,
          DepositRates:  product.depositRates,
          Tenor:         product.tenor,
          // FinanceRates is either the structured object (cleartext)
          // or the compact JWE string (encrypted). Never both, never null.
          FinanceRates:  encryptedFinanceRatesJwe ?? product.financeRates,
        },
      ],
    },
    Links: { Self: selfUrl(account, product) },
    Meta:  { TotalPages: 1 },
  }
}

See the corresponding TPP API guide for how the TPP detects the JWE shape, forwards it to the user's device, and decrypts using the OTP the customer types in.