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 utilizzando la nostra integrazione JavaScript, oppure la lightbox integration, per ottenere
un’integrazione senza interruzioni e conforme PCI DSS nel vostro checkout.
Lo scopo dell’integrazione iframe è consentire la raccolta e la validazione delle informazioni di pagamento prima che l’ordine vero e proprio venga confermato dal cliente. Ad esempio, l’iframe può essere incorporato prima che l’ordine venga effettivamente completato nell’applicazione dell’esercente. Ciò consente il seguente processo (semplificato) nell’applicazione dell’esercente:
-
Il cliente inserisce le informazioni di spedizione e fatturazione.
-
L’utente seleziona il tipo di pagamento. L’applicazione incorpora l’iframe con il modulo per la raccolta di informazioni di pagamento aggiuntive. Il modulo dipende dal tipo di pagamento ed eventualmente anche dal connettore.
-
L’applicazione può attivare una validazione delle informazioni inserite.
-
L’utente può confermare l’ordine e l’applicazione ci comunica lo stato finale della transazione. Dopo di che l’iframe viene inviato con JavaScript. L’iframe può essere nascosto dopo la validazione dei dati. L’invio provoca l’uscita dal frame.
Il vantaggio di questa integrazione rispetto alla pagina di pagamento è che l’integrazione avviene senza interruzioni e il cliente non si accorge mai di lasciare il sito dell’esercente. Inoltre le informazioni di pagamento possono essere inserite prima che l’ordine debba essere completato. Ciò implica che il numero d’ordine può essere fornito dopo la raccolta delle informazioni di pagamento. Tuttavia l’integrazione è più complicata dell’integrazione della pagina di pagamento.
Figure 1. L’immagine mostra un esempio di integrazione iframe senza interruzioni
Prima di iniziare con l’integrazione dell’iframe dovreste:
-
Creare un account e registrarvi.
-
Creare un utente applicativo in Account > Utenti > Utente applicativo.
-
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 anche un client API che vi consente di testare le richieste inviate all’API e di vedere le risposte.
Figure 2. Diagramma di sequenza dell’integrazione iframe
Di seguito descriviamo in dettaglio il processo di integrazione. Per comprenderlo meglio, date un’occhiata al diagramma delle interazioni di sistema qui sopra.
-
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 quei dati. La maggior parte dei dati forniti può essere modificata prima che la transazione venga effettivamente confermata. -
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 iltransactionIdrestituito dalla richiesta iniziale e la modalità di integrazioneiframe. Il metodo restituisce tutti i tipi di pagamento attivi per la transazione corrente. Il metodo può essere utilizzato per verificare se un determinato tipo di pagamento è attivo o per visualizzare tutti i tipi disponibili. Questo dipende dall’applicazione dell’esercente. -
Per incorporare l’iframe nel sito web è necessario recuperare un URL JavaScript. A questo scopo può essere utilizzato il metodo di servizio costruisci l’URL JavaScript. L’URL restituito dal metodo di servizio punta al file JavaScript che deve essere incorporato. È sufficiente incorporarlo una sola volta e non per ogni tipo di pagamento. Lo script può essere incorporato utilizzando il tag
<script>. -
Una volta caricato il JavaScript, utilizzate
window.IframeCheckoutHandler(paymentMethodConfigurationId)per creare un nuovo handler di checkout iframe, dovepaymentMethodConfigurationIdè l’ID della configurazione del tipo di pagamento come restituito da recupera i tipi di pagamento possibili. Questo handler può essere utilizzato per caricare l’iframe. Per caricare l’iframe chiamatecreate(containerId), dovecontainerIdè l’id dell’elemento HTML in cui l’iframe deve essere incorporato. Si consiglia di registrare unvalidationCallbackprima della creazione dell’iframe, che viene chiamato ogni volta che la validazione viene attivata sul modulo caricato all’interno dell’iframe. IlvalidationCallbackviene impostato sull’handler con il metodosetValidationCallback(validationCallback). Il callback dovrebbe essere utilizzato per visualizzare i messaggi di errore forniti come argomento. -
È possibile registrare callback aggiuntivi e opzionali sull’handler, prima della creazione dell’iframe. Il
initializeCallbackpuò essere utilizzato per registrare un handler che viene invocato dopo l’inizializzazione dell’iframe. IlheightChangeCallbackviene invocato ogni volta che l’altezza dell’iframe cambia. L’argomento del callback è l’altezza in pixel. I callback vengono impostati rispettivamente con il metodosetInitializeCallback(initializeCallback)osetHeightChangeCallback(heightChangeCallback). -
Aggiungete un pulsante che attiva la validazione del modulo all’interno dell’iframe. Per attivare la validazione chiamate il metodo
validate()sull’handler di checkout iframe. Potete nascondere l’iframe quando la validazione si è conclusa senza errori. Non rimuovete l’iframe. I dati memorizzati all’interno del frame verranno utilizzati in seguito. -
Una volta validato il modulo e quando la transazione deve essere completata, create un ordine nella vostra applicazione e confermate la transazione con il metodo
confirmsulTransaction Service. È consigliabile utilizzare una chiamata Ajax perché altrimenti l’iframe viene ricaricato e tutti i dati vanno persi. Potete anche aggiornare la transazione prima di confermarla. Ad esempio potete applicare costi aggiuntivi in base al tipo di pagamento selezionato oppure modificare i costi di consegna o l’indirizzo di consegna. -
Ora dovrebbe essere chiamato il metodo
submit()sull’handler di checkout iframe. Questo fa sì che il modulo all’interno dell’iframe venga inviato e che si esca dall’iframe, cioè che il sito dell’esercente venga lasciato. Al cliente potrebbe essere chiesto di inserire informazioni aggiuntive. Questo dipende dal tipo di pagamento. -
Quando la transazione è
authorizedofaileddal nostro lato, il cliente viene reindirizzato allasuccessUrlo allafailedUrldefinita al momento della creazione dell’oggetto transazione. -
Restate in ascolto della notifica sull’URL webhook definito per contrassegnare l’ordine nel sistema dell’esercente come
authorizedofailed. Questo listener di notifica è 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.
Alcuni tipi di pagamento richiedono un processo più complesso in più fasi. Per impostazione predefinita, nel modulo di pagamento è incluso un pulsante per navigare attraverso queste fasi. È tuttavia possibile nascondere questi pulsanti e utilizzare il pulsante di invio principale della vostra applicazione per attivare gli eventi.
Per gestire le azioni primarie sostituite, registrate un callback sull’handler iframe con setReplacePrimaryActionCallback(callback). Questo callback viene invocato con la nuova etichetta come parametro, con cui il pulsante principale deve essere aggiornato ogni volta che l’azione primaria viene sostituita. Inoltre, il pulsante deve essere modificato in modo da attivare l’azione trigger().
Quando il cliente ha completato con successo tutte le fasi necessarie, viene invocato il callback registrato con setResetPrimaryActionCallback(callback), che dovrebbe comportare il ripristino del pulsante principale al comportamento predefinito, cioè con l’etichetta iniziale e l’attivazione delle azioni validate() e submit().
Per nascondere i pulsanti nel modulo di pagamento, impostate la configurazione di conseguenza prima di creare l’handler di checkout iframe:
window.IframeCheckoutHandler.configure('replacePrimaryAction', true);Le fasi descritte sopra verranno ora spiegate un po' più in dettaglio, incluse le operazioni API con richieste di esempio.
L’accettazione dei pagamenti tramite iFrame offre un modo senza interruzioni per raccogliere le informazioni di pagamento dal vostro cliente. Questo metodo non solo è integrato senza interruzioni, 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 completamente integrato.
Di seguito trovate un esempio di configurazione lato client in cui l’iframe viene inserito utilizzando la risorsa JavaScript fornita dalla piattaforma. Come può essere risolto il { JavaScript URL }, dove può essere recuperato il paymentMethodConfigurationId, ecc. viene mostrato negli esempi più sotto.
<ul id="payment-errors"></ul>
<div id="payment-form"></div>
<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;
// Set here the id of the HTML element the payment iframe should be appended to.
var containerId = 'payment-form';
var handler = window.IframeCheckoutHandler(paymentMethodConfigurationId);
handler.setValidationCallback(
function(validationResult){
// Reset payment errors
$('#payment-errors').html('');
if (validationResult.success) {
// Create the order within the shop and eventually update the transaction.
$.ajax('http://your-shop-backend.com/create-order', {
success: function(){
handler.submit();
}
});
} else {
// Display errors to customer
$.each(validationResult.errors, function(index, errorMessage){
$('#payment-errors').append('<li>' + errorMessage + '</li>');
});
}
});
//Set the optional initialize callback
handler.setInitializeCallback(function(){
//Execute initialize code
});
//Set the optional height change callback
handler.setHeightChangeCallback(function(height){
//Execute code
});
handler.create(containerId)
$('#pay-button').on('click', function(){
handler.validate();
});
</script>Per creare un oggetto transazione dovete utilizzare
l’operazione di creazione della transazione.
Qui fornite i dettagli del cliente di cui disponete, incluse le voci e i prezzi.
Questo creerà una transazione pending nel vostro Space.
|
Note
|
Si consiglia di fornire tutte le informazioni di cui disponete sull’acquirente. Più informazioni abbiamo, più accurata sarà la selezione dei tipi di pagamento possibili. |
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":"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 sotto 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,
"metaData": {},
"plannedPurgeDate": "2017-12-21T08:14:09.119Z",
"refundedAmount": 0,
"state": "PENDING",
"timeZone": "Z",
"version": 1
}Per ottenere l’URL del JavaScript potete utilizzare l’operazione buildJavaScriptUrl per ottenere un URL che punta al
JavaScript che deve essere incluso nel vostro checkout per creare l’iframe. Inserite il JavaScript nella vostra
pagina dove l’iframe deve essere visualizzato, come mostrato nell’esempio lato client qui sopra.
Per integrare l’iframe senza interruzioni 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 dovrà 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,
"linkedSpaceId": 396,
"name": "Credit / Debit Card",
"oneClickPaymentMode": "ALLOW",
"paymentMethod": {
"id": 1457546097597
},
"resolvedDescription": {
"en-US": "Pay conveniently with your credit or debit card."
},
"resolvedImageUrl": "https://sandbox.app-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
}Le proprietà della transazione possono essere aggiornate finché questa 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 dovete gestire la proprietà version per evitare problemi di locking ottimistico.
|
Richiesta
Nell’esempio sotto aggiorneremo le voci ed elimineremo la voce di sconto che abbiamo 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
}Nel caso in cui la proprietà di conferma automatica non sia impostata, la transazione deve essere confermata. Noi raccomandiamo comunque di eseguire questo passaggio.
Il passaggio di conferma della transazione dovrebbe essere eseguito una volta che gli input del cliente sono stati validati e
l’ordine in sospeso è stato creato nella vostra applicazione (vedere il passaggio 7 del processo sopra).
Potete utilizzare l’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
}Per essere aggiornati sullo stato della transazione dovreste registrare notifiche webhook dal vostro lato. I webhook vi aggiorneranno sui cambiamenti di stato delle entità selezionate e dovrebbero attivare la vostra applicazione per elaborare ulteriormente i risultati della transazione.
Maggiori informazioni sui webhook, sui listener webhook e sulla loro configurazione sono disponibili nella documentazione dei webhook.
Se nel negozio vengono applicate restrizioni di content security policy, affinché questa integrazione funzioni devono essere rimosse le seguenti restrizioni per https://sandbox.app-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://sandbox.app-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://sandbox.app-wallee.com tramite interfacce iframe, la direttiva CSP: connect-src per consentire il caricamento degli URL https://sandbox.app-wallee.com tramite interfacce script.
content-security-policy: script-src https://sandbox.app-wallee.com 'unsafe-inline'; frame-src https://sandbox.app-wallee.com; connect-src https://sandbox.app-wallee.com;