API
Il tuo checkout chiede già i dati?
Mandali a FiscoJet dal tuo server con POST /checkout, senza il form.
Integrazioni · Form hosted
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.
API
Mandali a FiscoJet dal tuo server con POST /checkout, senza il form.
WordPress e WooCommerce
Il plugin fa tutto senza codice, con ogni metodo di pagamento.
Le generi nella pagina Sviluppatore della dashboard.
| Chiave | Formato | Dove si usa |
|---|---|---|
| Segreta | fj_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. |
| Pubblica | fj_pk_live_… | Nella pagina, nell'opzione publishableKey del form hosted. Può stare nel codice che arriva al browser. |
https://tuosito.it e https://www.tuosito.it. Senza dominio funziona da qualsiasi sito.https://api.fiscojet.com
Authorization: Bearer fj_live_sk_…
Content-Type: application/jsonIl 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.
POST /checkout/session con la chiave segreta e i prodotti. Riceve session (fj_cs_…) e ref (fj_ref_…).metadata.fj_ref uguale a ref e passa alla pagina solo la sessione e il client_secret.checkoutSession.onSuccess i dati sono salvati e puoi abilitare il pagamento.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
});
});{
"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
}
}<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.
theme lo cambia voce per voce.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.
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.
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'
}
]| Campo | Regola |
|---|---|
nome | Obbligatorio, fino a 255 caratteri. |
prezzo_lordo o prezzo_netto | Uno dei due, maggiore di 0. Il lordo è IVA inclusa. |
aliquota_iva | Da 0 a 100. Se manca vale 22. |
qty | Maggiore di 0. |
codice | Facoltativo, fino a 100 caratteri. |
descrizione | Facoltativa, 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.
Le passi a FiscoJet.mount(selettore, opzioni).
| Opzione | Tipo | Obbligatoria | Cosa fa |
|---|---|---|---|
publishableKey | string | Sì | La chiave pubblica fj_pk_live_…. |
checkoutSession | string | Sì | Il token fj_cs_… creato dal tuo server con POST /checkout/session. |
onSuccess | ({ ref, billing }) => void | Sì | I dati di fatturazione sono salvati. ref è lo stesso fj_ref_… che hai messo nel PaymentIntent. |
onError | (error) => void | No | Errori 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 | () => void | No | Il form è caricato e pronto. |
showSummary | boolean | No | Con false nasconde il riepilogo dell'ordine. Se non lo indichi, il riepilogo si vede. |
prefilledData | Partial<Billing> | No | Valori iniziali dei campi, per esempio { tipo: "azienda", nome: "Rossi S.r.l." }. |
hideFields | string[] | No | Campi da nascondere. Puoi nascondere solo tipo, provincia, nazione ed email. |
submitLabel | string | No | Testo del pulsante di invio. Se non lo indichi è «Conferma dati di fatturazione». |
theme | { primaryColor?, fontFamily?, borderRadius?, size?, mode? } | No | Cambia, voce per voce, l'aspetto scelto nella pagina Form hosted della dashboard. size vale compact, standard o large; mode vale light o dark. |
apiUrl | string | No | Indirizzo 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.
FiscoJet.mount restituisce un oggetto con questi metodi:
| Metodo | Cosa 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.
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:
| status | Significato |
|---|---|
awaiting_billing | Sessione del form hosted creata. Il cliente non ha ancora inviato i dati di fatturazione. |
pending | I dati di fatturazione ci sono. FiscoJet aspetta il pagamento riuscito su Stripe. |
scheduled | Pagamento trovato. La fattura parte all'orario che deriva dalle tue Regole. |
invoiced | Fattura creata. |
cancelled | Il pagamento è stato rimborsato prima della fattura. Nessuna fattura. |
curl https://api.fiscojet.com/checkout/fj_ref_4a3b2c1d9e8f7a6b \
-H "Authorization: Bearer $FISCOJET_SECRET_KEY"