Passa al contenuto principale

Klarna

Visualizza come Markdown

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

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).
  • Pagamenti ricorrenti e tokenizzazione: il metodo Klarna può essere tokenizzato per addebiti successivi, in modalità On-demand o Subscriptions (vedi Tokenizzazione e pagamenti ricorrenti).
  • Copertura internazionale: supporto attivo in oltre 20 paesi tra Europa, Stati Uniti, Canada, Australia e Nuova Zelanda (scopri di più).
  • 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).
  • Supporto multivaluta: compatibilità con le valute dei paesi supportati (scopri di più).
  • Riconciliazione semplificata: gestione dei pagamenti e reportistica tramite Fabrick Dashboard (scopri di più).
  • On-Site Messaging: su richiesta, attivazione del servizio nel Klarna Merchant Portal per personalizzare i messaggi Klarna sul sito dell'esercente (scopri di più).
  • Gestione dispute: le contestazioni vengono gestite tramite il Klarna Merchant Portal (scopri di più).

Prodotti Klarna disponibili​

Klarna offre tre categorie di pagamento:

CategoriaProdottoDescrizione
Pay NowBank TransferPagamento immediato tramite bonifico direttamente dal proprio online banking.
Pay by CardPagamento immediato tramite carta di credito o debito (disponibile nei mercati supportati).
Pay LaterPay in 30 daysIl cliente riceve il prodotto e completa il pagamento entro 30 giorni.
Pay in InstallmentsIl cliente suddivide l'importo in 3 o 4 rate senza interessi.
FinancingFinancingFinanziamento 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

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.

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

  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

MOTO

Per approfondire il funzionamento delle due modalità, consulta la sezione separazione tra autorizzazione e cattura.

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 transazioneGiorno della settimanaT+9 calendarialiGiorno della settimana T+9Accreditato quando?
10/03/2025Lunedì19/03/2025Mercoledì✅ 19/03/2025 (lavorativo)
15/03/2025Sabato24/03/2025Lunedì✅ 24/03/2025 (lavorativo)
25/04/2025Venerdì (festivo)04/05/2025Domenica⏩ 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ù).

Le tempistiche previste per la risoluzione variano in base alla tipologia di disputa:

Tempistiche di risoluzione delle dispute Klarna

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

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
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.
  • È possibile verificare l'attivazione del metodo di pagamento all'interno della Dashboard, al percorso Workspace → Negozi → [Seleziona negozio] → Configurazioni

Klarna

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 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 e rimuovi il campo paymentType dalla chiamata payment/create.

Pagina di pagamento con Klarna

Quando l'utente seleziona Klarna, viene reindirizzato al servizio per effettuare il login e completare il pagamento.

Pagina di pagamento con Klarna

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​

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/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"
            }
        ]
    }
}

In risposta viene restituito nel campo payload.userRedirect.href il link per il redirect del buyer verso Klarna.

Response

{
  "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.

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​

CampoMaxDescrizione
OrderDetails.BillingAddress.FirstName65Nome del cliente
OrderDetails.BillingAddress.Lastname65Cognome del cliente
OrderDetails.BillingAddress.Company75Ragione sociale
OrderDetails.BillingAddress.StreetName100Indirizzo (solo caratteri alfanumerici)
OrderDetails.BillingAddress.Email100Email del cliente
OrderDetails.BillingAddress.City50Città
OrderDetails.BillingAddress.ZipCode50CAP
OrderDetails.BillingAddress.State50Regione o stato
OrderDetails.BillingAddress.CountryCode2Codice paese ISO 3166 alpha-2 (es. IT, DE, GB)
OrderDetails.BillingAddress.PrimaryPhone100Telefono con prefisso internazionale

Shipping Address​

CampoMaxDescrizione
OrderDetails.ShippingAddress.FirstName65Nome destinatario
OrderDetails.ShippingAddress.Lastname65Cognome destinatario
OrderDetails.ShippingAddress.Company75Ragione sociale
OrderDetails.ShippingAddress.StreetName75Indirizzo (solo caratteri alfanumerici)
OrderDetails.ShippingAddress.Email100Email destinatario
OrderDetails.ShippingAddress.City50Città
OrderDetails.ShippingAddress.ZipCode20CAP
OrderDetails.ShippingAddress.State50Regione o stato
OrderDetails.ShippingAddress.CountryCode2Codice paese ISO 3166 alpha-2
OrderDetails.ShippingAddress.PrimaryPhone30Telefono con prefisso
OrderDetails.ShippingAddress.ShippingMethod—Metodo di spedizione: STORE, PICKUP_POINT, CARRIER

Customer Info​

CampoMaxDescrizione
OrderDetails.CustomerDetail.FirstName65Nome del cliente
OrderDetails.CustomerDetail.Lastname65Cognome del cliente

Product Details​

CampoMaxDescrizione
OrderDetails.ProductDetails.Description255Descrizione dell'articolo
OrderDetails.ProductDetails.SKU50Stock Keeping Unit
OrderDetails.ProductDetails.Name100Nome dell'articolo
OrderDetails.ProductDetails.UnitPrice12Prezzo unitario
OrderDetails.ProductDetails.Quantity3Quantità
OrderDetails.ProductDetails.ImageUrl2048URL immagine dell'articolo
OrderDetails.ProductDetails.ProductInfoUrl2048URL pagina prodotto
OrderDetails.ProductDetails.Type2Tipo di articolo (vedi tabella Product Type)

Klarna Product Type​

ValoreTipoNote
4DiscountValore negativo. Riduce il totale dell'ordine.
5Physical articleAcquisto fisico.
6Shipping feeSpese di spedizione.
8Digital articleAcquisto digitale (es. licenza).
9Gift CardPositivo: acquisto gift card. Negativo: riduzione totale ordine con gift card.
10Store creditValore negativo. Riduce il totale ordine con credito in-store.

Personalizzazione pagina di pagamento​

CampoMaxDescrizione
OrderDetails.PaymentPageDetails.LogoUrl2048Logo visualizzato sulla pagina
OrderDetails.ProviderPageDetails.BackgroundUrl2048Immagine di sfondo
OrderDetails.ProviderPageDetails.BackgroundWidth21Larghezza immagine di sfondo
OrderDetails.ProviderPageDetails.PageTitle255Titolo della pagina
OrderDetails.ProviderPageDetails.PrivacyUrl2048Link alla privacy policy
OrderDetails.ProviderPageDetails.TermsAndCondsUrl2048Link ai termini e condizioni

Dati di spedizione (Fulfillment)​

Utilizzati nella chiamata di cattura per trasmettere le informazioni di tracking a Klarna:

CampoMaxDescrizione
FullFillment.FullFillmentlst.FullfillmentDetail.TrackingCompany512Nome del corriere
FullFillment.FullFillmentlst.FullfillmentDetail.TrackingNumbers1024Numero di tracking
FullFillment.FullFillmentlst.FullfillmentDetail.TrackingUrls2048URL per il tracciamento
Tracking nell'app Klarna

Se il corriere è tra i Klarna Carrier Partner, 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:

SettoreEMD richiestiDettagli
Viaggiair_reservation_details, train_reservation_details, bus_reservation_details, ferry_reservation_details, car_rental_reservation_details, hotel_reservation_details, trip_reservation_detailsInformazioni su passeggeri e itinerario
Marketplacemarketplace_seller_info, marketplace_winner_infoInformazioni sul sub-venditore e categoria prodotti
BiglietteriaeventsInformazioni sull'evento
Info clientecustomer_account_info, payment_history_full, payment_history_simpleIdentificazione clienti registrati per migliorare l'esperienza
Ritiro in negozioother_delivery_addressIndirizzo 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.

{
    "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.

CampoTipoDescrizione
avg_order_valueintegerPrezzo del servizio in abbonamento, espresso in unità minori non negative della valuta di acquisto (es. 2999 corrisponde a 29,99 €)
avg_purchase_frequency_countintegerNumero di addebiti previsti per l'intervallo indicato in avg_purchase_frequency_interval
avg_purchase_frequency_intervalenumUnità di cadenza dell'abbonamento. Valori ammessi: day, week, month, year
min_order_valueintegerSe l'abbonamento è modificabile, importo dell'offerta più bassa, in unità minori non negative della valuta di acquisto
max_order_valueintegerSe 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.

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, 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

Request

POST /api/v1/payment/capture
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/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
                    }
                ]
            }
        ]
    }
}

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àDescrizioneQuando usarla
On-demandIl 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
SubscriptionsIl 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.

CampoObbligatorietàDescrizione
klarnaDescriptionObbligatorio — attiva la tokenizzazioneDescrizione del billing agreement associata alla tokenizzazione
transDetails.recurringTransaction.frequencyCondizionale — presente solo in modalità SubscriptionsNumero di giorni del ciclo di addebito ricorrente
Condizioni di attivazione​
ComportamentoCampoCondizione
Pagamento standard, nessuna tokenizzazioneklarnaDescription❌ assente
Tokenizzazione On-demandklarnaDescription✅ 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).

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/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}]}"
    }
}

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

GET /api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

Response

{
    "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

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).

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/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

{
    "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

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
{
    "shopLogin": "GESPAY12345",
    "paymentType": "KLARNA",
    "paymentTypeDetails": {
        "klarna": {
            "token": "KLYI2BVZ4R35IKCT"
        }
    }
}

Response

{
    "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), 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

Klarna