Form hosted
Non vuoi costruire i campi di fatturazione?
Il form di FiscoJet li raccoglie e li controlla nella tua pagina, prima del pagamento.
Integrazioni · API
Per un checkout che costruisci tu e che raccoglie già i dati di fatturazione. Il tuo server li manda a FiscoJet con i prodotti e riceve un riferimento, il fj_ref, da mettere nei metadata del PaymentIntent Stripe. Qui trovi le chiamate e il codice da copiare.
Form hosted
Il form di FiscoJet li raccoglie e li controlla nella tua pagina, prima del pagamento.
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/jsonPer un checkout che costruisci tu e che raccoglie già i dati di fatturazione. I due passi sono entrambi sul server.
Chiama POST /checkout con i prodotti dell'ordine e i dati di fatturazione del cliente. La risposta contiene il fj_ref.
curl -X POST https://api.fiscojet.com/checkout \
-H "Authorization: Bearer $FISCOJET_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"products": [
{ "uuid": "prod_e0dd538f1d51", "qty": 1 }
],
"billing": {
"nome": "Rossi S.r.l.",
"piva": "12345678903",
"sdi": "ABC1234",
"indirizzo": "Via Roma 1",
"citta": "Milano",
"cap": "20121",
"provincia": "MI"
}
}'{
"error": false,
"success": true,
"data": {
"ref": "fj_ref_4a3b2c1d9e8f7a6b"
}
}I dati di fatturazione che servono:
nome e cf (codice fiscale);nome, piva e uno tra sdi (codice destinatario di 7 caratteri) e pec;indirizzo, citta e cap. Sono facoltativi provincia, nazione (se manca vale IT) ed email.FiscoJet capisce il tipo di cliente dai campi: con cf è un privato, con sdi o pec è un'azienda. Controlla anche formati e lunghezze del formato FatturaPA: per esempio l'indirizzo può avere al massimo 60 caratteri e la partita IVA deve avere la cifra di controllo giusta. L'elenco completo è nel riferimento API.
Crea il PaymentIntent sull'account Stripe collegato a FiscoJet e scrivi il riferimento nei metadata, con la chiave fj_ref esattamente così.
const paymentIntent = await stripe.paymentIntents.create({
amount: 12200,
currency: 'eur',
metadata: { fj_ref: 'fj_ref_4a3b2c1d9e8f7a6b' }
});Con Stripe Checkout i metadata della sessione non arrivano al PaymentIntent. Mettili in payment_intent_data:
const session = await stripe.checkout.sessions.create({
mode: 'payment',
line_items: [/* … */],
payment_intent_data: {
metadata: { fj_ref: 'fj_ref_4a3b2c1d9e8f7a6b' }
},
success_url: 'https://tuosito.it/grazie'
});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.
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"