Koru Financing Options

Shows your VTEX payment rules' installments and banks on the product page, with logos, CFT/TEA and highlights — no manual data entry, always with the real amounts.

Koru Financing Options is a VTEX Admin App with a storefront block that shows, on the product page, the store's real financing options: how many installments, with which bank and payment method, how much each installment costs, the plan total and the difference against the cash price.

What sets it apart from a traditional installments app is where the data comes from. Instead of typing banks, installments, validity dates and recurrences by hand, the app reads the payment rules that already exist in VTEX and groups them into options. The operator only adds what VTEX does not have: the bank or card logo, colors, a display name, the order, which ones to highlight, and the regulatory data (CFT, TEA and legal disclaimers). The amounts shoppers see are never calculated by the app: they come from the product itself in VTEX, so they cannot contradict the checkout.

The app has two sides:

• In VTEX Admin, the ecommerce team reviews the options coming from their payment rules, sees which ones are shown today and why, enriches them, uploads logos and adds options VTEX does not have as a rule (for example Mercado Pago or MODO).
• On the product page, the financing-block block shows the headline installment, the highlighted options, a plan comparison table and a popup with the full detail, filterable by bank or card.

Before you begin

Recommended owners

One person may cover several roles in a small store.

Required access

Before installing, make sure you have:

• A valid VTEX Admin session in the store account.
• A License Manager role with the Gerenciar condições de pagamento (manage payment conditions) resource — GerenciarCondicoesPagamento — for the people who will use the app. Without it, VTEX rejects reading the payment rules and the app reports it with the name of the missing resource.
• The official VTEX CLI installed and up to date.
• Permission to install apps in the chosen workspace and to modify the app's settings.
• Access to the store's Store Theme repository, to declare the block.
• The ecommerce Website ID in Koru Suite, with Koru Financing Options active for that site.

Koru Financing Options does not create its own VTEX role. Access is managed with the access controls available in VTEX License Manager.

Identifiers you will encounter

Installation with the VTEX CLI

Installation uses the official VTEX CLI and has two parts: installing the app in the account (this section) and declaring the block in the theme (see below). Without the second part, the Admin works fully but shoppers see nothing.

Install in a validation workspace first

If the store has a QA process, install and configure in a development workspace first. Replace the values in braces:

vtex login {store-account}

vtex use {store-account}/{workspace}

vtex whoami

vtex install {vendor}.koru-financing-options@0.x

vtex list

Open the app in VTEX Admin

The app appears in the VTEX Admin side menu, under the store setup section, as Opciones de Financiación. You can also navigate directly:

https://{workspace}--{store-account}.myvtex.com/admin/koru-financing-options

For master, use the account's main Admin domain:

https://{store-account}.myvtex.com/admin/koru-financing-options

If the app does not show up in the navigation, check vtex list, reload VTEX Admin and make sure you are looking at the same account and workspace where you installed it.

Install in master

Once the setup is validated in the corresponding workspace, select master, confirm the context again and repeat the installation:

vtex use {store-account}/master
vtex whoami
vtex install {vendor}.koru-financing-options@0.x
vtex list

Settings are per installation/workspace. Check the Website ID in the final environment even if you already tested it in another workspace. Enrichment, logos and manual options, on the other hand, are stored at the account level.

Updating and uninstalling

Update within the current major

Select the right account/workspace, confirm it and install the range again:

vtex whoami
vtex install {vendor}.koru-financing-options@0.x
vtex list

After updating, open the app, confirm the license and open the Options tab so the copy of the rules used by the product page is regenerated. Then check a real product page.

Uninstall

Uninstalling applies to the current workspace:

vtex whoami
vtex uninstall {vendor}.koru-financing-options
vtex list

Before uninstalling, remove the block and the dependency from the Store Theme: if the theme still references financing-block without the app installed, the product page fails with a missing block error.

Activation and first access

Get the Website ID

Before first use, Red Clover must activate Koru Financing Options for the corresponding website in Koru Suite. The Website ID is obtained from Koru Suite or delivered during activation.

The Website ID:

• Identifies the ecommerce within Koru Suite.
• Is not a password or a secret.
• Must belong to the same VTEX store where you installed the app.
• Is the only Koru identifier the merchant enters manually.

Connect the store

On first access, the app shows Connect this store to Koru Suite:

The app does not ask for an extra Koru login. The person is already authenticated in VTEX Admin; Koru Suite only validates that the Website ID + Koru Financing Options combination has an active license.

Each tab includes a guided tour that opens the first time you visit it and that you can replay with the View tour button.

Recommended initial setup

Follow this order to get to a correct product page without surprises:

Full configuration

The installation's own configuration is minimal: everything operational (enrichment, logos, manual options) is managed from the app's tabs.

The Koru App ID is built into the app and cannot be overridden from settings. Nothing is applied until you save; if you try to leave Settings with unsaved changes, the browser warns you.

How options are built

From payment rules to options

VTEX usually has many nearly identical payment rules: the same installment promotion repeated per card level (classic, gold, platinum…), per payment condition or per sales channel. For shoppers that is a single option. The app groups into one option all the rules that share:

• the issuing bank,
• the payment method,
• the installments with their interest rate,
• the validity (start and end date), and
• the recurrence (the weekdays on which it applies).

Card level, payment condition and sales channel do not split options. An option is considered active if at least one of its rules is. The list is sorted by bank and, within each bank, from most installments to fewest.

Visibility: is it shown on the product page today?

Each option shows a status, evaluated in this order:

The product page recalculates visibility on every request, so an option with a recurrence (for example "Wednesdays only") appears and disappears on its own. Also, an option hidden from Enrich is not shown on the product page even if it is visible.

Which options appear on each product

The product page does not show every option on every product. It matches each option against the installments VTEX calculates for that product: an option appears only if the product has the same payment method, the same number of installments and the same rate. That way, a product that does not allow 18 installments never shows "18 interest-free installments", and the amounts are always VTEX's.

Manual options are the exception: since they do not exist in VTEX, there are no product installments to match them against, so they are always shown while active and valid.

Enrichment

From the Options tab, the Enrich button on each row opens a form with two sections.

Reusable data (per bank or payment method)

Shared with all options of the same bank or, if the option has no bank, of the same payment method. Enter it once and it applies to all their campaigns.

This option's data

Applies only to the option you are editing.

When a campaign changes in VTEX: "New" status

The Enrichment column shows whether the option is Enriched, Not enriched or New.

An option becomes New when the campaign it had enriched is rebuilt in VTEX: its installments or rates, dates, recurrence, bank or payment method change. From the app's point of view it is a different option, so:

• The option's data (CFT, TEA, disclaimer, highlight, order, hide) stops being shown on the product page. Showing a CFT entered for a rate that no longer exists would be risky.
• The bank's or method's reusable data stays visible.
• When you open Enrich, the form brings back the previous values so you can review them and confirm them with Save.

Changing only the card level, payment condition or sales channel does not turn the option into a new one.

Manual options

With Create option you add financing that does not exist as a payment rule in VTEX, for example installments from a digital wallet processed outside the standard checkout.

• There cannot be two manual options for the same method with the same number of installments (ignoring case, accents and spaces).
• A manual option is enriched like any other, from Enrich.
• Edit details and Delete are in the Actions column. Deleting cannot be undone and also removes its enrichment.
• On the product page they are always shown (they are not matched against the product's installments), with a per-installment amount equal to price ÷ installments when they are interest-free.

Logos

The Logos tab lists every bank and every payment method that appears in the account's payment rules, once each. The logo you upload is used in every option where it appears.

• The file is validated in the browser before uploading and again on the server.
• On the product page, the logo replaces the colored badge. If an option has both a bank logo and a payment-method logo, the bank logo is shown.
• Once saved, the product page shows it within 15 minutes (see Update times).
• Replace uploads a new version; the With logo / Without logo filters help you see what is missing.

Show the block on the product page

The app declares the financing-block block, but it is the store's Store Theme that places it on the product page. There are two changes in the theme repository.

"dependencies": {
  "{vendor}.koru-financing-options": "0.x"
}

// store/blocks/product.jsonc
{
  "flex-layout.col#right-col": {
    "children": [
      "product-name",
      "product-price",
      "financing-block",
      "product-quantity",
      "add-to-cart-button"
    ]
  },
 
  "financing-block": {
    "props": {
      "maxHighlights": 3
    }
  }
}

Block props

All are optional and can also be edited from the Site Editor.

What shoppers see

• Headline installment: the product's best interest-free option, large, with its per-installment amount and the bank or method. On a tie, the one with more installments wins.
• Highlights: the options marked as highlighted (or, if there are none, the ones that apply), up to maxHighlights, each with its logo or badge.
• Comparison table: plan rows with installment amount, total and the difference vs. cash price, grouped into Interest-free, Cheaper than cash and With interest, plus the "1 payment" row.
• Popup ("See all N plans, with total and CFT"): Interest-free, More installments and Cash tabs, a bank or card filter, and extra columns with TEA / CFT and the payment-method logos. It closes with Escape, by clicking outside or with the button.
• Legal footer: CFT/TEA of the visible options with interest, the legal disclaimers entered, and always the note that the final plan is confirmed at checkout.

The block is translated into Spanish, English and Portuguese, following the store language. While loading, it reserves its space with a skeleton so the page does not jump.

Styles

The app ships its own base styles, so the block looks right straight after installation without writing any CSS. To adapt it to the brand, the theme can override the block's CSS handles (container, title, hero, highlight, badge, logo, table, tableRow, modal, legal, among others) with the prefix {vendor}-koru-financing-options-0-x-.

If something does not look right

Update times

The product page does not query VTEX Admin on every visit. It works with a copy of the options and a short cache, so it adds no latency to the page:

• Changes in the app (enrichment, logos, manual options): shown on the product page within 5 to 15 minutes.
• Changes in VTEX payment rules (a new campaign, a change of installments or validity): the copy is refreshed every time someone opens the Options or Logos tab in the Admin. After editing rules in VTEX, open Options and use Refresh; the product page reflects it within the next 15 minutes.
• Visibility by date and recurrence: recalculated on every request, no need to open the Admin.

Screens and daily operation

The app is organized into four tabs within the same panel.

License and security

License validation

All Admin routes require:

1. A valid VTEX Admin session.
2. An active Koru license for the Website ID and the Koru Financing Options App ID.

The product page (and the logos it shows) also depend on the license: if it is not active, the block falls back to basic mode and shows only the installment VTEX calculates, without logos, highlights, table, CFT or manual options. The product page never breaks because of a license problem.

To tolerate transient failures, a positive validation is kept for up to 72 hours if Koru Suite does not respond, and for 5 minutes after an isolated negative response. Past that margin, the app distinguishes an inactive license (the screen says so and offers to review the configuration) from a temporary outage (it asks you to retry, with no need to change anything).

Data and credentials

• The browser never calls VTEX private APIs or Koru Suite directly: everything goes through the app's own routes.
• The app does not ask for or store the merchant's AppKey/AppToken. Payment rules are read with the logged-in admin's session; that is why their role needs the Gerenciar condições de pagamento resource.
• The app only reads payment rules: it never creates, modifies or deletes them.
• Enrichment, manual options, logos and the rules copy used by the product page are stored in the account's own Master Data, in the app's entities.
• The product page's public route exposes only what is displayed to shoppers: method names, installments, rates, CFT/TEA, disclaimers and logos.
• Website ID and App ID identify resources, but they are not passwords.

Troubleshooting

The app does not appear after installing

1. Run vtex whoami.
2. Confirm the account and workspace.
3. Run vtex list and look for {vendor}.koru-financing-options.
4. Reload VTEX Admin.
5. Try the direct URL /admin/koru-financing-options on the same domain/workspace.

The session was rejected or expired

Log in to VTEX Admin again and reload the app.

"Your user does not have permission to read payment conditions"

Your License Manager role does not include the Gerenciar condições de pagamento resource (GerenciarCondicoesPagamento). Ask an account administrator to add it to your role and open the tab again.

"This account has no payment rules loaded in VTEX"

The account has no payment rules configured. Create them in VTEX's Payments module or, if the financing does not go through VTEX, use Create option.

An option is not shown on the product page

1. Check its Visibility column in Options: it must say Visible.
2. Make sure it is not marked Hide this option in Enrich.
3. Confirm that the product has that method, that number of installments and that rate in VTEX: the option only appears on products where VTEX offers it.
4. If the campaign changed in VTEX, open Options, use Refresh and wait up to 15 minutes.

The option shows as "New" and lost its CFT

The campaign changed in VTEX. Open Enrich, review the previous values the form brings back and confirm them with Save.

"The option changed in VTEX: refresh the list and try again"

Someone modified the payment rule while you had the list open. Use Refresh and enrich the option again.

The logo is not accepted

Check the format (PNG or WebP), height (40 to 56 px, ideally 48 px), width (up to 144 px) and size (up to 100 KB). The error message says which requirement is not met.

I cannot create a manual option

• A manual option for the same method with the same number of installments already exists: edit that one.
• The "until" date is earlier than the "from" date.
• The number of installments is outside 1 to 36.

The license shows as inactive

1. Compare the Website ID with the right site in Koru Suite.
2. Confirm that Koru Financing Options is active for that website.
3. Make sure you did not copy extra spaces.
4. Retry the validation from Overview → Refresh status.
5. If it persists, send the Website ID, account and workspace to support, without sending credentials.

Functional limits

The current version:

• Only reads VTEX payment rules; it does not show payment-method discounts or promotions.
• Does not distinguish sales channel or payment condition on the product page: an option is shown if the product has those installments in VTEX.
• Refreshes the rules copy used by the product page only when someone opens Options or Logos in the Admin; it does not sync on its own.
• Interprets the dates and days of manual options in Argentina time (UTC−3).
• Supports up to 5,000 records per data type (enrichments, manual options).
• Does not show the per-installment amount of manual options with interest.
• Always operates on the VTEX account where it is installed.

Pre-publishing checklist

• Koru Financing Options installed in the right account and workspace.
• Store Website ID verified and license active in Overview.
• Users with the Gerenciar condições de pagamento resource in their role.
• Options tab opened at least once in the account.
• Option visibility reviewed against the current campaigns.
• Logos uploaded for the banks and methods that are shown.
• CFT and TEA entered for every option with interest.
• Highlighted and hidden options defined.
• Manual options reviewed (real validity and installments).
• financing-block dependency and block declared in the theme.
• Real product pages checked on desktop and mobile in a workspace.
• Owner defined to review the app whenever campaigns change in VTEX.