Documentazione
Documentazione
Pagina dei pagamenti

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.

Il processo della pagina di pagamento è il seguente (semplificato):

  1. Create un transaction object tramite la nostra API.

  2. Richiedete l’URL della pagina di pagamento.

  3. Reindirizzate l’utente alla pagina di pagamento.

  4. Elaborate la richiesta webhook in arrivo per autorizzare la transazione nell’applicazione dell’esercente.

2Interazioni tra i sistemi

Integrazione della pagina di pagamento
Figure 1. Diagramma di sequenza dell’integrazione della pagina di pagamento

3Dettagli dell’integrazione della pagina di pagamento

Prima di iniziare con l’integrazione della pagina di pagamento dovreste:

  1. Creare un account e registrarvi.

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

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

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

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

3.1Processo

  1. Quando il cliente completa il checkout, create un ordine nel vostro negozio.

  2. Dovete creare un transaction object utilizzando il metodo create del Transaction Service.

  3. Utilizzate il servizio build payment page URL per creare l’URL della pagina di pagamento e reindirizzate il cliente a questo URL. Il cliente inserisce i dati di pagamento sulla pagina di pagamento. A seconda del tipo di pagamento verrà eventualmente reindirizzato ulteriormente.

  4. Quando la transazione è stata elaborata o è fallita da parte nostra, il cliente viene reindirizzato alla successUrl o alla failedUrl definita al momento della creazione dell’oggetto transazione.

  5. Restate in ascolto della notifica per contrassegnare l’ordine nel sistema dell’esercente come authorized o failed.

Potete migliorare questo processo lasciando che il cliente selezioni il tipo di pagamento già nell’applicazione dell’esercente. Con l’operazione fetch possible payment methods del Transaction Service offriamo la possibilità di recuperare i tipi di pagamento attivati per un determinato spazio. Poiché qui descriviamo la modalità di integrazione della pagina di pagamento, dovete passare payment_page come modalità di integrazione.

Come risultato, il metodo restituisce i tipi di pagamento possibili. Questi tipi di pagamento costituiscono la base dell’elenco dei tipi di pagamento presentati al cliente. La proprietà allowedPaymentMethods dell’oggetto transazione consente di limitare i tipi di pagamento consentiti per la transazione specifica alla selezione effettuata in precedenza dal cliente.

3.1.1Creare un oggetto transazione

Per creare un oggetto transazione dovete utilizzare l’operazione Creazione della transazione. Qui fornite i dati del cliente in vostro possesso, incluse le voci d’ordine e i prezzi. In questo modo viene creata una transazione nello stato pending nel vostro spazio.

Richiesta

{
   "billingAddress":{
	  "city":"Winterthur",
	  "commercialRegisterNumber":"",
	  "country":"CH",
	  "dateOfBirth":"",
	  "emailAddress":"some-buyer@wallee.com",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"Neuwiesenstrasse 15"
   },
   "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@wallee.com",
	  "familyName":"Test",
	  "gender":"",
	  "givenName":"Sam",
	  "mobilePhoneNumber":"",
	  "organizationName":"Wallee AG",
	  "phoneNumber":"",
	  "postCode":"8400",
	  "salesTaxNumber":"",
	  "salutation":"",
	  "socialSecurityNumber":"",
	  "state":"",
	  "street":"Neuwiesenstrasse 15"
   }
}

Risposta

La risposta che riceverete contiene il campo id (nell’esempio seguente 109472) che verrà ora utilizzato per eseguire ulteriori operazioni con 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,
	"merchantReference": "DEV-2630",
	"metaData": {},
	"plannedPurgeDate": "2017-12-21T08:14:09.119Z",
	"refundedAmount": 0,
	"state": "PENDING",
	"timeZone": "Z",
	"version": 1
}

3.1.2Aggiornare le transazioni

Le proprietà della transazione possono essere aggiornate finché la transazione non si trova nello stato confirmed. A tale scopo utilizzate l’operazione update del servizio transazioni.

Note
 Consultate la sezione Versionamento / blocco degli oggetti, che descrive come dovete gestire la proprietà version per evitare conflitti di blocco ottimistico.

Richiesta

Nell’esempio seguente aggiorniamo le voci d’ordine ed eliminiamo la voce di sconto che avevamo aggiunto nell’esempio precedente.

{
	"billingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@wallee.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "Neuwiesenstrasse 15"
	},
	"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"
		}
	],
	"merchantReference": "DEV-2630",
	"shippingAddress": {
		"city": "Winterthur",
		"country": "CH",
		"emailAddress": "some-buyer@wallee.com",
		"familyName": "Test",
		"givenName": "Sam",
		"postCode": "8400",
		"street": "Neuwiesenstrasse 15"
	},
	"version": 3
}

Risposta

La risposta contiene l’oggetto transazione aggiornato.

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

3.1.3Realizzare la preselezione del pagamento

Per ottenere un’integrazione migliore è utile mostrare ai vostri clienti già nel checkout quali tipi di pagamento sarebbero disponibili in base ai dati dell’oggetto transazione. La risposta dovrebbe essere resa e mostrata come opzioni di pagamento nel vostro checkout.

Per preselezionare il tipo di pagamento sulla transazione, dovreste aggiornare la transazione come mostrato in precedenza fornendo l’ID allowedPaymentMethodConfiguration restituito da fetchPossiblePaymentMethods per la transazione specifica.

Risposta

La risposta restituisce i tipi di pagamento possibili per la transazione specifica.

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

Ora potete utilizzare queste informazioni per visualizzare la selezione del tipo di pagamento nel vostro negozio. Una volta che il cliente ha scelto il tipo di pagamento, potete aggiornare la transazione di cui sopra fornendo le allowedPaymentMethodConfigurations con l’operazione update del servizio transazioni.

Richiesta

{
	"allowedPaymentMethodConfigurations": [
		{
			"id": 507
		}
	],
	"id": 109472,
	"version": 4
}

3.1.4Creare l’URL della pagina di pagamento

Per reindirizzare il cliente alla pagina di pagamento utilizzate l’operazione Creazione dell’URL della pagina di pagamento, che restituisce l’URL della pagina di pagamento verso cui reindirizzare il cliente.

Note
 Offriamo grande flessibilità per personalizzare l’aspetto della pagina di pagamento con il nostro editor di risorse. Ulteriori informazioni sono disponibili nella documentazione su risorse e personalizzazione.

3.1.5Recuperare gli aggiornamenti della transazione

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

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

Staging 2.218.1