Documentazione
Documentazione
Lightbox

1Introduzione

Per creare un pagamento tramite la piattaforma potete scegliere tra la payment page integration, in cui il cliente viene reindirizzato alla nostra pagina di pagamento, la iframe integration, in cui il modulo di pagamento viene inserito in un iframe tramite la nostra integrazione JavaScript, oppure la lightbox integration, per ottenere un’integrazione fluida e conforme allo standard PCI DSS nel vostro checkout.

L’integrazione lightbox consente di visualizzare il modulo per la raccolta delle informazioni di pagamento come finestra in sovrimpressione nel checkout, dopo che l’ordine è stato confermato. Ciò consente il seguente processo (semplificato) nell’applicazione dell’esercente:

  1. Facoltativo: il cliente seleziona il tipo di pagamento.

  2. Il cliente invia l’ordine, che viene creato.

  3. Viene visualizzata la lightbox, in cui il cliente può scegliere il tipo di pagamento (se non lo ha già fatto al punto 1) e inserire le proprie informazioni di pagamento.

Il vantaggio di questa integrazione rispetto alla pagina di pagamento è che l’integrazione è fluida e il cliente non si accorge mai di lasciare il sito web dell’esercente. Inoltre, l’integrazione lightbox è meno complicata di quella iframe.

Integrazione lightbox fluida
Figure 1. L’immagine mostra un esempio di integrazione lightbox fluida.

2Dettagli dell’integrazione lightbox

Prima di iniziare con l’integrazione della lightbox dovreste:

  1. Creare un account e registrarvi.

  2. Creare un utente applicativo in Account > Utenti > Utente applicativo.

  3. Imparare come autenticarvi e connettervi al nostro web service.

Note
 Date un’occhiata al nostro repository GitHub, dove offriamo SDKs pronti da scaricare in diversi linguaggi che facilitano notevolmente i vostri sforzi di integrazione.

Vi offriamo inoltre un API Client che vi consente di testare le richieste inviate all’API e di consultare le risposte.

3Interazioni di sistema

lightbox
Figure 2. Diagramma di sequenza dell’integrazione lightbox

3.1Processo

Di seguito descriviamo in dettaglio il processo di integrazione. Per comprenderlo meglio, date un’occhiata al diagramma delle interazioni di sistema riportato sopra.

  1. Create un oggetto transazione con il Transaction Service. Per creare un oggetto transazione potete fornire tutte le informazioni di cui disponete in questa fase. Più informazioni fornite, meglio possiamo prevalidare i dati ed eventualmente escludere alcuni tipi di pagamento che non funzioneranno con questi dati. La maggior parte dei dati forniti può essere aggiornata prima che la transazione venga effettivamente confermata.

  2. Una volta creato l’oggetto transazione, i tipi di pagamento possibili possono essere recuperati utilizzando recupera i tipi di pagamento possibili sul Transaction Service, fornendo il transactionId restituito dalla richiesta iniziale e la modalità di integrazione lightbox. Il metodo restituisce tutti i tipi di pagamento adatti alla transazione corrente. Il metodo può essere utilizzato per verificare se un determinato tipo di pagamento è attivo oppure per visualizzare tutti i tipi di pagamento disponibili. Dipende dal caso d’uso.

  3. Per raccogliere le informazioni di pagamento nella lightbox, dovete includere un file JavaScript nella pagina web da cui la lightbox deve essere aperta. L’URL di questo file JavaScript può essere recuperato tramite buildJavaScriptUrl. Includete lo script utilizzando il tag <script>.

  4. Chiamate la funzione JavaScript LightboxCheckoutHandler.startPayment(paymentMethod, errorCallback) per visualizzare la lightbox. Questa funzione accetta due argomenti facoltativi:

    paymentMethod

    Passate alla funzione l’ID della configurazione del tipo di pagamento per preselezionare questo tipo. Se questo argomento viene omesso, il cliente può selezionare il tipo di pagamento nella lightbox.

    errorCallback

    Come secondo argomento può essere passata una funzione JavaScript, che viene chiamata in caso di errore durante l’apertura della lightbox.

  5. Dopo che il cliente ha inserito le proprie informazioni di pagamento e il pagamento è stato elaborato (o non è riuscito), il cliente viene reindirizzato alla successUrl (o alla failedUrl) definita sull’oggetto transazione.

  6. Restate in ascolto della notifica sull’URL webhook definito per contrassegnare l’ordine nel sistema dell’esercente come authorized o failed. Questo listener di notifiche è importante perché il cliente potrebbe chiudere la finestra prima di tornare all’applicazione dell’esercente. Lo stato della transazione può essere recuperato in qualsiasi momento tramite l’API.

3.2Dettagli tecnici

I passaggi descritti sopra vengono ora spiegati un po' più in dettaglio, incluse le operazioni API con richieste di esempio.

3.2.1Configurazione lato client

L’accettazione dei pagamenti tramite lightbox offre un modo fluido per raccogliere le informazioni di pagamento dai vostri clienti. Questo metodo non solo è integrato in modo fluido, ma soddisfa anche tutti i requisiti PCI DSS per gli esercenti, in modo da tenervi il più possibile fuori dall’ambito di applicazione, ottenendo comunque un flusso di checkout integrato.

Di seguito trovate un esempio della configurazione lato client.

<button id="pay-button">Pay</button>

<script src="jquery.js" type="text/javascript"></script>
<script src="{ JavaScript URL }" type="text/javascript"></script>
<script type="text/javascript">
// Set here the id of the payment method configuration the customer chose.
var paymentMethodConfigurationId = 1;

$('#pay-button').on('click', function(){
	window.LightboxCheckoutHandler.startPayment(paymentMethodConfigurationId, function(){
		alert('An error occurred during the initialization of the payment lightbox.');
	});
});
</script>

3.2.2Creare un oggetto transazione

Per creare un oggetto transazione dovete utilizzare la operazione di creazione della transazione. Qui fornite i dati del cliente di cui disponete, incluse le posizioni e i prezzi. In questo modo viene creata una transazione pending nel vostro Space.

Note
 Fornite tutte le informazioni che siete riusciti a raccogliere dal vostro cliente in questa fase. Più informazioni abbiamo, più accurata sarà la selezione dei tipi di pagamento possibili.

Richiesta

{
   "billingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"some-buyer@customweb.com",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"General-Guisan-Strasse 47"
   },
   "currency":"EUR",
   "language":"de-CH",
   "lineItems":[
	  {
		 "amountIncludingTax":"11.87",
		 "name":"Barbell Pull Up Bar",
		 "quantity":"1",
		 "shippingRequired":"true",
		 "sku":"barbell-pullup",
		 "type":"PRODUCT",
		 "uniqueId":"barbell-pullup"
	  },
	  {
		 "amountIncludingTax":"559",
		 "name":"Rowing Machine",
		 "quantity":"1",
		 "shippingRequired":"true",
		 "sku":"rowing-machine",
		 "type":"PRODUCT",
		 "uniqueId":"rowing-machine"
	  },
	  {
		 "amountIncludingTax":"17.98",
		 "name":"Super Whey Protein",
		 "quantity":"4",
		 "shippingRequired":"true",
		 "sku":"super-whey",
		 "taxes":[
			{
			   "rate":"10",
			   "title":"VAT"
			},
			{
			   "rate":"3.5",
			   "title":"Supplement Fee"
			}
		 ],
		 "type":"PRODUCT",
		 "uniqueId":"super-whey"
	  },
	  {
		 "amountIncludingTax":"12.5",
		 "name":"Special Chär Test",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"special-chär-test",
		 "type":"SHIPPING",
		 "uniqueId":"special-chär-test"
	  },
	  {
		 "amountIncludingTax":"12.5",
		 "name":"Standard Shipping",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"standard-shipping",
		 "type":"SHIPPING",
		 "uniqueId":"standard-shipping"
	  },
	  {
		 "amountIncludingTax":"-10",
		 "name":"Spring Discount",
		 "quantity":"1",
		 "shippingRequired":"false",
		 "sku":"spring-discount",
		 "type":"DISCOUNT",
		 "uniqueId":"spring-discount"
	  }
   ],
   "merchantReference":"DEV-2630",
   "shippingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"some-buyer@customweb.com",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"General-Guisan-Strasse 47"
   }
}

Risposta

La risposta che riceverete contiene l'`id` (nell’esempio seguente 109472) che verrà ora utilizzato per eseguire ulteriori operazioni su questa transazione.

{
	"allowedPaymentMethodBrands": [],
	"allowedPaymentMethodConfigurations": [],
	"authorizationAmount": 603.85,
	"authorizationTimeoutOn": "2017-12-07T08:44:09.119Z",
	"autoConfirmationEnabled": true,
	"chargeRetryEnabled": true,
	"confirmedBy": 0,
	"createdBy": 0,
	"createdOn": "2017-12-07T08:14:09.119Z",
	"currency": "EUR",
	"customersPresence": "VIRTUAL_PRESENT",
	"endOfLife": "2017-12-21T08:14:09.119Z",
	"group": {
		"id": 109478
	},
	"id": 109472,
	"language": "de-CH",
	"linkedSpaceId": 396,
	"metaData": {},
	"plannedPurgeDate": "2017-12-21T08:14:09.119Z",
	"refundedAmount": 0,
	"state": "PENDING",
	"timeZone": "Z",
	"version": 1
}

3.2.3Creare l’URL JavaScript

Per ottenere l’URL del JavaScript potete utilizzare l’operazione buildJavaScriptUrl per ottenere un URL che punta al JavaScript da includere nel vostro checkout per creare la lightbox. Inserite il JavaScript nella pagina in cui la lightbox deve essere visualizzata, come mostrato nell’esempio lato client riportato sopra.

3.2.4Recuperare i tipi di pagamento possibili

Per integrare l’iframe in modo fluido nel vostro checkout, dovrete recuperare i tipi di pagamento possibili e visualizzare le opzioni nel checkout.

Questo restituirà l'`id` del tipo di pagamento, che deve poi essere impostato nel JavaScript utilizzando il paymentMethodConfigurationId.

Risposta

La risposta restituisce i tipi di pagamento possibili per il transactionId indicato.

{
	"data": [{
		"dataCollectionType": "ONSITE",
		"description": {
			"en-US": ""
		},
		"id": 510,
		"imageResourcePath": null,
		"linkedSpaceId": 396,
		"name": "Credit / Debit Card",
		"oneClickPaymentMode": "ALLOW",
		"paymentMethod": {
			"id": 1457546097597
		},
		"plannedPurgeDate": null,
		"resolvedDescription": {
			"en-US": "Pay conveniently with your credit or debit card."
		},
		"resolvedImageUrl": "https://staging-wallee.com/s/396/resource/icon/payment/method/credit-debit-card.svg",
		"resolvedTitle": {
			"en-US": "Credit / Debit Card"
		},
		"sortOrder": 1,
		"spaceId": 396,
		"state": "ACTIVE",
		"title": {
			"en-US": ""
		},
		"version": 2
	}],
	"hasMore": false,
	"limit": 1
}

3.2.5Aggiornare le transazioni

Le proprietà della transazione possono essere aggiornate finché la transazione non si trova nello stato confirmed. Per farlo, utilizzate l’operazione update sul servizio Transaction.

Note
 Date un’occhiata alla sezione Versionamento / Blocco degli oggetti, che descrive come gestire la proprietà version per evitare conflitti di blocco ottimistico.

Richiesta

Nell’esempio seguente aggiorniamo le posizioni ed eliminiamo la posizione di sconto che avevamo aggiunto nell’esempio precedente.

{
	"billingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@customweb.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "General-Guisan-Strasse 47"
	},
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"lineItems": [
		{
			"amountIncludingTax": "11.87",
			"name": "Barbell Pull Up Bar",
			"quantity": "1",
			"sku": "barbell-pullup",
			"type": "PRODUCT",
			"uniqueId": "barbell-pullup"
		},
		{
			"amountIncludingTax": "559",
			"name": "Rowing Machine",
			"quantity": "1",
			"sku": "rowing-machine",
			"type": "PRODUCT",
			"uniqueId": "rowing-machine"
		},
		{
			"amountIncludingTax": "17.98",
			"name": "Super Whey Protein",
			"quantity": "4",
			"sku": "super-whey",
			"type": "PRODUCT",
			"uniqueId": "super-whey"
		},
		{
			"amountIncludingTax": "12.5",
			"name": "Special Chär Test",
			"quantity": "1",
			"sku": "special-chär-test",
			"type": "SHIPPING",
			"uniqueId": "special-chär-test"
		},
		{
			"amountIncludingTax": "12.5",
			"name": "Standard Shipping",
			"quantity": "1",
			"sku": "standard-shipping",
			"type": "SHIPPING",
			"uniqueId": "standard-shipping"
		}
	],
	"shippingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@customweb.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "General-Guisan-Strasse 47"
	},
	"version": 3
}

Risposta

La risposta contiene l’oggetto transazione aggiornato.

{
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"version": 3
}

3.2.6Confermare la transazione

Se la proprietà di conferma automatica non è impostata, la transazione deve essere confermata. Consigliamo comunque di eseguire questo passaggio in ogni caso.

Il passaggio di conferma della transazione deve essere eseguito una volta che gli input del cliente sono stati validati e l’ordine in sospeso è stato creato nella vostra applicazione (vedere il punto 7 del processo sopra). Potete utilizzare la operazione di conferma per confermare la transazione e impostare anche la merchant reference, dato che ora disponete di un numero d’ordine nella vostra applicazione.

Richiesta

{
	"billingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@customweb.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "General-Guisan-Strasse 47"
	},
	"currency": "EUR",
	"id": 109472,
	"language": "de-CH",
	"lineItems": [
		{
			"amountIncludingTax": "11.87",
			"name": "Barbell Pull Up Bar",
			"quantity": "1",
			"sku": "barbell-pullup",
			"type": "PRODUCT",
			"uniqueId": "barbell-pullup"
		},
	 ],
	"merchantReference": "DEV-2630",
	"shippingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@customweb.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "General-Guisan-Strasse 47"
	},
	"version": 5
}

3.2.7Recuperare gli aggiornamenti della transazione

Per essere aggiornati sullo stato della transazione dovreste registrare notifiche webhook dal vostro lato. I webhook vi informano sui cambiamenti di stato delle entità selezionate e dovrebbero attivare nella vostra applicazione l’ulteriore elaborazione dei risultati della transazione.

Maggiori informazioni sui webhook, sui listener webhook e sulla loro configurazione sono disponibili nella documentazione dei webhook.

4Politica di sicurezza

Se nel negozio vengono applicate restrizioni di Content Security Policy, affinché questa integrazione funzioni devono essere rimosse le seguenti restrizioni per https://staging-wallee.com:

  • URL che possono essere caricati come sorgenti valide per JavaScript.

  • Consentire l’esecuzione di script inline.

  • URL che possono essere caricati tramite interfacce iframe.

  • URL che possono essere caricati tramite interfacce script.

Ad esempio, il seguente header lo consentirebbe impostando la direttiva CSP: script-src per consentire il caricamento degli URL https://staging-wallee.com come sorgenti valide per JavaScript, la politica Unsafe inline script per consentire l’esecuzione di script inline, la direttiva CSP: frame-src per consentire il caricamento degli URL https://staging-wallee.com tramite interfacce iframe e la direttiva CSP: connect-src per consentire il caricamento degli URL https://staging-wallee.com tramite interfacce script.

content-security-policy: script-src https://staging-wallee.com 'unsafe-inline'; frame-src https://staging-wallee.com; connect-src https://staging-wallee.com;
Staging 2.218.1