Documentazione
Documentazione
Checkout espresso

1Introduzione

Express Checkout consente ai clienti di pagare direttamente da una pagina prodotto o carrello usando pulsanti wallet (ad esempio PayPal, Apple Pay o Google Pay), senza passare da un modulo di checkout separato.

2Passaggi di integrazione

L’integrazione prevede cinque passaggi logici:

Passaggio Parte Obbligatorio? Cosa significa per il merchant

1

Creare una sessione (POST /api/v2.0/express-checkout/session/create)

Sì

Creare una sessione per ogni tentativo di checkout e salvare gli identificativi restituiti.

2

Mostrare il widget wallet (iframe con sessionToken)

Sì

Mostrare l’interfaccia wallet al cliente.

3

Callback di spedizione (merchantShippingCallbackUrl)

Condizionale

Obbligatorio solo quando sono presenti articoli da spedire e le opzioni di spedizione devono essere calcolate dinamicamente.

4

Ritorno allo shop e creazione dell’ordine (GET merchantRedirectUrl)

Sì

Dopo l’approvazione del cliente, il flusso ritorna al tuo shop. Crea l’ordine in questo passaggio. Facoltativamente, recupera i dettagli della sessione (GET /api/v2.0/express-checkout/session) per validare o arricchire l’ordine con indirizzo finale, opzione di spedizione e totali.

5

Elaborare la sessione (POST /api/v2.0/express-checkout/session/process)

Sì

Chiama questo endpoint dopo il ritorno a merchantRedirectUrl, poi reindirizza il browser al redirectUrl restituito.

Termini di reindirizzamento:

  • merchantRedirectUrl è l’URL verso cui il flusso riporta il cliente nel tuo shop.

  • redirectUrl è restituito da /express-checkout/session/process ed è l’URL successivo verso cui il tuo shop deve reindirizzare il cliente.

3Flusso

Flusso di integrazione Express Checkout

3.11. Creare una sessione Express Checkout

  • Metodo: POST

  • URL: /api/v2.0/express-checkout/session/create

  • Autenticazione: token HMAC

Per l’elenco completo dei campi e delle relative descrizioni, consulta API Client. Modello della richiesta: IExpressCheckoutSession.ICreate. Modello della risposta: ExpressCheckoutSessionCreateResponse.

{
  "currency": "CHF",
  "authorizationEnvironment": "TEST",
  "merchantRedirectUrl": "https://your-shop.com/checkout/complete?sessionUuid=550e8400-e29b-41d4-a716-446655440000",
  "merchantShippingCallbackUrl": "https://your-shop.com/api/shipping-options?sessionUuid=550e8400-e29b-41d4-a716-446655440000",
  "lineItems": [
    {
      "uniqueId": "item-1",
      "sku": "SKU-001",
      "name": "Product Name",
      "type": "PRODUCT",
      "quantity": 1,
      "amountIncludingTax": 42.00,
      "shippingRequired": true,
      "currency": "CHF",
      "taxes": []
    }
  ]
}

In questo esempio, sessionUuid=550e8400-e29b-41d4-a716-446655440000 è un valore di correlazione generato dal merchant. Lo shop deve associare sessionUuid al sessionId restituito.

La risposta contiene:

  • sessionId — l’ID della sessione creata

  • sessionToken — token di sicurezza necessario per l’elaborazione

Note di implementazione:

  • Richiesto nella pratica: includere i dati che definiscono l’ordine (currency, lineItems, merchantRedirectUrl).

  • Richiesto: fornire authorizationEnvironment (TEST o PRODUCTION). Questo ambiente viene usato per determinare la disponibilità dei wallet e il comportamento di elaborazione della sessione.

  • Richiesto condizionatamente: fornire merchantShippingCallbackUrl quando il wallet deve richiedere opzioni di spedizione.

  • Richiesto per una correlazione affidabile: generare il proprio sessionUuid, aggiungerlo a merchantRedirectUrl e merchantShippingCallbackUrl, e salvare una mappatura sessionUuid <→ sessionId.

  • Conservare correttamente gli identificativi: persistere sessionId per l’elaborazione successiva. Tenere disponibile sessionToken fino al completamento del rendering del widget (la persistenza è facoltativa).

3.22. Mostrare il widget wallet

Incorpora l’iframe del wallet nella tua pagina usando l’URL del widget costruito con il sessionToken. Il widget gestisce la selezione dell’indirizzo, la visualizzazione delle opzioni di spedizione e l’approvazione del pagamento.

Esempio minimo di integrazione:

<script src="https://<scope-base-path>/assets/payment/express-checkout-handler.js"></script>

<div id="express-checkout-container"></div>

<script>
  window.ExpressCheckoutHandler.load('express-checkout-container', sessionToken, {
    maxColumns: 3,
    maxRows: 2,
    onError: function (error) {
      // Hook di errore personalizzato facoltativo.
      // error = { source, code, message }
      console.error('Errore wallet Express Checkout', error);
      alert(error.message);
    }
  });
</script>

Note di implementazione:

  • Richiesto: mostrare il widget con il containerId e il sessionToken ottenuti dalla creazione della sessione.

  • Facoltativo (maxColumns): controlla quanti pulsanti wallet vengono mostrati per riga. L’intervallo consentito va da 1 a 6. Se omesso, il widget usa il valore predefinito 2.

  • Facoltativo (maxRows): controlla il numero massimo di righe mostrate inizialmente. L’intervallo consentito va da 1 a 10. Se omesso, non viene applicato alcun limite di righe (vengono mostrate tutte le righe renderizzate).

  • Facoltativo (onError): callback invocato quando un’iframe wallet pubblica un errore di integrazione o runtime. Riceve un oggetto con source, code e message. Quando presente, questo callback diventa l’hook attivo per l’interfaccia di errore. Quando assente, rimane attiva la gestione degli errori predefinita del widget.

  • Logging operativo: gli errori delle iframe wallet vengono segnalati al backend e registrati per la diagnostica.

3.33. Elaborare il pagamento

Dopo l’approvazione del wallet e il ritorno al tuo merchantRedirectUrl, chiama l’endpoint di elaborazione per creare la transazione e autorizzare il pagamento.

  • Metodo: POST

  • URL: /api/v2.0/express-checkout/session/process

  • Autenticazione: token HMAC (come per tutte le chiamate REST API)

Per l’elenco completo dei campi e delle relative descrizioni, consulta API Client. Modello della richiesta: IExpressCheckoutSessionProcessRequest. Modello della risposta: ExpressCheckoutSessionProcessResponse.

{
  "sessionId": 123456,
  "merchantReference": "EC-MR-789",
  "successUrl": "https://your-shop.com/checkout/success",
  "failureUrl": "https://your-shop.com/checkout/failure"
}

Note di implementazione:

  • Richiesto: chiamare questo endpoint dopo l’approvazione e dopo che il cliente è stato reindirizzato dal portale al tuo shop.

  • Richiesto: fornire sessionId, una merchantReference idempotente e non vuota, oltre a successUrl e failureUrl.

  • Richiesto: reindirizzare il browser all’URL restituito nella risposta.

  • Importante: Express Checkout non usa il fallback dell’URL di risultato predefinito della payment page. La chiamata di elaborazione deve fornire URL di risultato merchant espliciti.

  • Facoltativo (consigliato): recuperare i dettagli della sessione prima dell’elaborazione per validare importo finale, indirizzo e opzione di spedizione selezionata.

  • Consigliato: considerare i webhook come fonte di verità per lo stato asincrono finale (AUTHORIZED / FAILED), mentre i redirect del browser guidano la navigazione del cliente.

La risposta contiene un URL di destinazione per il redirect. Reindirizza il cliente a quell’URL per continuare il 3DS (se necessario) e completare il flusso.

4Facoltativo: leggere i dettagli della sessione prima dell’elaborazione

Puoi recuperare la sessione Express Checkout approvata prima dell’elaborazione. Questo è utile per creare o validare l’ordine dello shop in base alle selezioni finali del cliente.

  • Metodo: GET

  • URL: /api/v2.0/express-checkout/session

  • Autenticazione: token HMAC

Per l’elenco completo dei campi e delle relative descrizioni, consulta API Client.

Uso tipico:

  1. Risolvi il tuo riferimento checkout interno nel sessionId salvato

  2. Recupera i dettagli della sessione

  3. Crea o valida l’ordine usando l’indirizzo restituito, l’opzione di spedizione selezionata e i totali

  4. Chiama /express-checkout/session/process

5Facoltativo: Shipping Options Provider API

Se i tuoi prodotti richiedono spedizione, devi implementare un endpoint di callback che wallee chiama per recuperare le opzioni di spedizione quando il cliente cambia indirizzo. L’URL di questo endpoint viene fornito per sessione tramite il campo merchantShippingCallbackUrl nella richiesta di creazione.

Il contratto di callback usa i seguenti tre modelli:

  • IExpressCheckoutShippingOptionRequest

    • Richiesti: countryCode, currency, language, expressCheckoutId, spaceId, requestId

    • Facoltativi: state, street, city, postalCode

  • IExpressCheckoutShippingOptionsResponse

    • shippingOptions: elenco di voci IExpressCheckoutShippingOption (restituire almeno una voce in caso di successo, un elenco vuoto in caso di errore). Per l’elenco completo dei campi e delle relative descrizioni, consulta IExpressCheckoutShippingOption.

    • error: null in caso di successo, oppure un oggetto IExpressCheckoutShippingOptionsClientError in caso di errore business

  • IExpressCheckoutShippingOptionsClientError

    • Campi: error (tipo breve), message (spiegazione leggibile dall’utente), timestamp (stringa temporale facoltativa)

5.1Specifiche dell’endpoint

  • Metodo: POST

  • URL: il tuo URL di callback configurato

  • Content-Type: application/json

5.2Richiesta

Wallee invia i seguenti campi in IExpressCheckoutShippingOptionRequest:

Campo Tipo Obbligatorio? Note

expressCheckoutId

Long

Sì

Identificativo della sessione Express Checkout.

spaceId

String

Sì

Identificativo dello space merchant.

requestId

String

Sì

ID di correlazione per il tracciamento.

countryCode

String

Sì

Codice paese (ISO-3166 alpha-2).

currency

String

Sì

Codice valuta (ISO-4217).

language

String

Sì

Codice lingua (ISO-639).

state

String

No

Codice stato o provincia.

street

String

No

Indirizzo stradale.

city

String

No

Nome della città.

postalCode

String

No

Codice postale o ZIP.

 
{
  "expressCheckoutId": 123456,
  "spaceId": "84",
  "requestId": "21a2f7fe-51b7-4ed5-9f88-1fb128292986",
  "countryCode": "CH",
  "currency": "CHF",
  "language": "it",
  "state": "ZH",
  "street": "Via Esempio 5",
  "city": "Winterthur",
  "postalCode": "8400"
}

5.3Risposta (restituita dal tuo shop)

Restituisci un oggetto JSON con opzioni di spedizione oppure un errore. L’endpoint del tuo shop deve restituire IExpressCheckoutShippingOptionsResponse a wallee come corpo della risposta HTTP.

Contratto della risposta:

  • Percorso di successo: restituire una o più shippingOptions e impostare error a null.

  • Percorso di errore: restituire un array shippingOptions vuoto e fornire un oggetto error popolato.

  • Non usare codici HTTP non-200 per errori business: mantenere HTTP 200 e comunicare gli errori nel corpo.

  • Usare codici HTTP non-200 solo per guasti tecnici: ad esempio formato payload non valido, errore di autenticazione o indisponibilità lato server.

5.3.1Campi delle opzioni di spedizione

Campo Tipo Obbligatorio? Note

id

String

Sì

Identificativo univoco dell’opzione di spedizione.

label

String

Sì

Nome visualizzato al cliente.

description

String

No

Testo descrittivo facoltativo.

amountIncludingTax

Decimal

Sì

Importo totale della spedizione incluse le imposte.

taxes

Array

No

Righe imposta con title e rate (percentuale). Può essere vuoto.

currency

String

Sì

Codice valuta ISO-4217. Deve corrispondere alla valuta della sessione.

5.3.2Campi di errore

Campo Tipo Obbligatorio? Note

error

String

Sì

Identificativo breve del tipo di errore (ad esempio INVALID_ADDRESS, SERVICE_UNAVAILABLE).

message

String

Sì

Descrizione dell’errore leggibile dall’utente.

timestamp

String

No

Timestamp del momento in cui si è verificato l’errore.

5.3.3Successo 

{
  "shippingOptions": [
    {
      "id": "standard",
      "label": "Spedizione standard",
      "description": "Consegna in 3-5 giorni lavorativi",
      "amountIncludingTax": 9.99,
      "taxes": [
        { "title": "IVA", "rate": 7.70 }
      ],
      "currency": "CHF"
    },
    {
      "id": "express",
      "label": "Spedizione express",
      "description": "Consegna in 1-2 giorni lavorativi",
      "amountIncludingTax": 19.99,
      "taxes": [
        { "title": "IVA", "rate": 7.70 }
      ],
      "currency": "CHF"
    }
  ],
  "error": null
}

5.3.4Errore 

{
  "shippingOptions": [],
  "error": {
    "error": "INVALID_ADDRESS",
    "message": "L'indirizzo di spedizione fornito non è valido per il calcolo dei costi di spedizione",
    "timestamp": "2025-10-10T12:00:00Z"
  }
}

6Wallet supportati

Wallet Stato Note

Bogus Pay

Disponibile

Solo per test e sviluppo.

PayPal

Disponibile

Pronto per la produzione in Express Checkout.

Apple Pay

Pianificato

—

Google Pay

Pianificato

—

7Test con Bogus Pay

Per i test, usa Bogus Pay.

Fornisce indirizzi fittizi, carte di test e flussi di approvazione (inclusa la simulazione 3DS).

Staging 2.207.2