@forgeco/ext-payment-reference

The front half of a Forge app: the reference payment provider's checkout UI — the card form and the PIX display, behind the two payment roles.

A Forge app has two halves. Its manifest and its provider run inside the kernel, which already ships them; what a storefront needs is the React blocks, and that is all this package contains. It is part of the reference storefront — yours to import, wrap, or replace.

⚠️ This app is a SIMULATOR. It approves, declines and times out by the digits of the typed card number so a store can be exercised end to end without a real PSP. Turn it off in production (the app's active config switch); the real card entry is @forgeco/ext-payment-mercadopago.

Install

The Forge packages are published as tarballs on the GitHub Release, so install them together — they resolve each other from the sibling files, not from a registry:

npm i ./forgeco-contracts-<version>.tgz ./forgeco-ext-*-<version>.tgz

Use it

A payment app presents itself in two ROLES, and the storefront mounts each where its own layout puts it: the options role before the charge, the after-payment role once the order is placed.

import PaymentOptions from '@forgeco/ext-payment-reference/payment-options';
import AfterPayment from '@forgeco/ext-payment-reference/after-payment';

Each role receives the NEUTRAL kernel method (pix, card) plus this app's own config, and decides what to draw — the storefront never needs to know which methods the app serves.

⚠️ One required line in next.config

This package ships its components as source (.tsx + CSS Modules), so your bundler compiles them along with your own code — that is what keeps the styles, the tokens and the tree-shaking working. Next skips node_modules unless you say otherwise:

// next.config.mjs
export default {
  transpilePackages: ['@forgeco/ext-payment-reference'],
};

Without it the build fails loudly (Module parse failed: Unexpected token) — it never degrades into an unstyled page.

The blocks style themselves in semantic design tokens, never literal colours, so install @forgeco/theme-storefront-vanilla (or provide the same token names from your own theme) and import its tokens.css once in your root layout.

Licence

Apache-2.0. The Forge kernel itself is BUSL-1.1; what you install and compile against is permissive on purpose — your storefront code is yours.