Encrypted FinanceRates 6 min read

The FinanceRates field on GET /accounts/{AccountId}/product is defined as anyOf a structured AEProductFinanceRates object or an AEJwe compact string. Each LFI decides, per product, whether to return the rate in cleartext or as an encrypted JWE. A TPP holding ReadProductFinanceRates MUST therefore be ready for either shape on every call.

• Cleartext — FinanceRates is a JSON object. Render the rates directly. No special handling required.
• Encrypted (JWE) — FinanceRates is a compact JWE string. The TPP server MUST forward this opaque string to the user's device without inspecting, logging, or persisting it. Decryption happens in the browser using a one-time code the LFI sends to the customer.

Whether the LFI returns cleartext or an encrypted JWE, the request itself is unchanged. Make the call as you would for any other Bank Data Sharing endpoint:

import crypto from 'node:crypto'

const productResponse = await fetch(
  `${LFI_API_BASE}/open-finance/v2.1/accounts/${accountId}/product`,
  {
    headers: {
      Authorization:                `Bearer ${access_token}`,
      'x-fapi-interaction-id':      crypto.randomUUID(),
      'x-fapi-auth-date':           lastCustomerAuthDate,
      'x-fapi-customer-ip-address': customerIpAddress,
    },
    // agent: new https.Agent({ cert: transportCert, key: transportKey }),
  }
)

const { Data: { Product } } = await productResponse.json()
const product = Product[0]

Example response — cleartext

{
  "Data": {
    "Product": [
      {
        "AccountId": "acc-001",
        "ProductId": "credit-card-platinum",
        "ProductType": "CreditCard",
        "ProductName": "Platinum Credit Card",
        "FinanceRates": {
          "ProductFinanceRateProperties": [
            {
              "RateType": "PurchaseAPR",
              "Rate": "21.99",
              "RateApplication": "OnOutstandingBalance"
            }
          ]
        }
      }
    ]
  },
  "Links": {
    "Self": "https://rs1.altareq1.sandbox.apihub.openfinance.ae/open-finance/v2.1/accounts/acc-001/product"
  },
  "Meta": { "TotalPages": 1 }
}

Example response — encrypted JWE

{
  "Data": {
    "Product": [
      {
        "AccountId": "acc-001",
        "ProductId": "credit-card-platinum",
        "ProductType": "CreditCard",
        "ProductName": "Platinum Credit Card",
        "FinanceRates": "eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIiwicDJzIjoiNGtBWG..."
      }
    ]
  },
  "Links": {
    "Self": "https://rs1.altareq1.sandbox.apihub.openfinance.ae/open-finance/v2.1/accounts/acc-001/product"
  },
  "Meta": { "TotalPages": 1 }
}

Apart from FinanceRates, every other field in the response is returned in cleartext in both shapes — Charges, DepositRates, ProductName, Tenor, and so on. Only FinanceRates is ever encrypted.

When the LFI returns an encrypted FinanceRates, it also sends a one-time code to the customer directly, through a channel the LFI controls — an SMS, an email, or a push notification in the LFI's banking app. The TPP MUST display an input field where the customer can type that code, and a short explanation that matches the wording shown to the customer on the consent screen (“Your bank has sent you a one-time code — enter it below to see your finance rate”).

Click to expand ↗

What the customer receives

The LFI sends the code to the customer directly — the TPP never sees it. The message names the product, names your TradingName so the customer can tie it back to your application, and carries a 30-minute validity. Knowing the shape of the message helps you word your own prompt consistently with what the customer is reading on their phone:

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.

• Customer-present only — this flow only works when the customer is actively using the TPP. Do not call GET /accounts/{AccountId}/product on a schedule when you require the encrypted rate; there is no way to decrypt the JWE without the customer entering the OTP.
• Display the rate types you are about to reveal — tell the customer which product the OTP unlocks (for example, “Platinum Credit Card — purchase APR”).
• Offer to resend — if the customer does not receive the code, the TPP may re-call GET /accounts/{AccountId}/product to ask the LFI to issue a fresh code. Respect the rate limits described in Step 6 — Rate limits and retries.

The JWE carries a fixed 30-minute lifetime as an exp claim inside its plaintext, set by the LFI. Within that window the TPP MAY re-decrypt and re-render the rate as the customer navigates between screens, provided the OTP is still held in browser memory.

Decryption does not stop working when the window closes — a JWE and its OTP can technically be decrypted at any later time, so the 30-minute limit is not enforced by the cryptography. The TPP MUST enforce it: after decrypting, the TPP MUST read the exp claim from the plaintext and MUST NOT display the rate, or re-decrypt it for display, once exp has passed. This obligation is part of the TPP's Access Encrypted Resource Data certification.

// The JWE carries a 30-minute exp claim. Decryption still works past that
// point — the TPP MUST NOT display the rate once exp has passed. Track the
// expiry on the client so the UI can prompt for a fresh request proactively.
//
// You can pass the issuance time alongside the JWE when you serve the page —
// the JWE itself does not carry a parseable claim because it is opaque to the
// TPP server. The 30-minute window is a normative LFI rule, not a value you
// negotiate.
const JWE_TTL_MS = 30 * 60 * 1000
const expiresAt  = issuedAt + JWE_TTL_MS

if (Date.now() >= expiresAt) {
  // Re-fetch GET /accounts/{AccountId}/product to obtain a fresh JWE
  // (and a fresh OTP sent to the user's device). Honour the rate limit.
}

When the window closes mid-session, prompt the customer to request a fresh code via a new call to GET /accounts/{AccountId}/product rather than continuing to show a stale rate. The customer's consent is unaffected — only the 30-minute display window has expired.

• The TPP MUST NOT transmit, store, log, or otherwise process the unencrypted FinanceRates on its servers in any form or capacity. The decrypted value lives only in the customer's browser session.
• The TPP MUST perform all decryption of FinanceRates locally on the user's device, solely for the purpose of displaying the rate to the customer.
• The TPP MUST NOT interact with the encrypted or unencrypted FinanceRates in any manner other than as described in this guide.
• The TPP MUST submit its architectural plan for decryption and display of FinanceRates — including the relevant browser-side source — to Nebras for inspection and approval as part of the Access Encrypted Resource Data certification. Material changes to that process post go-live require Nebras sign-off before they are deployed.
• The TPP MUST present the decrypted rate accurately and in context — for example, labelling a credit card APR as “purchase APR” rather than “interest rate” — so the customer sees the rate faithfully as the LFI provided it.