Documentazione
Documentazione
Vista web mobile

1Introduzione

Questa documentazione descrive in dettaglio come comunicare con l’API dei servizi web da un dispositivo mobile. La comunicazione è pensata per avvenire tramite una WebView o una tecnica simile. L’assunto di base è che l’app mobile sia in grado di comunicare invocando funzioni JavaScript all’interno della WebView e ascoltando gli URL invocati dalla `WebView'.

2Sicurezza dei servizi web

L’applicazione mobile potrebbe aver bisogno di un accesso diretto ai servizi web. Tuttavia, la chiave MAC dell’utente dell’applicazione non dovrebbe essere trasmessa al dispositivo mobile, perché ciò consentirebbe a un dispositivo mobile malintenzionato di recuperare tali dettagli. Per questo motivo forniamo un metodo di servizio web dedicato per creare, per una determinata transazione di pagamento, delle TransactionCredentials. Queste credenziali concedono temporaneamente (15 minuti) il permesso di lavorare con la transazione a cui le credenziali sono collegate. Inoltre, quando le credenziali vengono fornite in un secondo momento, concedono le stesse autorizzazioni dell’utente che ha creato le credenziali temporanee. Ciò implica che il dispositivo mobile avrà le stesse autorizzazioni dell’utente.

3Flusso / Interazioni

Il flusso è simile a quello dell’integrazione iFrame. I passaggi seguenti riassumono come utilizzare l’integrazione SDK. Presupponiamo che la transazione sia stata creata e che le credenziali della transazione siano state trasmesse al dispositivo mobile:

  1. Recuperate i tipi di pagamento disponibili utilizzando l’operazione fetchPossiblePaymentMethodsWithCredentials sul Transaction Service.

  2. Presentate all’utente un elenco di tipi di pagamento.

  3. Per il tipo di pagamento selezionato, incorporate il modulo chiamando l’operazione buildMobileSdkUrlWithCredentials sul Transaction Service. L’URL restituito non conterrà il tipo di pagamento selezionato. Questo deve essere aggiunto accodando il parametro URL paymentMethodConfigurationId con l’ID della configurazione del tipo di pagamento da utilizzare. L’URL deve essere invocato all’interno di una WebView.

  4. Quando l’utente indica di voler completare il pagamento (ad esempio premendo un pulsante continue), deve essere attivata la validazione. A tal fine deve essere invocato il MobileSdkHandler. Il risultato della validazione dovrebbe poi essere utilizzato per fornire all’utente un riscontro adeguato. In questo caso attiviamo il callback validationCallback.

  5. Quando il pagamento deve essere elaborato (ad esempio l’utente ha premuto il pulsante pay), il modulo all’interno della WebView deve essere inviato. Ciò può essere fatto invocando il metodo submit sul MobileSdkHandler. Una volta inviato il modulo, potremmo invocare un servizio esterno (ad esempio 3-D secure). Questo servizio potrebbe richiedere l’intero schermo. Una volta completato il pagamento, invochiamo uno dei seguenti callback: awaitingFinalResultCallback, successCallback o failureCallback

Diagramma di sequenza del Mobile SDK
Figure 1. Diagramma di sequenza del flusso Mobile SDK

4Azione primaria sostituita

Alcuni tipi di pagamento richiedono un processo più complesso in più passaggi. Per impostazione predefinita, nel modulo di pagamento è incluso un pulsante per navigare attraverso questi passaggi. È tuttavia possibile nascondere questi pulsanti e utilizzare il pulsante di invio primario della vostra applicazione per attivare gli eventi.

Ogni volta che l’azione primaria viene sostituita, viene invocato un callback replacePrimaryAction con la nuova etichetta come parametro, con cui il pulsante primario deve essere aggiornato. Inoltre, il pulsante deve essere modificato in modo da attivare l’azione MobileSdkHandler.trigger().

Quando il cliente ha percorso con successo tutti i passaggi necessari, viene invocato il callback resetPrimaryAction, che dovrebbe comportare il ripristino del pulsante primario al comportamento predefinito, ovvero avere l’etichetta iniziale e attivare le azioni MobileSdkHandler.validate(); e MobileSdkHandler.submit();.

Per nascondere i pulsanti nel modulo di pagamento, accodate il parametro URL replace-primary-action=1 all’URL di pagamento.

5Callback

I callback vengono attivati per dare all’applicazione mobile la possibilità di reagire a questi eventi. Un callback viene attivato invocando un URL con il prefisso https://localhost/mobile-sdk-callback/. L’URL contiene un nome per il callback e, facoltativamente, alcuni dati allegati. Esempio: https://localhost/mobile-sdk-callback/some-callback?data={"data":"object"}

La WebView deve essere monitorata per individuare gli URL invocati che iniziano con https://localhost/mobile-sdk-callback/. Questi URL rappresentano callback.

5.1Inizializzazione

Quando la finestra è stata caricata completamente e tutti i listener sono stati collegati, viene invocato il callback initializeCallback. Non vengono forniti ulteriori dati.

5.2Modifica dell’altezza del frame

Quando l’altezza del frame cambia, viene invocato il callback heightChangeCallback con l’altezza (in px) nel parametro dei dati.

5.3Sostituzione dell’azione primaria

Se l’azione primaria del modulo di pagamento viene sostituita, viene invocato il callback replacePrimaryAction con l’etichetta dell’azione come parametro. Il pulsante di invio della vostra applicazione deve essere aggiornato con l’etichetta trasmessa e deve attivare l’azione trigger quando viene premuto.

5.4Ripristino dell’azione primaria

Se l’azione primaria del modulo di pagamento è stata sostituita e viene ripristinata al comportamento predefinito, viene invocato il callback resetPrimaryAction. L’etichetta del pulsante di invio deve essere riportata al valore iniziale e, quando il pulsante viene premuto, deve essere attivata l’azione submit.

5.5Validazione

Quando viene attivata la validazione, il suo risultato viene comunicato tramite il callback validationCallback. Il parametro dei dati conterrà un oggetto risultato:

{
	success: false,
	errors: [
		'Message 1',
		'Message 2'
	]
}

5.6In attesa dello stato finale

Quando il processo di pagamento è stato completato, può accadere che non sia disponibile un risultato finale (successo / fallimento). In questo caso invochiamo il callback awaitingFinalResultCallback. Il parametro dei dati conterrà l’ID della transazione. Normalmente uno stato finale di successo o fallimento viene raggiunto entro pochi secondi. A volte può richiedere anche alcuni minuti.

5.7Successo

Quando il processo di pagamento si conclude con successo, viene invocato il callback successCallback. Il parametro dei dati conterrà l’ID della transazione. Successo significa che la transazione è almeno authorized.

5.8Fallito

Quando il processo di pagamento fallisce, viene invocato il callback failureCallback. Il parametro dei dati conterrà l’ID della transazione. Fallito significa che la transazione si trova nello stato failed.

6API JavaScript 

<script>

// This triggers the validation.
MobileSdkHandler.validate();

// This triggers the primary action if it has been replaced by the 'replacePrimaryAction' callback.
MobileSdkHandler.trigger();

// This will submit the form and triggers the processing of the payment.
MobileSdkHandler.submit();

</script>

7Tokenizzazione

I token disponibili possono essere recuperati con l’operazione fetchOneClickTokensWithCredentials sul Transaction Service. L’elaborazione di una transazione con un token di questo tipo può essere effettuata utilizzando processOneClickTokenWithCredentials. L’eliminazione di un token può essere eseguita con l’operazione deleteOneClickTokenWithCredentials.

Ulteriori operazioni possono essere effettuate tramite i servizi regolari Token Service e Token Version Service.