FiscoJet

Integrazioni · Form hosted

Il form di FiscoJet nel tuo checkout

Il form si mostra nella tua pagina, prima del pagamento: il cliente vede il riepilogo dell'ordine e scrive i dati per la fattura, già controllati. Il tuo server crea la sessione e il pagamento Stripe, la pagina monta il form con la chiave pubblica.

Gli altri modi

API

Il tuo checkout chiede già i dati?

Mandali a FiscoJet dal tuo server con POST /checkout, senza il form.

WordPress e WooCommerce

Vendi con WooCommerce?

Il plugin fa tutto senza codice, con ogni metodo di pagamento.

Chiavi e indirizzo dell'API

Le generi nella pagina Sviluppatore della dashboard.

Le due chiavi di FiscoJet
ChiaveFormatoDove si usa
Segretafj_live_sk_…Solo sul tuo server, nell'header Authorization: Bearer. Serve per POST /checkout, POST /checkout/session e GET /checkout/:uuid. Non deve mai arrivare al browser.
Pubblicafj_pk_live_…Nella pagina, nell'opzione publishableKey del form hosted. Può stare nel codice che arriva al browser.
  • La chiave segreta la vedi una volta sola, quando la generi. Se ne generi un'altra, la precedente smette di funzionare.
  • Anche la chiave pubblica, se la rigeneri, sostituisce quella vecchia.
  • Se nella pagina Sviluppatore indichi il dominio del tuo sito, la chiave pubblica funziona solo da https://tuosito.it e https://www.tuosito.it. Senza dominio funziona da qualsiasi sito.
Indirizzo dell'API e header delle chiamate dal server
https://api.fiscojet.com

Authorization: Bearer fj_live_sk_…
Content-Type: application/json

Con il form hosted

Il form di FiscoJet si mostra nella tua pagina, prima del pagamento. Il cliente vede il riepilogo dell'ordine e scrive i dati per la fattura.

  1. Il tuo server chiama POST /checkout/session con la chiave segreta e i prodotti. Riceve session (fj_cs_…) e ref (fj_ref_…).
  2. Il tuo server crea il PaymentIntent con metadata.fj_ref uguale a ref e passa alla pagina solo la sessione e il client_secret.
  3. La pagina monta il form con la chiave pubblica e checkoutSession.
  4. Quando arriva onSuccess i dati sono salvati e puoi abilitare il pagamento.

Sul server: sessione e PaymentIntent

Il tuo server · Node.js con Express
import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

app.post('/api/checkout', async (req, res) => {
  // 1. Sessione FiscoJet: i prodotti li decide il tuo server
  const fj = await fetch('https://api.fiscojet.com/checkout/session', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + process.env.FISCOJET_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      products: [
        { nome: 'Corso base', prezzo_lordo: 122.00, aliquota_iva: 22, qty: 1 }
      ]
    })
  }).then((r) => r.json());
  if (fj.error) return res.status(400).json({ error: fj.message });

  // 2. PaymentIntent con il ref della sessione nei metadata
  const paymentIntent = await stripe.paymentIntents.create({
    amount: Math.round(fj.data.totale * 100),
    currency: 'eur',
    metadata: { fj_ref: fj.data.ref }
  });

  // 3. Alla pagina servono solo questi due valori
  res.json({
    checkoutSession: fj.data.session,
    clientSecret: paymentIntent.client_secret
  });
});
Risposta di POST /checkout/session · 201
{
  "error": false,
  "success": true,
  "data": {
    "session": "fj_cs_…",
    "ref": "fj_ref_…",
    "expires_at": "2026-10-26T09:30:00.000Z",
    "items": [
      { "nome": "Corso base", "qty": 1, "prezzo_lordo": 122, "aliquota_iva": 22 }
    ],
    "totale": 122
  }
}

Nella pagina: il form

La tua pagina · HTML
<div id="fiscojet-form"></div>

<script src="https://www.fiscojet.com/embed/v1/fiscojet.js"></script>
<script type="module">
  const { checkoutSession, clientSecret } = await fetch('/api/checkout', {
    method: 'POST'
  }).then((r) => r.json());

  const form = FiscoJet.mount('#fiscojet-form', {
    publishableKey: 'fj_pk_live_…',
    checkoutSession,
    onSuccess: ({ ref, billing }) => {
      // Dati di fatturazione salvati: ora abilita il pagamento
      // (per esempio il Payment Element di Stripe con clientSecret)
    },
    onError: (error) => {
      console.error(error.code, error.message, error.messages);
    }
  });
</script>

Abilita il pagamento solo dopo onSuccess. Finché il cliente non invia il form, FiscoJet non emette la fattura, anche se il pagamento arriva.

Prima di pagare il cliente può correggere i dati e inviare di nuovo il form.

  • Crea una sessione per ogni ordine. Se il cliente non invia i dati entro 24 ore la sessione scade e ne serve una nuova.
  • Il form usa l'aspetto che hai scelto nella pagina Form hosted della dashboard. L'opzione theme lo cambia voce per voce.
  • Se il tuo sito ha una Content Security Policy, aggiungi script-src https://www.fiscojet.com e connect-src https://api.fiscojet.com.

Componente React in arrivo. Il pacchetto @fiscojet/react non è ancora su npm: per ora usa lo script, anche in un'app React o Next.js.

Prodotti al volo

Valgono per POST /checkout e per POST /checkout/session.

Ogni riga di products può indicare un prodotto del tuo catalogo FiscoJet con uuid e qty. Puoi anche descriverlo nella richiesta, senza crearlo prima nella dashboard.

Esempio di products
products: [
  // Dal tuo catalogo FiscoJet
  { uuid: 'prod_e0dd538f1d51', qty: 1 },

  // Al volo: prezzo IVA inclusa (oppure prezzo_netto)
  {
    nome: 'Corso base',
    prezzo_lordo: 122.00,
    aliquota_iva: 22,
    qty: 1,
    codice: 'CORSO-01'
  }
]
Campi di una riga al volo
CampoRegola
nomeObbligatorio, fino a 255 caratteri.
prezzo_lordo o prezzo_nettoUno dei due, maggiore di 0. Il lordo è IVA inclusa.
aliquota_ivaDa 0 a 100. Se manca vale 22.
qtyMaggiore di 0.
codiceFacoltativo, fino a 100 caratteri.
descrizioneFacoltativa, fino a 1000 caratteri.

Se nel catalogo c'è già un prodotto attivo con lo stesso nome, prezzo lordo, aliquota e codice, FiscoJet usa quello. Altrimenti ne crea uno nuovo. I prodotti che esistono già non vengono mai modificati. Con prodotti al volo puoi mandare al massimo 50 righe.

Opzioni del form

Le passi a FiscoJet.mount(selettore, opzioni).

Opzioni di FiscoJet.mount
OpzioneTipoObbligatoriaCosa fa
publishableKeystringSìLa chiave pubblica fj_pk_live_….
checkoutSessionstringSìIl token fj_cs_… creato dal tuo server con POST /checkout/session.
onSuccess({ ref, billing }) => voidSìI dati di fatturazione sono salvati. ref è lo stesso fj_ref_… che hai messo nel PaymentIntent.
onError(error) => voidNoErrori di rete, di chiave, di dominio, di sessione o di validazione. error.code dice quale; con gli errori di validazione error.messages elenca i problemi.
onReady() => voidNoIl form è caricato e pronto.
showSummarybooleanNoCon false nasconde il riepilogo dell'ordine. Se non lo indichi, il riepilogo si vede.
prefilledDataPartial<Billing>NoValori iniziali dei campi, per esempio { tipo: "azienda", nome: "Rossi S.r.l." }.
hideFieldsstring[]NoCampi da nascondere. Puoi nascondere solo tipo, provincia, nazione ed email.
submitLabelstringNoTesto del pulsante di invio. Se non lo indichi è «Conferma dati di fatturazione».
theme{ primaryColor?, fontFamily?, borderRadius?, size?, mode? }NoCambia, voce per voce, l'aspetto scelto nella pagina Form hosted della dashboard. size vale compact, standard o large; mode vale light o dark.
apiUrlstringNoIndirizzo dell'API. Se non lo indichi è https://api.fiscojet.com.

I campi di Billing sono tipo (privato o azienda), nome, cf, piva, sdi, pec, indirizzo, citta, cap, provincia, nazione ed email.

Metodi

FiscoJet.mount restituisce un oggetto con questi metodi:

Metodi del form montato
MetodoCosa fa
update({ checkoutSession, prefilledData })Cambia la sessione o i valori precompilati senza rimontare il form.
submit()Invia il form come il suo pulsante. Restituisce una Promise con { ref, billing } e la rifiuta se i dati non sono validi.
unmount()Toglie il form dalla pagina.

I valori di error.code, con il loro significato, sono nel riferimento API.

Dopo il pagamento

Uguale per le API e per il form hosted.

Ogni minuto FiscoJet cerca su Stripe i PaymentIntent riusciti che hanno nei metadata un fj_ref in attesa. Quando ne trova uno, la fattura segue le tue Regole: parte subito, parte dopo il ritardo che hai scelto, oppure resta in bozza finché non la approvi. Se il pagamento è stato rimborsato prima, la fattura non viene emessa.

La fattura ha una sola riga. La descrizione mette insieme i nomi dei prodotti, per esempio Corso base x2, Manuale. Se il cliente ha usato uno sconto Stripe, l'importo è quello incassato e la descrizione riporta lo sconto.

FiscoJet non manda webhook al tuo server. Per sapere a che punto è un ordine chiama GET /checkout/:uuid con il fj_ref. Il campo status vale:

Stati di un riferimento
statusSignificato
awaiting_billingSessione del form hosted creata. Il cliente non ha ancora inviato i dati di fatturazione.
pendingI dati di fatturazione ci sono. FiscoJet aspetta il pagamento riuscito su Stripe.
scheduledPagamento trovato. La fattura parte all'orario che deriva dalle tue Regole.
invoicedFattura creata.
cancelledIl pagamento è stato rimborsato prima della fattura. Nessuna fattura.
Stato di un riferimento · cURL
curl https://api.fiscojet.com/checkout/fj_ref_4a3b2c1d9e8f7a6b \
  -H "Authorization: Bearer $FISCOJET_SECRET_KEY"