Documentazione
Documentazione
Link per il pagamento

1Cosa sono i link di pagamento?

I link di pagamento aiutano a incassare pagamenti quando sul lato dell’esercente non è disponibile alcun backend / negozio per l’elaborazione dei pagamenti. I link di pagamento vi consentono quindi, in qualità di esercente, di incassare pagamenti senza alcuna programmazione lato server. Il pagamento viene creato invocando un URL con parametri specifici. I parametri sono normali parametri HTTP GET o POST. Ad esempio: l’indirizzo di fatturazione viene ricavato dai parametri della richiesta HTTP all’URL.

I link di pagamento possono essere utilizzati per un’ampia gamma di casi d’uso. L’elenco seguente, non esaustivo, presenta alcuni casi d’uso:

  • Se desiderate vendere un prodotto semplice sul vostro sito web ma non volete implementare alcun backend né utilizzare un carrello per la gestione dei prodotti o del magazzino, potete utilizzare questi link di pagamento. Può essere un’ottima soluzione per gestire vendite flash per le quali non volete creare un negozio, siti web con contenuti statici, ecc. Se utilizzate i link di pagamento, potete inserire un semplice modulo HTML sul vostro sito web che punta alla nostra piattaforma, la quale elabora il pagamento e verifica i dati di fatturazione. Inoltre, potete impostare un limite di acquisti per questo particolare prodotto. Il prodotto e tutte le spese di spedizione possono essere predefiniti nel link di pagamento. Tutte le e-mail di conferma possono essere inviate dal nostro sistema.

  • Se desiderate raccogliere donazioni sul vostro sito web, potete inserire un semplice modulo sul vostro sito web che punta alla nostra piattaforma. L’importo può essere impostato dinamicamente nel modulo ospitato sul vostro sito web. Potete raccogliere i dati di contatto che desiderate e, se volete, memorizzarli nel nostro sistema. Tutte le e-mail verranno inviate dal nostro sistema. Potete adattarle e personalizzarle a piacere.

Note
 Utilizzate i Charge Flows se desiderate incassare pagamenti via e-mail e non volete occuparvi dell’invio di più e-mail e della gestione dei diversi livelli di sollecito quando il vostro cliente non fa clic sul link.

2Come posso configurare un link di pagamento?

Andate su Space > Link di pagamento > Crea e fornite i dati richiesti. Se dovete configurare numerosi link di pagamento in modo automatizzato, potete prendere in considerazione l’utilizzo del servizio web dei link di pagamento.

Per creare il link di pagamento è richiesto un nome, poiché viene visualizzato nell’interfaccia di amministrazione. Tutti gli altri dettagli aggiuntivi sono facoltativi. Tuttavia, se non fornite queste informazioni, esse potrebbero essere modificate dall’utente. Quindi, se desiderate incassare i pagamenti solo in una determinata valuta, dovete fornire questa indicazione. In caso contrario prenderemo la valuta che avete fornito nella richiesta all’URL. Lo stesso vale anche per le voci: se non vengono fornite, prendiamo quelle fornite nella richiesta.

Note
 La richiesta può essere modificata dall’acquirente e l’importo addebitato può differire da quanto avevate previsto.

3Come posso utilizzare un link di pagamento? Come posso integrarlo nel mio sito web?

Una volta creato un link di pagamento, potete prendere l’URL fornito e iniziare a invocarlo. A seconda di come avete configurato il link di pagamento, dovete fornire parametri aggiuntivi nella richiesta che invoca l’URL del link di pagamento.

Se desiderate utilizzare un modulo sul vostro sito web per invocarlo, potete procedere così:

<form action="<< put here payment link url >>" method="POST">

	<input type="text" name="billingAddress[givenName]" placeholder="Given Name" />
	<input type="text" name="billingAddress[familyName]" placeholder="Family Name" />
	<input type="text" name="billingAddress[street]" placeholder="Street" />
	<input type="text" name="billingAddress[postcode]" placeholder="Postcode" />
	<input type="text" name="billingAddress[city]" placeholder="City Name" />
	<input type="text" name="billingAddress[country]" placeholder="Country Code" />

	<input type="hidden" name="lineItems[0][uniqueId]" value="test" />
	<input type="hidden" name="lineItems[0][sku]" value="test" />
	<input type="hidden" name="lineItems[0][name]" value="Test" />
	<input type="hidden" name="lineItems[0][amountIncludingTax]" value="10.87" />
	<input type="hidden" name="lineItems[0][type]" value="PRODUCT" />
	<input type="hidden" name="lineItems[0][quantity]" value="1" />

	<input type="hidden" name="metaData[additionalData]" value="Further data you want to store along the transaction." />

	<input type="hidden" name="currency" value="CHF" />

	<!-- Further parameters as you need. -->

	<input type="submit" value="Pay" />
</form>

Raccomandiamo di utilizzare il method POST e non GET, perché i parametri del modulo verrebbero altrimenti aggiunti all’URL. La lunghezza dell’URL non può superare i 2000 caratteri, perché alcuni browser non la supportano. Utilizzando POST eviterete questo tipo di problemi.

4Quali parametri posso inviare?

In sostanza, potete inviare qualsiasi parametro che potete inviare tramite l’API dei servizi web quando create una transazione. In pratica, il JSON deve essere trasposto in un formato che può essere prodotto da normali moduli HTML. I dati devono essere trasmessi con codifica UTF-8. Di seguito descriviamo i parametri e il loro formato:

4.1Indirizzo di fatturazione e indirizzo di spedizione

L’indirizzo di fatturazione e quello di spedizione hanno gli stessi campi. Quando viene fornito un indirizzo, verifichiamo se è presente un insieme minimo di campi che consenta una consegna. I parametri richiesti e il loro formato dipendono dal paese. Di seguito trovate un elenco di tutti i campi richiesti per un indirizzo:

  • country: il codice paese ISO 3166-1 a due lettere determina come viene convalidato l’indirizzo.

  • givenName: contiene il nome del cliente.

  • familyName: contiene il cognome del cliente.

  • street: il nome della via, incluso il numero civico ecc. dell’indirizzo.

  • postCode: il codice postale dell’indirizzo è normalmente richiesto.

  • city: anche il nome della città è normalmente richiesto.

Consultate anche la definizione del modello di indirizzo per maggiori informazioni sugli altri campi disponibili e su come li convalidiamo.

Per semplificare la convalida dell’indirizzo potete integrare la nostra libreria JavaScript, che consente di convalidare l’indirizzo direttamente sul vostro sito web. Potete dare un’occhiata alla documentazione sulla convalida degli indirizzi. La convalida degli indirizzi offre anche la possibilità di recuperare le regioni e i paesi disponibili. Ciò consente di proporre all’acquirente un campo di selezione da cui scegliere le opzioni consentite. Inoltre, nell’elenco dei paesi indichiamo anche quali campi sono richiesti a seconda del paese. Ciò consente di aggiornare il modulo per contrassegnare come obbligatori i campi dipendenti dal paese.

I campi menzionati devono essere utilizzati con il prefisso billingAddress oppure shippingAddress.

4.2Dettagli del cliente

Potete fornire un parametro customerEmailAddress contenente l’indirizzo e-mail del cliente. Invieremo tutti i messaggi e-mail a questo indirizzo. Qualsiasi altro dettaglio sul cliente deve essere fornito nell’indirizzo di spedizione o di fatturazione.

Il customerId non può essere fornito: poiché viene utilizzato per l’elaborazione dei pagamenti one-click, ignoriamo questo parametro della richiesta.

4.3Voci

Se non fornite le voci nel link di pagamento, dovete fornirle tramite la richiesta. Una voce richiede almeno le seguenti proprietà:

  • amountIncludingTax: l’importo della voce, tasse incluse.

  • name: il nome della voce, visualizzato nei documenti e nelle e-mail.

  • quantity: la quantità della voce. Il prezzo unitario viene calcolato dividendo amountIncludingTax per quantity.

  • type: il tipo della voce indica di cosa si tratta. Tipi possibili: PRODUCT, SHIPPING, DISCOUNT o FEE

  • uniqueId: l’ID univoco identifica la voce all’interno di una singola transazione.

La voce può avere ulteriori proprietà. La definizione del modello di voce fornisce ulteriori dettagli sulle altre proprietà. Di seguito trovate un esempio di voce:

<input type="hidden" name="lineItems[0][uniqueId]" value="t-shirt-123" />
<input type="hidden" name="lineItems[0][sku]" value="t-shirt-red-36" />
<input type="hidden" name="lineItems[0][name]" value="T-Shirt" />
<input type="hidden" name="lineItems[0][amountIncludingTax]" value="40.85" />
<input type="hidden" name="lineItems[0][taxes][0][title]" value="MwSt." />
<input type="hidden" name="lineItems[0][taxes][0][rate]" value="19" />
<input type="hidden" name="lineItems[0][shippingRequired]" value="true" />
<input type="hidden" name="lineItems[0][attributes][color][label]" value="Color" />
<input type="hidden" name="lineItems[0][attributes][color][value]" value="Red" />
<input type="hidden" name="lineItems[0][attributes][size][label]" value="Size" />
<input type="hidden" name="lineItems[0][attributes][size][value]" value="36" />

Se desiderate inviare più di una voce, dovete ripetere le proprietà e aumentare l’indice di uno.

È importante capire che fornire le voci tramite la richiesta consente all’acquirente di modificarle. Non possiamo impedirlo. Ciò implica che per ogni transazione occorre verificare che l’importo non sia stato modificato dall’acquirente.

4.4Valuta

La valuta può essere fornita nel parametro currency. Se è già definita nel link di pagamento, la currency inviata nella richiesta verrà ignorata.

Se il link di pagamento definisce le voci e queste non sono presenti nella richiesta, la valuta deve essere definita nel link di pagamento.

4.5Pagina di errore e pagina di successo

Quando la transazione è stata autorizzata o è fallita, l’utente può essere reindirizzato a una pagina dedicata. Se non è stato specificato nulla, l’utente verrà reindirizzato alla pagina predefinita.

Il parametro failedUrl definisce l’URL a cui l’utente viene reindirizzato quando il pagamento fallisce. Il parametro successUrl definisce l’URL a cui l’utente viene reindirizzato quando il pagamento è stato autorizzato con successo.

Note
 Assicuratevi di utilizzare un URL assoluto, non un URL relativo.

4.6Riferimento dell’esercente

Per fornire un riferimento dell’esercente potete utilizzare il parametro merchantReference. Il riferimento dell’esercente viene visualizzato nella panoramica della transazione. Può anche essere utilizzato per cercare una determinata transazione.

È importante capire che questo merchantReference può essere modificato dall’acquirente; dovreste quindi tenere conto di questo fatto nei processi che impostate.

4.7Informazioni aggiuntive

Se dovete memorizzare ulteriori dati insieme alla transazione, potete farlo utilizzando il campo metaData. Esso consente di memorizzare ulteriori coppie chiave-valore. Ad esempio, se desiderate memorizzare nella chiave comment un commento sull’acquisto, potete farlo passando un commento nel parametro metaData[comment]. Ai metadati si applicano alcuni limiti. Maggiori dettagli sono disponibili nella sezione metadati dell’API dei servizi web.

4.8Controllare la disponibilità per data e ora

La disponibilità del link di pagamento può essere controllata con i parametri availableFrom e availableUntil. Questi parametri vengono interpretati allo stesso modo delle opzioni corrispondenti sul link di pagamento. Tuttavia, se forniti tramite il link di pagamento, l’acquirente può aggirarli. Se devono essere applicati in modo che l’acquirente non possa manipolarli, è necessario utilizzare le opzioni corrispondenti sul link di pagamento stesso.

Le date accettate per availableFrom e availableUntil devono essere nel formato ISO 8601. Ad esempio:

  • 2018-05-01

  • 2018-08-09T10:10:10

  • 2018-08-09T10:10:10+02:00

Se la data non contiene un fuso orario, viene assunto il fuso orario UTC. Tenete presente che potrebbe essere necessario codificare la data nel formato URL.

5Come gestisco la convalida?

Convalidiamo i dati del modulo. Tuttavia, dobbiamo segnalare l’errore su una pagina dedicata, il che non è ottimale per l’esperienza utente. Raccomandiamo di utilizzare la convalida degli indirizzi per convalidare l’indirizzo nel browser prima di inviare il modulo all’URL del link di pagamento. La convalida degli indirizzi offre anche gli strumenti per recuperare i paesi e le regioni.

Convalidiamo nuovamente i dati sul lato server. In questo modo garantiamo che non vengano elaborati dati corrotti.

6Posso aggiungere condizioni generali alla pagina di pagamento?

Raccomandiamo di aggiungere al modulo del vostro sito web una casella di accettazione delle condizioni generali. Tuttavia, se volete obbligare l’utente ad accettare determinate condizioni, potete utilizzare il componente aggiuntivo della pagina di pagamento per le condizioni generali, che obbliga l’utente ad accettare le vostre condizioni.

7Perché non posso utilizzare i pagamenti one-click con i link di pagamento?

I pagamenti one-click consentono all’acquirente di memorizzare i dati di pagamento. Per gli acquisti successivi l’acquirente non deve inserire nuovamente i dati di pagamento.

Poiché non autentichiamo il cliente, non possiamo consentirgli di pagare senza inserire alcun dato di pagamento. Per questo motivo non potete utilizzare la funzione di pagamento one-click con i link di pagamento. Se attivate la funzione di pagamento one-click sul tipo di pagamento, dobbiamo ignorarla.

Staging 2.218.1