--- title: "Klarna" description: "Klarna è una soluzione di pagamento che permette ai clienti di pagare subito, a rate o in differita. In questa guida scoprirai come attivarlo, configurarlo su Fabrick Payment Orchestra e integrarlo correttamente nel tuo e-commerce." url: "https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/klarna/" language: "it" --- # Klarna ## Perché scegliere Klarna Klarna è una **soluzione di pagamento svedese** che permette agli esercenti di offrire ai propri clienti la possibilità di pagare subito, in differita o a rate, attraverso un checkout rapido e riconoscibile. Il vantaggio per l'esercente è immediato: **l'intero importo della transazione viene incassato subito**, indipendentemente dalla modalità di pagamento scelta dal cliente. > **Approfondimento** > > Per ulteriori informazioni consulta la [documentazione ufficiale Klarna](https://docs.klarna.com/) --- ## Servizi e funzionalità disponibili tramite integrazione Fabrick L'integrazione di Klarna con Fabrick Payment Orchestra mette a disposizione un ecosistema completo di funzionalità: - **Tre modalità di pagamento**: Pay Now (pagamento immediato), Pay Later (differito fino a 30 giorni o in 3-4 rate senza interessi), Financing (finanziamento da 6 a 36 mesi). - **Incasso immediato per l'esercente**: l'intero importo della transazione viene accreditato all'esercente nei tempi stabiliti, indipendentemente dalla modalità di pagamento scelta dal cliente. - **Gestione del rischio**: Klarna si assume il rischio di credito (mancato pagamento del consumatore) e di frode sulle transazioni approvate, nei limiti previsti dalle policy Klarna. Restano a carico dell'esercente le contestazioni relative alla fornitura di beni e servizi (vedi [Gestione delle dispute](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/klarna/#gestione-delle-dispute)). - **Pagamenti ricorrenti e tokenizzazione**: il metodo Klarna può essere tokenizzato per addebiti successivi, in modalità *On-demand* o *Subscriptions* (vedi [Tokenizzazione e pagamenti ricorrenti](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/klarna/#tokenizzazione-e-pagamenti-ricorrenti)). - **Copertura internazionale**: supporto attivo in oltre 20 paesi tra Europa, Stati Uniti, Canada, Australia e Nuova Zelanda ([scopri di più](https://docs.klarna.com/payments/web-payments/additional-resources/markets-and-regional-groupings/)). - **Gestione avanzata delle transazioni**: supporto a catture e storni parziali o multipli. - **Separazione/contestualità tra autorizzazione e conferma finanziaria**: la cattura può essere contestuale all'autorizzazione oppure disposta in un momento successivo (vedi [Separazione tra autorizzazione e cattura](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/klarna/#separazione-tra-autorizzazione-e-cattura)). - **Supporto multivaluta**: compatibilità con le valute dei paesi supportati ([scopri di più](https://docs.klarna.com/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/)). - **Riconciliazione semplificata**: gestione dei pagamenti e reportistica tramite Fabrick Dashboard ([scopri di più](https://www.fabrick.com/it-it/assistenza/fabrick-dashboard/)). - **On-Site Messaging**: su richiesta, attivazione del servizio nel Klarna Merchant Portal per personalizzare i messaggi Klarna sul sito dell'esercente ([scopri di più](https://docs.klarna.com/conversion-boosters/on-site-messaging/before-you-start/)). - **Gestione dispute**: le contestazioni vengono gestite tramite il Klarna Merchant Portal ([scopri di più](https://docs.klarna.com/acquirer/klarna/after-payments/disputes/disputes-management-v1-v2/dispute-management-overview/)). --- ### Prodotti Klarna disponibili Klarna offre tre categorie di pagamento: | Categoria | Prodotto | Descrizione | | ------------- | ------------------- | ------------------------------------------------------------------------------------------- | | **Pay Now** | Bank Transfer | Pagamento immediato tramite bonifico direttamente dal proprio online banking. | | | Pay by Card | Pagamento immediato tramite carta di credito o debito (disponibile nei mercati supportati). | | **Pay Later** | Pay in 30 days | Il cliente riceve il prodotto e completa il pagamento entro 30 giorni. | | | Pay in Installments | Il cliente suddivide l'importo in 3 o 4 rate senza interessi. | | **Financing** | Financing | Finanziamento a medio-lungo termine da 6 a 36 mesi per acquisti di importo elevato. | > **Incasso per l'esercente** > > A prescindere dalla modalità scelta dal cliente, **l'esercente riceve subito l'intero importo della transazione**. --- ### Copertura geografica e disponibilità prodotti Klarna è attiva in oltre 20 paesi tra Europa, Stati Uniti, Canada, Australia e Nuova Zelanda. Di seguito la mappatura della disponibilità dei prodotti Klarna per paese, valuta e modalità di pagamento. ![Copertura geografica e disponibilità prodotti Klarna](https://docs.fabrick.com/assets/images/fulltabellaklarna-1-d26842205ef660f585084b71bf7fe82d.png) > **Disponibilità effettiva** > > La tabella fornisce una panoramica orientativa. La disponibilità effettiva può variare in base alle policy di Klarna, al profilo dell'utente e al contesto locale. Per il dettaglio aggiornato consulta la [documentazione ufficiale Klarna](https://docs.klarna.com/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/). --- ### Esperienza di pagamento per l'acquirente Durante il processo di pagamento l'acquirente inserisce il numero di telefono e/o l'indirizzo e-mail associati al proprio account Klarna. Il sistema riconosce automaticamente l'utente, evitando l'inserimento di ulteriori dati. Dopo l'accesso, Klarna guida l'utente attraverso il checkout, dove può selezionare la modalità di pagamento preferita tra **Pay Now**, **Pay Later** e **Financing**. La disponibilità delle opzioni dipende da diversi fattori: - Profilo dell'utente - Paese di residenza - Importo dell'acquisto - Policy di Klarna --- ### Separazione tra autorizzazione e cattura Per impostare o modificare la modalità di gestione delle transazioni del metodo di pagamento: 1. Accedi alla Dashboard e vai su **Impostazioni → Accedi alle configurazioni** ![Accesso alle configurazioni dalla Dashboard](https://docs.fabrick.com/assets/images/dashboard-access-configurations-f4782eb17db7b8fb6f23649ba8e3e5d7.png) 2. Una volta reindirizzato sul backoffice, vai su **Configurazioni → Ambiente** e clicca su **MOTO**: si apre un pannello laterale con l'elenco dei metodi di pagamento attivi 3. Individua il metodo di pagamento e seleziona la modalità desiderata tra **Contestuale** e **Separata** ![Configurazione MOTO per Klarna](https://docs.fabrick.com/assets/images/klarna-moto-9ca726eff8c04dd1d577f3bf9f411547.png) > **MOTO** > > Per approfondire il funzionamento delle due modalità, consulta la sezione [separazione tra autorizzazione e cattura](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/introduction/getting-started/#moto). --- ### Tempistiche di accredito L'accredito delle transazioni Klarna è gestito da **Fabrick** come **Payment Facilitator**. Le tempistiche dipendono dal contratto di adesione al servizio Payment Facilitator sottoscritto tra l'esercente e Fabrick. In caso di **accredito giornaliero**, il pagamento viene accreditato a **T+9** rispetto alla data di movimentazione della transazione (dove T è il giorno della cattura). | Data transazione | Giorno della settimana | T+9 calendariali | Giorno della settimana T+9 | Accreditato quando? | | ---------------- | ---------------------- | ---------------- | -------------------------- | ------------------------- | | 10/03/2025 | Lunedì | 19/03/2025 | Mercoledì | ✅ 19/03/2025 (lavorativo) | | 15/03/2025 | Sabato | 24/03/2025 | Lunedì | ✅ 24/03/2025 (lavorativo) | | 25/04/2025 | Venerdì (festivo) | 04/05/2025 | Domenica | ⏩ 05/05/2025 (lunedì) | > **Giorni non lavorativi** > > Se la data di accredito coincide con un giorno non lavorativo (**festivo o fine settimana**), l'accredito viene posticipato al **primo giorno lavorativo successivo**. Questa logica si applica a tutte le modalità di pagamento Klarna (Pay Now, Pay Later, Financing): l'esercente riceve l'accredito nei tempi indicati indipendentemente dalla modalità scelta dal cliente. --- ### Gestione delle dispute La policy di Klarna prevede che l'esercente, in qualità di fornitore di beni e/o servizi, sia responsabile della risoluzione delle dispute sollevate dal cliente. La gestione avviene tramite il **Klarna Merchant Portal** ([scopri di più](https://docs.klarna.com/acquirer/klarna/after-payments/disputes/disputes-management-v1-v2/disputes-app-in-merchant-portal/)). Le tempistiche previste per la risoluzione variano in base alla tipologia di disputa: > **Calcolo della data di escalation** > > Le tempistiche decorrono dalla data di restituzione fornita a Klarna dal cliente. Se la data di restituzione è inferiore a 21 giorni, la data di escalation viene automaticamente posticipata di 21 giorni rispetto alla data di restituzione. Se una disputa non viene risolta entro le tempistiche previste, il servizio clienti di Klarna interviene per permettere alle parti di raggiungere un accordo. Tale intervento può comportare una **commissione addizionale** a carico dell'esercente, addebitata retroattivamente nel caso in cui l'esito indichi il merchant come responsabile. Nessun costo viene addebitato all'esercente quando il cliente viene ritenuto colpevole, non fornisce le informazioni richieste da Klarna, oppure cancella la controversia di propria iniziativa. > **Approfondimento** > > Per maggiori informazioni sulle dispute: [Klarna Merchant Disputes](https://docs.klarna.com/acquirer/klarna/after-payments/disputes/disputes-management-v1-v2/dispute-management-overview/) --- ## Klarna su Fabrick Payment Orchestra: attivazione e modalità di integrazione ### Richiesta di attivazione Per iniziare ad accettare pagamenti con Klarna, è necessario aderire alle condizioni dedicate riservate da Fabrick ai propri clienti, firmando il contratto che abilita Fabrick a operare come **Payment Facilitator**. Puoi richiedere l'attivazione di Klarna tramite Fabrick: - Contattando il tuo referente commerciale - Contattando l'assistenza al seguente [link](https://landing.fabrick.com/fabrick-dashboard-support) > **Indirizzo email dell'amministratore** > > In fase di attivazione è necessario comunicare a Fabrick **l'indirizzo email dell'amministratore che verrà utilizzato per la registrazione al Klarna Merchant Portal**. Una volta completate le procedure contrattuali e tecniche necessarie: - Klarna invia all'indirizzo email comunicato **un messaggio con le istruzioni per accedere al [Klarna Merchant Portal](https://portal.klarna.com/)**. - È possibile verificare l'attivazione del metodo di pagamento all'interno della Dashboard, al percorso **Workspace → Negozi → \[Seleziona negozio] → Configurazioni** ![Klarna](https://docs.fabrick.com/assets/images/kln-attivazione-ae44f2e9d97926a9db451cdc003d6cb5.png) > **Attivazione completata** > > Da questo momento, il tuo e-commerce è pronto per accettare pagamenti Klarna tramite Fabrick Payment Orchestra. ### Tipologie di integrazione Fabrick offre due modalità di integrazione per utilizzare Klarna: - **Integrazione hosted** ### Integrazioni supportate ✓ — Checkout Page ✓ — Pay By Link ✓ — Web Component ✓ — Lightbox Klarna viene mostrato direttamente nella pagina di pagamento Fabrick. Fabrick gestisce autonomamente la visualizzazione del metodo e l'intera fase di processamento ma a differenza di altri metodi di pagamento è richiesto di inviare i dati obbligatori. - **Integrazione tramite API** ### Integrazioni supportate ✓ — API Only In questa modalità il redirect verso Klarna viene gestito direttamente tramite API. È necessario inizializzare la transazione tramite `payment/create`, inviare i dati obbligatori e gestire il redirect del buyer. > **Campi obbligatori** > > Per richiedere il pagamento con Klarna è necessario valorizzare gli oggetti **Billing Address**, in particolare il campo `CountryCode`, e **Product Details**, con i campi `Name`, `UnitPrice` e `Quantity`. > **Numero di telefono** > > Se il numero di telefono non viene inviato nella richiesta e l'acquirente inserisce dati errati sulla pagina Klarna, viene mostrata una pagina con esito negativo senza possibilità di reinserimento. Questo comportamento non è replicabile in sandbox. > **Testare Klarna in ambiente sandbox** > > Per integrare Klarna in sandbox sono necessari due passaggi preliminari: > > 1. Richiedere all'assistenza Fabrick le **credenziali sandbox** e l'abilitazione del metodo Klarna (onboarding su Payment Orchestra) > 2. Utilizzare i **dati cliente di esempio forniti da Klarna** per il mercato di riferimento > > Klarna non accetta dati personali reali in ambiente di test. Utilizza i [sample customer data](https://docs.klarna.com/acquirer/klarna/resources/developer-tools/sample-data/sample-customer-data/) per il mercato di riferimento: l'indirizzo email determina l'esito della transazione. > > Gli esempi in questa pagina usano i dati del flusso **approvato** per il mercato italiano. --- ## Integrazione hosted Per presentare Klarna sulla pagina di pagamento è necessario aggiungere nella chiamata `payment/create` i campi obbligatori richiesti dal metodo di pagamento. Quando l'utente seleziona Klarna, inserisce il numero di telefono o l'email associati al proprio account Klarna e completa il pagamento scegliendo tra le modalità disponibili (Pay Now, Pay Later, Financing). Per impostare la chiamata con l'integrazione hosted, vai alla sezione [creazione della transazione e redirect verso Klarna](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/klarna/#creazione-della-transazione-e-redirect-verso-klarna) e **rimuovi il campo `paymentType`** dalla chiamata `payment/create`. ![Pagina di pagamento con Klarna](https://docs.fabrick.com/assets/images/klarna-buyer-01-117e0174d85814c5b05482b6f68d952e.png) Quando l'utente seleziona Klarna, viene reindirizzato al servizio per effettuare il login e completare il pagamento. ![Pagina di pagamento con Klarna](https://docs.fabrick.com/assets/images/klarna-buyer-02-0a5f822733d5a91ad9edcbeb677d857f.png) --- ## Integrazione tramite API Per richiedere il pagamento con Klarna utilizzando l'integrazione tramite API, è necessario inizializzare la transazione tramite `payment/create` utilizzando il tag **`KLARNA`** nel campo `paymentType`, includere i dati obbligatori e gestire il redirect del buyer verso il metodo di pagamento. ### Creazione della transazione e redirect verso Klarna **Campi obbligatori** **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "294.90", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["KLARNA"], // Per integrazione hosted eliminare questa riga "paymentChannel": { "channelType": ["LINK"] }, "OrderDetails": { "BillingAddress": { "CountryCode": "IT" }, "ProductDetails": [ { "Name": "Zaino Explorer", "UnitPrice": "180.00", "Quantity": "1" }, { "Name": "Runner Pro", "UnitPrice": "89.90", "Quantity": "1" }, { "Name": "Spedizione", "UnitPrice": "25", "Quantity": "1" } ] } } ``` **Chiamata completa** **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "541.49", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["KLARNA"], // Per integrazione hosted eliminare questa riga "paymentChannel": { "channelType": ["LINK"] }, "OrderDetails": { "PaymentPageDetails": { "LogoUrl": "https://www.example.com/logo.svg" }, "ProviderPageDetails": { "BackgroundUrl": "https://www.example.com/bg.svg", "BackgroundWidth": "100", "PageTitle": "Completa il pagamento", "PrivacyUrl": "https://www.example.com/privacy", "TermsAndCondsUrl": "https://www.example.com/terms" }, "CustomerDetail": { "FirstName": "Test", "Lastname": "Person-it" }, "BillingAddress": { "FirstName": "Test", "Lastname": "Person-it", "Company": "Example S.r.l.", "StreetName": "Via Corradino Sella 10", "City": "Biella", "ZipCode": "13900", "State": "Piemonte", "CountryCode": "IT", "Email": "customer+it@klarna.com", "PrimaryPhone": "+393339741231" }, "ShippingAddress": { "FirstName": "Test", "Lastname": "Person-it", "Company": "Example S.r.l.", "StreetName": "Via Corradino Sella 10", "City": "Biella", "ZipCode": "13900", "State": "Piemonte", "CountryCode": "IT", "Email": "customer+it@klarna.com", "PrimaryPhone": "+393339741231", "ShippingMethod": "CARRIER" }, "ProductDetails": [ { "Description": "Zaino da viaggio", "SKU": "512678_M", "Name": "Zaino Explorer", "UnitPrice": "180.00", "Quantity": "1", "ImageUrl": "https://www.example.com/images/zaino-explorer.jpg", "ProductInfoUrl": "https://www.example.com/products/zaino-explorer", "Type": 5 }, { "Description": "Scarpe sportive", "SKU": "789456_42", "Name": "Runner Pro", "UnitPrice": "89.90", "Quantity": "1", "ImageUrl": "https://www.example.com/images/runner-pro.jpg", "ProductInfoUrl": "https://www.example.com/products/runner-pro", "Type": 5 }, { "Description": "Orologio smart", "SKU": "998877_BLK", "Name": "SmartWatch X", "UnitPrice": "246.59", "Quantity": "1", "ImageUrl": "https://www.example.com/images/smartwatch-x.jpg", "ProductInfoUrl": "https://www.example.com/products/smartwatch-x", "Type": 5 }, { "Name": "Spedizione", "UnitPrice": "25", "Quantity": "1", "Type": 6 } ], "ProviderData": "{\"customer_account_info\":[{\"unique_account_identifier\":\"customer+it@klarna.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\",\"loyalty_level\":\"intermediate\",\"customer_email\":\"customer+it@klarna.com\",\"customer_phone\":\"+393339741231\"}]}" } } ``` In risposta viene restituito nel campo `payload.userRedirect.href` il link per il redirect del buyer verso Klarna. **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "f0419188-8a78-4918-913c-a491e4e78084", "paymentID": "1881129911957", "userRedirect": { "href": "https://sandbox-web.axerve.com/orchestra/checkout/a/f991s1ba01d24eacaa3fac4b2145262a/b/36ab092425ff34515f7430e38babb28b84f16a31d63102b829072a1366c13580ae128e86-d779-4d98-88a2-0c035bcbd42eiAQ8ZaRT3IFyanLLjcIxtsuc3DTwycBdj5FD7FjuhlKm-mNnpirMdm9p3O8bhycmHVVPz6QOyo811UzHG3csjOSlH2KbF2EiUIxEwWFPAvk9TdUDrgWtyKLJYWayfzbZlP4iULt9eHTvhJEhK21sS8Smd0hX" }, "qrCode": null } } ``` > **UnitPrice e Quantity** > > Il totale degli articoli, calcolato moltiplicando `UnitPrice` per `Quantity` di ciascuna riga, deve corrispondere all'importo specificato nel campo `amount`. > **Pulsante Klarna** > > Il link restituito può essere utilizzato sotto un pulsante *Paga con Klarna*, rispettando le [linee guida grafiche Klarna](https://docs.klarna.com/acquirer/klarna/web-payments/additional-resources/checkout-styling/). --- ## Campi da inviare nella chiamata verso Klarna I parametri da includere nella `payment/create` sono riportati nelle tabelle seguenti. I campi obbligatori sono riportati in **grassetto**. ### Billing Address | Campo | Max | Descrizione | | --------------------------------------------- | --- | ---------------------------------------------- | | `OrderDetails.BillingAddress.FirstName` | 65 | Nome del cliente | | `OrderDetails.BillingAddress.Lastname` | 65 | Cognome del cliente | | `OrderDetails.BillingAddress.Company` | 75 | Ragione sociale | | `OrderDetails.BillingAddress.StreetName` | 100 | Indirizzo (solo caratteri alfanumerici) | | `OrderDetails.BillingAddress.Email` | 100 | Email del cliente | | `OrderDetails.BillingAddress.City` | 50 | Città | | `OrderDetails.BillingAddress.ZipCode` | 50 | CAP | | `OrderDetails.BillingAddress.State` | 50 | Regione o stato | | **`OrderDetails.BillingAddress.CountryCode`** | 2 | Codice paese ISO 3166 alpha-2 (es. IT, DE, GB) | | `OrderDetails.BillingAddress.PrimaryPhone` | 100 | Telefono con prefisso internazionale | ### Shipping Address | Campo | Max | Descrizione | | --------------------------------------------- | --- | -------------------------------------------------------- | | `OrderDetails.ShippingAddress.FirstName` | 65 | Nome destinatario | | `OrderDetails.ShippingAddress.Lastname` | 65 | Cognome destinatario | | `OrderDetails.ShippingAddress.Company` | 75 | Ragione sociale | | `OrderDetails.ShippingAddress.StreetName` | 75 | Indirizzo (solo caratteri alfanumerici) | | `OrderDetails.ShippingAddress.Email` | 100 | Email destinatario | | `OrderDetails.ShippingAddress.City` | 50 | Città | | `OrderDetails.ShippingAddress.ZipCode` | 20 | CAP | | `OrderDetails.ShippingAddress.State` | 50 | Regione o stato | | `OrderDetails.ShippingAddress.CountryCode` | 2 | Codice paese ISO 3166 alpha-2 | | `OrderDetails.ShippingAddress.PrimaryPhone` | 30 | Telefono con prefisso | | `OrderDetails.ShippingAddress.ShippingMethod` | — | Metodo di spedizione: `STORE`, `PICKUP_POINT`, `CARRIER` | ### Customer Info | Campo | Max | Descrizione | | --------------------------------------- | --- | ------------------- | | `OrderDetails.CustomerDetail.FirstName` | 65 | Nome del cliente | | `OrderDetails.CustomerDetail.Lastname` | 65 | Cognome del cliente | ### Product Details | Campo | Max | Descrizione | | -------------------------------------------- | ---- | -------------------------------------------- | | `OrderDetails.ProductDetails.Description` | 255 | Descrizione dell'articolo | | `OrderDetails.ProductDetails.SKU` | 50 | Stock Keeping Unit | | **`OrderDetails.ProductDetails.Name`** | 100 | Nome dell'articolo | | **`OrderDetails.ProductDetails.UnitPrice`** | 12 | Prezzo unitario | | **`OrderDetails.ProductDetails.Quantity`** | 3 | Quantità | | `OrderDetails.ProductDetails.ImageUrl` | 2048 | URL immagine dell'articolo | | `OrderDetails.ProductDetails.ProductInfoUrl` | 2048 | URL pagina prodotto | | `OrderDetails.ProductDetails.Type` | 2 | Tipo di articolo (vedi tabella Product Type) | ### Klarna Product Type | Valore | Tipo | Note | | ------ | ---------------- | ------------------------------------------------------------------------------ | | 4 | Discount | Valore negativo. Riduce il totale dell'ordine. | | 5 | Physical article | Acquisto fisico. | | 6 | Shipping fee | Spese di spedizione. | | 8 | Digital article | Acquisto digitale (es. licenza). | | 9 | Gift Card | Positivo: acquisto gift card. Negativo: riduzione totale ordine con gift card. | | 10 | Store credit | Valore negativo. Riduce il totale ordine con credito in-store. | ### Personalizzazione pagina di pagamento | Campo | Max | Descrizione | | --------------------------------------------------- | ---- | ------------------------------ | | `OrderDetails.PaymentPageDetails.LogoUrl` | 2048 | Logo visualizzato sulla pagina | | `OrderDetails.ProviderPageDetails.BackgroundUrl` | 2048 | Immagine di sfondo | | `OrderDetails.ProviderPageDetails.BackgroundWidth` | 21 | Larghezza immagine di sfondo | | `OrderDetails.ProviderPageDetails.PageTitle` | 255 | Titolo della pagina | | `OrderDetails.ProviderPageDetails.PrivacyUrl` | 2048 | Link alla privacy policy | | `OrderDetails.ProviderPageDetails.TermsAndCondsUrl` | 2048 | Link ai termini e condizioni | ### Dati di spedizione (Fulfillment) Utilizzati nella **chiamata di cattura** per trasmettere le informazioni di tracking a Klarna: | Campo | Max | Descrizione | | ----------------------------------------------------------------- | ---- | ----------------------- | | `FullFillment.FullFillmentlst.FullfillmentDetail.TrackingCompany` | 512 | Nome del corriere | | `FullFillment.FullFillmentlst.FullfillmentDetail.TrackingNumbers` | 1024 | Numero di tracking | | `FullFillment.FullFillmentlst.FullfillmentDetail.TrackingUrls` | 2048 | URL per il tracciamento | > **Tracking nell'app Klarna** > > Se il corriere è tra i [Klarna Carrier Partner](https://docs.klarna.com/order-management/delivery/klarna-carrier-partner-list/), il buyer potrà monitorare la spedizione direttamente dall'app Klarna. --- ### Extra Merchant Data (EMD) In base al settore merceologico, Klarna può richiedere informazioni aggiuntive (Extra Merchant Data) per effettuare una valutazione accurata del rischio e migliorare i tassi di conversione. Gli EMD sono **obbligatori** per i seguenti settori: | Settore | EMD richiesti | Dettagli | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | Viaggi | `air_reservation_details`, `train_reservation_details`, `bus_reservation_details`, `ferry_reservation_details`, `car_rental_reservation_details`, `hotel_reservation_details`, `trip_reservation_details` | Informazioni su passeggeri e itinerario | | Marketplace | `marketplace_seller_info`, `marketplace_winner_info` | Informazioni sul sub-venditore e categoria prodotti | | Biglietteria | `events` | Informazioni sull'evento | | Info cliente | `customer_account_info`, `payment_history_full`, `payment_history_simple` | Identificazione clienti registrati per migliorare l'esperienza | | Ritiro in negozio | `other_delivery_address` | Indirizzo del punto di ritiro per l'analisi del rischio | #### Come inviare gli EMD Gli EMD vanno inclusi nel campo `OrderDetails.ProviderData` della chiamata `payment/create`, valorizzato con i pacchetti dati previsti per il proprio settore merceologico. **in_store_payment** ```json { "OrderDetails": { "ProviderData": "{\"in_store_payment\":[{\"merchant_store_id\":\"LONDON12\",\"store_terminal_id\":\"AD12342D\",\"store_address\":{\"city\":\"London\",\"country\":\"GB\",\"postal_code\":\"W1B 1JA\",\"street_address\":\"New Burlington St 10\"}}]}" } } ``` **customer_account_info** ```json { "OrderDetails": { "ProviderData": "{\"customer_account_info\":[{\"unique_account_identifier\":\"customer@email.it\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]}" } } ``` **customer_tokens** ```json { "OrderDetails": { "ProviderData": "{\"customer_tokens\":[{\"avg_order_value\":5000,\"avg_purchase_frequency_count\":1,\"avg_purchase_frequency_interval\":\"month\",\"min_order_value\":500,\"max_order_value\":50000}]}" } } ``` #### Dettaglio campi per customer_tokens Il pacchetto `customer_tokens` descrive a Klarna le caratteristiche economiche dell'abbonamento associato al token. | Campo | Tipo | Descrizione | | --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `avg_order_value` | integer | Prezzo del servizio in abbonamento, espresso in unità minori non negative della valuta di acquisto (es. `2999` corrisponde a 29,99 €) | | `avg_purchase_frequency_count` | integer | Numero di addebiti previsti per l'intervallo indicato in `avg_purchase_frequency_interval` | | `avg_purchase_frequency_interval` | enum | Unità di cadenza dell'abbonamento. Valori ammessi: `day`, `week`, `month`, `year` | | `min_order_value` | integer | Se l'abbonamento è modificabile, importo dell'offerta più bassa, in unità minori non negative della valuta di acquisto | | `max_order_value` | integer | Se l'abbonamento è modificabile, importo dell'offerta più alta, in unità minori non negative della valuta di acquisto | > **Unità minori della valuta** > > Gli importi vanno espressi come interi nella sottounità della valuta: per l'euro corrispondono ai centesimi, quindi `1999` equivale a 19,99 €. > **Formato del campo** > > `ProviderData` accetta una **stringa JSON serializzata**, non un oggetto JSON annidato. Le virgolette interne devono quindi essere precedute dal carattere di escape `\`. > **Individuare il settore corretto** > > Per sapere quale pacchetto EMD si applica al tuo settore merceologico, contatta il tuo referente commerciale Fabrick. I dettagli sui campi di ciascun pacchetto sono disponibili su [Klarna Docs - Extra Merchant Data](https://docs.klarna.com/api/extra-merchant-data/). --- ## Funzionalità aggiuntive del metodo di pagamento ### Cattura e storno parziali della transazione Klarna supporta **catture parziali** e **storni parziali**. L'oggetto `ProductDetails` è facoltativo nelle operazioni di cattura e storno: se utilizzato, è necessario valorizzarlo con i singoli articoli coinvolti nell'operazione e con i relativi [campi obbligatori](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/klarna/#product-details), per consentire a Klarna di aggiornare correttamente l'ordine lato acquirente. È possibile procedere con un rimborso parziale o totale in due modi: - Direttamente dalla **Fabrick Dashboard** - Tramite chiamata API **`POST payment/capture`** e **`POST payment/refund`** **Cattura parziale della transazione** **Request** ```http POST /api/v1/payment/capture Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "currency": "EUR", "bankTransactionID": "614", // o "paymentID": "21421310038753" "amount": "269.90", "settlementID": "SID-1", "FullFillment": { "FullFillmentlst": [ { "TrackingCompany": "TNT", "TrackingNumbers": "TNT100", "TrackingUrls": "https://www.tnt.com/tnt100", "ProductDetails": [ { "Description": "Zaino da viaggio", "SKU": "512678_M", "Name": "Zaino Explorer", "UnitPrice": "180.00", "Quantity": "1", "ImageUrl": "https://www.example.com/images/zaino-explorer.jpg", "ProductInfoUrl": "https://www.example.com/products/zaino-explorer", "Type": 5 }, { "Description": "Scarpe sportive", "SKU": "789456_42", "Name": "Runner Pro", "UnitPrice": "89.90", "Quantity": "1", "ImageUrl": "https://www.example.com/images/runner-pro.jpg", "ProductInfoUrl": "https://www.example.com/products/runner-pro", "Type": 5 } ] } ] } } ``` **Storno parziale della transazione movimentata** **Request** ```http POST /api/v1/payment/refund Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "currency": "EUR", "bankTransactionID": "614", // o "paymentID": "21421310038753" "amount": "89.90", "settlementID": "SID-1", "orderDetails": { "ProductDetails": [ { "Description": "Scarpe sportive", "SKU": "789456_42", "Name": "Runner Pro", "UnitPrice": "89.90", "Quantity": "1", "ImageUrl": "https://www.example.com/images/runner-pro.jpg", "ProductInfoUrl": "https://www.example.com/products/runner-pro", "Type": 5 } ] } } ``` ### Tokenizzazione e pagamenti ricorrenti Payment Orchestra consente di **tokenizzare il metodo di pagamento Klarna** scelto dal buyer, per riutilizzarlo in pagamenti successivi senza che l'acquirente debba reinserire i propri dati di pagamento. Il token può essere utilizzato in due contesti: - **Con il buyer presente al checkout** (es. metodo salvato in un wallet), per velocizzare i pagamenti successivi senza richiedere una nuova interazione con la pagina Klarna. - **Senza il buyer presente**, per addebiti avviati direttamente dal merchant (es. rinnovo di un abbonamento). #### Modalità di tokenizzazione | Modalità | Descrizione | Quando usarla | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | **On-demand** | Il token viene creato senza un ciclo di addebito predefinito. Può essere utilizzato sia per addebiti decisi dal merchant senza cadenza fissa, sia per pagamenti in cui è il buyer stesso, presente al checkout, a selezionare il metodo salvato. | Wallet e checkout semplificato, riordini a discrezione del cliente, addebiti non pianificati avviati dal merchant | | **Subscriptions** | Il token viene creato con un ciclo di addebito ricorrente a cadenza fissa, espressa in giorni. | Abbonamenti e servizi in abbonamento con cadenza di rinnovo nota in anticipo | La modalità applicata dipende dai campi inviati nella richiesta di creazione del token. Al completamento della transazione è possibile ottenere il token da utilizzare per i pagamenti successivi. #### Attivazione della tokenizzazione e campi da inviare La tokenizzazione si attiva includendo il campo `klarnaDescription` nella chiamata `payment/create`. In assenza di questo campo, Payment Orchestra elabora un pagamento standard e non richiede la tokenizzazione del metodo di pagamento. Nella richiesta di tokenizzazione restano obbligatori i campi già richiesti per un pagamento Klarna, ad eccezione di `ProductDetails`, che non deve essere inviato. | Campo | Obbligatorietà | Descrizione | | --------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------- | | **`klarnaDescription`** | Obbligatorio — attiva la tokenizzazione | Descrizione del billing agreement associata alla tokenizzazione | | `transDetails.recurringTransaction.frequency` | Condizionale — presente solo in modalità Subscriptions | Numero di giorni del ciclo di addebito ricorrente | ##### Condizioni di attivazione | Comportamento | Campo | Condizione | | ----------------------------------------------------------------------------------------------- | --------------------------------------------- | ---------- | | Pagamento standard, nessuna tokenizzazione | `klarnaDescription` | ❌ assente | | Tokenizzazione **On-demand** | `klarnaDescription` | ✅ presente | | | `transDetails.recurringTransaction.frequency` | ❌ assente | | Tokenizzazione **Subscriptions**. `frequency` esprime il numero di giorni del ciclo ricorrente. | `klarnaDescription` | ✅ presente | | | `transDetails.recurringTransaction.frequency` | ✅ presente | #### Creazione del token Il token può essere generato **esclusivamente con una transazione di importo pari a `0`**: non è possibile richiederlo contestualmente ad un pagamento. La richiesta di tokenizzazione non addebita alcun importo al buyer. La chiamata segue lo stesso schema *request/response* di un pagamento Klarna standard, con queste differenze: - l'importo deve essere valorizzato a `0` - l'oggetto `ProductDetails` **non deve essere inviato** - è necessario aggiungere il campo `klarnaDescription`, per indicare al sistema che deve essere generato un token > **Modalità Subscriptions** > > Nelle richieste in modalità *Subscriptions* è **obbligatorio** valorizzare `OrderDetails.ProviderData` con il pacchetto `customer_tokens` (vedi [Campi del pacchetto customer_tokens](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/klarna/#dettaglio-campi-per-customer_tokens)). **Subscriptions** **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "0", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["KLARNA"], // Per integrazione hosted eliminare questa riga "paymentChannel": { "channelType": ["LINK"] }, "klarnaDescription": "Abbonamento mensile - Piano Plus", "transDetails": { "recurringTransaction": { "frequency": "90" } }, "OrderDetails": { "BillingAddress": { "CountryCode": "IT" }, "ProviderData": "{\"customer_tokens\":[{\"avg_order_value\":5000,\"avg_purchase_frequency_count\":1,\"avg_purchase_frequency_interval\":\"month\",\"min_order_value\":500,\"max_order_value\":50000}]}" } } ``` **On-demand** **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "0", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["KLARNA"], // Per integrazione hosted eliminare questa riga "paymentChannel": { "channelType": ["LINK"] }, "klarnaDescription": "Metodo di pagamento salvato - Wallet cliente", "OrderDetails": { "BillingAddress": { "CountryCode": "IT" } } } ``` #### Recupero del token Al completamento della transazione da parte del buyer, il sistema risponde con `transactionResult` valorizzato a `WAITING`. Recupera quindi il token generato tramite `GET /payment/detail`, nel campo `payload.token`, e salvalo per i pagamenti successivi. **Request** ```http GET /api/v1/payment/detail/{paymentID} Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionType": "detail", "transactionResult": "WAITING", "transactionState": "", "transactionErrorCode": "", "transactionErrorDescription": "", "bankTransactionID": "", "shopTransactionID": "", "shopTransactionID_2": "", "authorizationCode": "", "paymentID": "", "currency": "", "country": "", "company": "", "tdLevel": "", "threeDS": { "authenticationResult": null, "transDetails": null }, "events": null, "buyer": null, "risk": null, "customInfo": null, "alertCode": "", "alertDescription": "", "cvvPresent": "", "dcc": null, "maskedPAN": "", "paymentMethod": "", "productType": "", "token": "KLYI2BVZ4R35IKCT", "tokenExpiryMonth": "", "tokenExpiryYear": "", "tokenDetails": null, "fraudPrevention": null, "automaticOperation": null } } ``` > **Pagamento a rate** > > Solo per la modalità *Subscriptions*, se `transDetails.recurringTransaction.frequency` è valorizzato con un valore **maggiore o uguale a 90**, quindi con cadenza trimestrale o superiore, il buyer può scegliere la modalità di pagamento a rate direttamente sulla pagina Klarna. L'impostazione selezionata viene applicata anche a tutti i pagamenti successivi effettuati con quel token. > > ![Klarna](https://docs.fabrick.com/assets/images/klarna-4-e1cad994767e7dd8e6e492968eb44cb3.png) #### Utilizzo del token per pagamenti successivi I pagamenti effettuati con il token sono transazioni Klarna a tutti gli effetti: la richiesta `POST /payment/create` deve quindi includere i **campi obbligatori previsti dal metodo di pagamento**, come per qualsiasi altra transazione Klarna (vedi [Campi da inviare nella chiamata verso Klarna](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/klarna/#campi-da-inviare-nella-chiamata-verso-klarna)). **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "29.99", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "OrderDetails": { "BillingAddress": { "CountryCode": "IT" }, "ProductDetails": [ { "Name": "Abbonamento mensile - Piano Plus", "UnitPrice": "29.99", "Quantity": "1" } ] } } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "f0419188-8a78-4918-913c-a491e4e78084", "paymentID": "1881129911957", "userRedirect": null, "qrCode": null } } ``` Nella chiamata `POST /payment/submit` utilizza il token per processare il pagamento: - Header **`PaymentToken`**: valorizzare con il `paymentToken` ricevuto dallo step precedente - Body: aggiungi `paymentTypeDetails.klarna.token` valorizzato con il token Klarna salvato in precedenza **Request** ```http POST /api/v1/payment/submit Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it PaymentToken: f0419188-8a78-4918-913c-a491e4e78084 Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "paymentType": "KLARNA", "paymentTypeDetails": { "klarna": { "token": "KLYI2BVZ4R35IKCT" } } } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionType": "submit", "transactionResult": "OK", "transactionErrorCode": "0", "transactionErrorDescription": "Transaction correctly processed", "bankTransactionID": "4672", "shopTransactionID": "FBK_OrderID", "shopTransactionID_2": "", "authorizationCode": "KL3413", "paymentID": "1881129911957", "currency": "EUR", "country": "", "company": null, "tdLevel": "", "buyer": { "name": "", "email": "" }, "risk": { "riskResponseCode": "", "riskResponseDescription": "" }, "customInfo": {}, "alertCode": "", "alertDescription": "", "cvvPresent": "", "maskedPAN": "", "paymentMethod": "", "productType": "", "token": "", "tokenExpiryMonth": "", "tokenExpiryYear": "", "userRedirect": { "href": "https://sandbox.gestpay.net/pagam/AxerveThankYou.aspx" } } } ``` #### Cancellazione e interrogazione del token Le operazioni di **Cancel** e **Details** utilizzano gli stessi endpoint (vedi sezione [Tokenizzazione](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/)), campi e strutture di risposta già impiegati per gli altri metodi di pagamento tokenizzati su Payment Orchestra. Il comportamento lato Klarna non richiede parametri aggiuntivi. --- ## Assistenza **Fabrick** - **Status page**: [https://status.fabrick.com/](https://status.fabrick.com/) - **Support**: [https://landing.fabrick.com/fabrick-dashboard-support](https://landing.fabrick.com/fabrick-dashboard-support) **Klarna** - **Docs**: [https://docs.klarna.com/](https://docs.klarna.com/) - **Merchant Portal**: [https://portal.klarna.com/](https://portal.klarna.com/)