Documentazione
Documentazione
Applicazioni web di pagamento BETA

1Introduzione alle Payment Web App

Le Payment Web App consentono l’integrazione di servizi di pagamento che non sono direttamente integrati nel nostro servizio.

Le Payment Web App in generale sono semplicemente normali Web App con la capacità di elaborare pagamenti.

A grandi linee, dovete fare le seguenti cose per integrare l’elaborazione dei pagamenti nella vostra Web App:

  1. Dovete integrare il processo di installazione per la vostra Web App.

  2. Dovete utilizzare il servizio REST Payment Web App per aggiungere un gestore corrispondente e uno o più connettori.

  3. Dovete fornire un URL su cui potete presentare una pagina di pagamento che consenta all’acquirente di confermare il pagamento.

  4. L’acquirente conferma il pagamento sulla vostra pagina di pagamento. Voi comunicate il risultato tramite JavaScript.

  5. In background aggiornate anche il nostro backend sul risultato dell’elaborazione del pagamento. A questo scopo utilizzate l’operazione di aggiornamento del tentativo di addebito.

Facoltativamente potete anche consentire all’esercente di eseguire completamenti differiti e di effettuare rimborsi.

La sezione seguente vi guiderà attraverso i dettagli del processo per realizzare una tale integrazione.

2Installazione del gestore e dei connettori

L’installazione del gestore e dei connettori avviene tramite il servizio REST Payment Web App. Per poterli installare avete bisogno innanzitutto dell’accesso allo Space dell’esercente. A questo proposito seguite le istruzioni su come deve essere eseguita l’installazione di una web app.

Una volta installata la Web App nello Space dell’esercente, le credenziali della Web App consentono l’installazione dei gestori e dei connettori. Nell’ambito del processo di installazione potete chiedere all’esercente di concedervi determinate autorizzazioni. Per poter successivamente installare i gestori e i connettori dovete richiedere l’autorizzazione Payment Web Apps (ID: 1627022088852).

2.1Inserimento di un gestore

Una volta richiesta all’esercente l’autorizzazione ad accedere allo Space, utilizzate l’operazione di inserimento del gestore per aggiungere un nuovo gestore.

Nell’ambito dell’inserimento del gestore dovete fornire un externalId. Questo ID deve essere univoco per Space. Se il servizio viene invocato più volte con lo stesso externalId, il gestore viene aggiornato e non viene inserito un nuovo gestore.

Note
 Quando l’esercente disinstalla la vostra Web App, anche i gestori associati vengono rimossi.

2.2Inserimento di un connettore

Una volta aggiunto un gestore potete anche inserire un connettore. Per farlo dovete utilizzare l’operazione di inserimento del connettore.

  • externalId: analogamente al gestore, dovete fornire un externalId. Questo ID deve essere univoco. Le richieste con lo stesso externalId aggiorneranno il connettore invece di inserirne uno nuovo.

  • processorExternalId: il connettore è sempre associato a un gestore. Dovete quindi fornire anche il processorExternalId del gestore aggiunto in precedenza.

  • completionConfiguration e refundConfiguration: fornendo le configurazioni corrispondenti potete controllare se supportare i rimborsi e i completamenti differiti. Tenete presente che una volta indicato che supportate queste funzionalità opzionali, non potete più disattivarle sul connettore tramite una chiamata di aggiornamento.

  • paymentPageEndpoint: il paymentPageEndpoint riceverà le richieste di pagamento. Vedere Gestione della pagina di pagamento per maggiori dettagli.

  • connector: il connector definisce quale tipo di pagamento (ed eventualmente anche quale marchio) è associato al vostro connettore di Web App appena aggiunto. Vedere sotto i connettori che potete fornire.

Vedere connettori supportati per l’elenco completo dei connettori supportati.

2.3Passaggio alla modalità live

Il gestore è per impostazione predefinita automaticamente pronto per essere utilizzato nell’ambiente di produzione. Se volete prima integrare l’esercente in una modalità di test e passare successivamente a una modalità live, potete farlo. Quando create un nuovo gestore potete definire la productionModeUrl. Se fornite questo URL, l’utente verrà inoltrato a questo URL non appena il gestore viene spostato in modalità di produzione.

All’URL verranno aggiunti i seguenti parametri:

  • timestamp: l’ora come timestamp Unix (secondi da gennaio 1970). Impedisce gli attacchi di tipo replay. Dovreste quindi assicurarvi che non sia troppo vecchio.

  • externalId: l’ID del gestore come fornito al momento della creazione tramite l’API di servizio web. Vi aiuta a identificare il gestore dal vostro lato.

  • returnUrl: quando l’utente ha completato l’attivazione, potete reindirizzare l’utente a questo URL. Inoltre potete aggiungere un message e un type. Il message può contenere un messaggio per l’utente e il type indica se si tratta di un failure o di un success.

  • spaceId: l’ID dello Space indica in quale Space è stato installato il gestore.

  • hmac: l’HMAC consente di verificare se l’utente proviene realmente dai nostri server. Il calcolo dell'`hmac` funziona allo stesso modo degli altri HMAC.

Note
 Vi preghiamo di includere tutti i parametri che ricevete sull’URL. In futuro potremmo ampliare l’elenco dei parametri. In tal caso li includeremo anche nel calcolo dell’HMAC.

3Gestione della pagina di pagamento

Durante l’installazione del connettore dovete fornire un endpoint della pagina di pagamento. Questo URL dell’endpoint verrà invocato dall’acquirente durante l’elaborazione del pagamento.

Questa invocazione consente di elaborare il pagamento richiedendo ulteriori dettagli o autenticando l’acquirente ecc. L’endpoint della pagina di pagamento deve fornire il seguente comportamento:

  1. Verificate l’origine della richiesta. La richiesta contiene un HMAC che consente la verifica dell’origine della richiesta. Così potete essere sicuri che la richiesta sia legittima.

  2. Richiedete ulteriori dettagli all’utente. Ad esempio chiedete all’utente di autenticarsi. Questo passaggio può anche essere saltato quando non è necessario.

  3. Una volta chiaro il risultato dell’elaborazione, invocate il JavaScript corrispondente per comunicare il risultato dell’elaborazione del pagamento. Questo feedback viene utilizzato solo all’interno del client. Attiverà nel client la modifica dell’interfaccia utente in modo che l’utente conosca il risultato. Nel caso in cui qualcosa vada storto con il pagamento e il client si blocchi, dovete comunicare il risultato in background anche al nostro backend.

Le due sezioni seguenti trattano più in dettaglio il primo e l’ultimo passaggio del processo.

3.1Gestire la richiesta in arrivo della pagina di pagamento

Quando l’acquirente invoca l’URL dell’endpoint della pagina di pagamento, i seguenti parametri faranno parte della richiesta GET:

  • transactionId: l’ID della transazione fa riferimento alla transazione attualmente in elaborazione. Se l’esercente lo consente, possono esserci più tentativi di addebito per transazione.

  • chargeAttemptId: l’ID del tentativo di addebito fa riferimento al tentativo di addebito eseguito nell’ambito di questa invocazione.

  • language: la lingua indica la lingua parlata dall’acquirente. La pagina di pagamento dovrebbe quindi essere visualizzata in questa lingua. Il parametro language è nel formato del tag di lingua IETF. Ad esempio de-DE.

  • currency: la valuta contiene il codice ISO a 3 lettere della valuta (ad es. USD, EUR, CHF ecc.).

  • returnUrl: quando il pagamento è completato dovete reindirizzare l’utente a questo URL.

  • amount: l’importo corrisponde all’importo che deve essere addebitato. Il formato dell’importo è un normale numero decimale. Ad esempio 10.56. Vi preghiamo di tenere presente che potreste dover utilizzare una struttura dati dedicata per gestirlo correttamente. Ad esempio in Java dovreste utilizzare un BigDecimal. Il numero di cifre decimali dipende dalla valuta.

  • authorizationEnvironment: l’ambiente in cui deve essere eseguito il pagamento. Il valore può essere TEST o PRODUCTION. Se il valore è TEST dovete solo eseguire un pagamento simulato. In questo caso non deve essere spostato denaro.

  • completionBehavior: il comportamento di completamento indica se il pagamento deve essere completato IMMEDIATELY o DEFERRED. Nel caso in cui il connettore non supporti la funzione di completamento differito, il completionBehavior sarà sempre IMMEDIATELY.

  • spaceId: l’ID dello Space fa riferimento allo Space in cui è stata installata la web app.

  • connectorExternalId: questo è l’ID del connettore che deve eseguire il pagamento. L’ID corrisponde all’ID fornito durante la creazione del connettore.

  • merchantReference: il riferimento dell’esercente aiuta l’esercente a identificare il pagamento. Quando ha senso, aggiungete questo riferimento al pagamento. Non è univoco ma normalmente aiuta l’acquirente e l’esercente a capire a quale ordine appartiene il pagamento.

  • hmac: l’hmac contiene l’hash sui parametri di cui sopra, protetto con il segreto della Web App. Il calcolo dell'`hmac` funziona come per gli altri HMAC relativi alle Web App. Vi preghiamo di includere tutti i parametri forniti nella richiesta HTTP (esclusi i parametri già presenti nell’URL dell’endpoint). In futuro potremmo aggiungere ulteriori parametri e dovete includerli, altrimenti l’elaborazione non funzionerà più.

Se i parametri di cui sopra non contengono ciò di cui avete bisogno per elaborare il pagamento, potete recuperare l’oggetto transazione tramite l’API REST. In questo caso potreste dover richiedere più autorizzazioni durante l’installazione della Web App.

La richiesta contiene un chargeAttemptId. Ogni transazione può avere più tentativi di addebito. Ogni tentativo prova ad addebitare il consumatore. Se un tentativo ha successo, la transazione viene contrassegnata come authorized. Ciò implica che una transazione può avere al massimo un tentativo di addebito successful. Potreste voler verificare questo dal vostro lato e assicurarvi che non diventi mai un problema. Qualsiasi operazione successiva (rimborso, storno e completamento) farà semplicemente riferimento alla transazione.

Note
 Dovete convalidare l’HMAC per garantire che il sistema non possa essere manomesso. Se lo trascurate, un aggressore potrebbe essere in grado di falsificare un pagamento.
Note
 Vi preghiamo di includere tutti i parametri che ricevete sull’URL. In futuro potremmo ampliare l’elenco dei parametri. In tal caso li includeremo anche nel calcolo dell’HMAC.

3.2Aggiornare il tentativo di addebito

Una volta elaborato il tentativo di addebito, dovete comunicarci qual è lo stato del tentativo di addebito. Dovete farlo prima di reindirizzare l’utente alla returnUrl. A questo scopo dovete utilizzare l’operazione dell’API REST di aggiornamento del tentativo di addebito.

4Completamento differito

Il fornitore di servizi esterno può decidere di offrire anche il completamento differito. Ciò significa che l’esercente prima autorizza un importo e in un secondo passaggio completa un importo diverso. Per consentire un tale processo in due fasi, il connettore deve contenere la proprietà di configurazione completionConfiguration. Durante la creazione del connettore potete aggiungere la proprietà corrispondente.

Note
 Quando il connettore ha supportato una volta il completamento differito, questo non può più essere disattivato. Un aggiornamento che rimuove la configurazione di completamento fallirà quindi.

Il parametro completionBehavior all’interno della richiesta della pagina di pagamento indica se il pagamento deve essere completato direttamente o se seguirà più tardi una richiesta di completamento. IMMEDIATELY significa che il pagamento deve essere contabilizzato direttamente.

4.1Esecuzione di un completamento

Quando l’esercente esegue una richiesta di completamento, viene invocato il completionEndpoint definito all’interno della completionConfiguration. La richiesta HTTP POST all’endpoint contiene il seguente corpo:

{
	"completionId": 1231231,
	"spaceId": 12,
	"amount": 12.96,
	"transactionId": 542131,
	"merchantReference": "Some reference from the merchant for this completion",
	"lastCompletion": true,
}

Descrizione dei parametri:

  • completionId: questo ID fa riferimento al completamento nei nostri sistemi. Potete anche utilizzare l’API di servizio web per leggere l’oggetto completamento con questo ID e recuperare ulteriori dettagli. Insieme allo spaceId, il completionId è univoco.

  • spaceId: l’ID dello Space fa riferimento allo Space a cui appartiene il completamento.

  • amount: l’importo corrisponde all’importo che deve essere completato.

  • transactionId: l’ID della transazione fa riferimento all’oggetto transazione.

  • merchantReference: il riferimento dell’esercente corrisponde a un riferimento dell’esercente che aiuta a identificare questo completamento.

  • lastCompletion: questo flag indica se questo è l’ultimo completamento o se potrebbe seguirne un altro.

La richiesta HTTP con il messaggio JSON di cui sopra viene ripetuta finché il comopletionEndpoint non risponde con un codice di stato HTTP 2xx. Il feedback sullo stato del completamento deve essere fornito tramite un’invocazione dell’operazione dell’API REST di aggiornamento del completamento. Questo feedback deve avvenire entro i completionTimeoutInMinutes. Altrimenti consideriamo il completamento fallito.

4.2Esecuzione di uno storno

Nel caso in cui l’esercente decida di non completare la transazione, eseguiamo uno storno (void). Quando l’esercente ha attivato uno o più completamenti, non è più possibile attivare uno storno.

Quando l’esercente attiva uno storno, il voidEndpoint definito all’interno della completionConfiguration riceve il seguente corpo della richiesta HTTP POST:

{
	"voidId": 65437,
	"spaceId": 12,
	"transactionId": 542131,
}

Descrizione dei parametri:

  • voidId: questo ID fa riferimento allo storno nei nostri sistemi. Potete anche utilizzare l’API di servizio web per leggere l’oggetto void con questo ID e recuperare ulteriori dettagli. Insieme allo spaceId, il voidId è univoco.

  • spaceId: l’ID dello Space fa riferimento allo Space a cui appartiene lo storno.

  • transactionId: l’ID della transazione fa riferimento all’oggetto transazione.

La richiesta HTTP con il messaggio JSON di cui sopra viene ripetuta finché il voidEndpoint non risponde con un codice di stato HTTP 2xx. Il feedback sullo stato dello storno deve essere fornito tramite un’invocazione dell’operazione dell’API REST di aggiornamento dello storno. Questo feedback deve avvenire entro i completionTimeoutInMinutes. Altrimenti consideriamo lo storno fallito.

5Rimborsi

I rimborsi consentono a un esercente di restituire denaro all’acquirente. L’esercente può attivare un tale rimborso solo quando il connettore supporta i rimborsi. Durante la creazione del connettore, la proprietà refundConfiguration abilita i rimborsi per il connettore corrispondente. Quando un connettore ha supportato una volta i rimborsi, questo non può più essere disattivato. Un aggiornamento del connettore che non contiene più la refundConfiguration fallirà quindi.

Quando l’esercente attiva un rimborso, invochiamo il refundEndpoint. Il corpo della richiesta HTTP POST contiene il seguente JSON:

{
	"refundId": 5623,
	"spaceId": 12,
	"amount": 12.96,
	"merchantReference": "Some reference from the merchant for this refund",
	"transactionId": 542131,
}

Descrizione dei parametri:

  • refundId: questo ID fa riferimento al rimborso nei nostri sistemi. Potete anche utilizzare l’API di servizio web per leggere l’oggetto rimborso con questo ID e recuperare ulteriori dettagli. Insieme allo spaceId, il refundId è univoco.

  • spaceId: l’ID dello Space fa riferimento allo Space a cui appartiene il rimborso.

  • amount: l’importo corrisponde all’importo che deve essere rimborsato all’acquirente.

  • transactionId: l’ID della transazione fa riferimento all’oggetto transazione.

  • merchantReference: il riferimento dell’esercente corrisponde a un riferimento dell’esercente che aiuta a identificare questo rimborso.

La richiesta HTTP con il messaggio JSON di cui sopra viene ripetuta finché il refundEndpoint non risponde con un codice di stato HTTP 2xx. Il feedback sullo stato del rimborso deve essere fornito tramite un’invocazione dell’operazione dell’API REST di aggiornamento del rimborso. Questo feedback deve avvenire entro i refundTimeoutInMinutes. Altrimenti consideriamo il rimborso fallito.

6Connettori per app di pagamento

Quando l’app di pagamento è installata, potete aggiungere i connettori con cui elaborate i pagamenti. I seguenti connettori possono essere utilizzati a questo scopo.

ID Nome
1634723429050 Criptovaluta