Documentazione
Documentazione
Sottoscrizioni

1Abbonamenti

Dopo che un prodotto e un abbonato sono stati creati, l’abbonato deve essere abbonato a un abbonamento.

1.1Creare abbonamenti tramite il backend

Potete creare abbonamenti direttamente tramite il backend. Per farlo dovete navigare su Space > Abbonamento.

iframe
Figure 1. Selezionate un abbonato e un prodotto nel backend.

Per prima cosa dovete selezionare l’abbonato che desiderate abbonare a un prodotto. Nella pagina successiva vi verrà presentata una finestra di dialogo aggiuntiva che chiede un riferimento e fornisce una panoramica dei costi mensili che avete definito nel prodotto.

iframe
Figure 2. Configurate l’abbonamento per l’abbonato.
Note
 In questo esempio nessun token è presente e selezionato. Questo attiverà un Charge Flow in cui verrà inviata un’e-mail all’abbonato per chiedergli i suoi dati di pagamento. Se avete già queste informazioni di pagamento memorizzate in un token valido, è importante che selezioniate qui il token. Maggiori informazioni sulla creazione dei token sono disponibili nella documentazione sulla tokenizzazione.

1.2Web Service API

Un abbonamento può anche essere creato tramite l’API di servizio web. Esistono due modi per inizializzare un abbonamento.

1.2.1Panoramica

Dobbiamo distinguere tra due diverse forme in cui gli abbonamenti possono essere inizializzati:

  1. Integrate il servizio di abbonamento nel vostro sito web con un processo di adesione in cui l’abbonato è presente e desiderate raccogliere subito i suoi dati di pagamento. In questo caso dovrete utilizzare il servizio initializeSubscriberPresent. Questo creerà una transazione di pagamento confirmed che può essere utilizzata per costruire l’URL della Payment Page o il JavaScript come descritto nella documentazione Iframe rispettivamente nella documentazione Payment Page.

  2. Potete anche utilizzare i Charge Flows per inizializzare un abbonamento. In questo caso utilizzate il servizio initialize. Maggiori informazioni sui Charge Flows nella documentazione Charge Flow

Consultate il seguente esempio di richiesta per scoprire come dovete combinare le richieste.

1.2.2Creare un token

È possibile creare un abbonamento con un token specifico. Quando il token è già inizializzato e pronto per essere utilizzato, la creazione dell’abbonamento non richiede alcun input da parte dell’abbonato. Quando non fornite un token, ne creiamo uno insieme all’abbonamento. Il token appena creato non è inizializzato. Pertanto richiede che l’utente fornisca le informazioni di pagamento. Questo può avvenire tramite la transazione iniziale dell’abbonamento.

Oltre a lasciare che il sistema crei il token, questo può essere creato manualmente e assegnato all’abbonamento.

1.2.2.1Creare un token tramite il backend

I token possono essere creati tramite il backend sotto Space > Pagamento > Token. Cliccate lì per creare un nuovo token.

1.2.2.2Creare un token tramite l’API di servizio web

I token possono anche essere creati tramite l’API di servizio web utilizzando l’operazione create sul Token Service.

Richiesta

{
	"enabledForOneClickPayment": true,
	"externalId": "customer-id-1",
	"tokenReference": "customer-id-1"
}
Note
 L'`externaId` deve essere univoco. Se inviate nuovamente l'`externalID`, il token verrà aggiornato.
Note
 Se aggiornate delle entità, dovete aumentare la proprietà di versione per mantenere la coerenza.

1.2.3Creare un abbonamento

Un abbonamento può anche essere creato tramite l’API. Per farlo dovrete utilizzare il Subscription Service.

{
	"currency": "EUR",
	"product": {
		"id": 2
	},
	"selectedComponents": [{
		"id": 4
	}, {
		"id": 2
	}],
	"subscription": {
		"reference": "subscription-subscriber-101",
		"subscriber": {
			"id": 2
		},
		"token": {
			"id": 3
		}
	}
}

Questo creerà un abbonamento nello stato PENDING con i componenti del prodotto e le proprietà specificati. Come passi successivi dobbiamo inizializzare l’abbonamento con Initialize. Questo può avvenire in due modi.

  1. In genere l’abbonato è presente nella vostra applicazione e desiderate che fornisca i dati di pagamento direttamente nel processo di adesione. In questo caso utilizzate l’operazione initializeSubscriberPresent sul Subscription Service

  2. Nel caso in cui il vostro abbonato non sia presente, potete anche inviargli un link di pagamento tramite il Charge Flow, dove gli verrà chiesto di fornire le sue informazioni di pagamento. In questo caso utilizzate l’operazione initialize sul Subscription Service

1.2.4Inizializzare un abbonamento con l’abbonato presente

Una volta creato l’abbonamento, possiamo inizializzare la transazione con l’operazione initializeSubscriberPresent sul Subscription Service.

Richiesta

POST request to the following endpoint:

/api/v2.0/subscriptions/2/initialize-subscriber-present
{
	"successUrl": "http://www.yoursuccessurl.com",
	"failureUrl": "http://www.yourfailedurl.com"
}

Risposta

{
	"createdOn": "2017-04-26T12:08:37.602Z",
	"discardedBy": 0,
	"externalId": "subscription-2",
	"failedUrl": "http://www.yourfailedurl.com",
	"id": 2,
	"ledgerEntries": [],
	"linkedSpaceId": 1,
	"plannedExecutionDate": "2017-04-26T12:08:37.152Z",
	"plannedPurgeDate": "2017-05-12T12:08:37.333Z",
	"processingType": "SYNCHRONOUS",
	"state": "PROCESSING",
	"subscription": {
		"id": 2
	},
	"succeedOn": null,
	"successUrl": "http://www.yoursuccessurl.com",
	"transaction": {
	  "id": 2
	},
	"type": "AUTOMATIC",
	"version": 1
}

Questo creerà una transazione di pagamento che si trova nello stato confirmed. L’ID della transazione restituito nella risposta può ora essere utilizzato per eseguire buildJavaScriptUrl oppure buildPaymentPageUrl e creare un’autorizzazione IFrame o Payment Page.

Esempio

Nell’esempio utilizziamo la richiesta GET a buildPaymentPageURL per ottenere l’URL a cui reindirizzate il vostro commerciante affinché fornisca le informazioni di pagamento e completi l’inizializzazione dell’abbonamento. Quando la transazione si trova nello stato fulfill, l’abbonamento passerà allo stato Active. Questo creerà anche una versione dell’abbonamento attiva.

1.2.5Inizializzare l’abbonamento utilizzando un Charge Flow

Potete anche inizializzare un abbonamento con un Charge Flow. In questo caso utilizzate l’operazione initialize sul Subscription Service.

Questo attiverà automaticamente un Charge Flow e richiederà le informazioni di pagamento al vostro abbonato nel caso in cui non abbiate fornito un token o il token non sia valido.

Note
 Ora avete un abbonato abbonato a un prodotto! Dietro le quinte creiamo un libro mastro (ledger) in cui teniamo traccia degli addebiti che si verificano durante un periodo. Ad ogni periodo il ledger viene riconciliato e l’importo in sospeso viene addebitato al cliente. Questo creerà una transazione e una fattura associata. La fattura illustra quanto deve il cliente, indica quando verrà o è stato addebitato e traccia lo stato del pagamento. Potete aggiungere ulteriori addebiti su questo ledger tramite l’API o nel backend. Maggiori informazioni sono disponibili nella sezione sulla fatturazione.

1.3Disdire abbonamenti

Gli abbonamenti possono essere disdetti con l’operazione terminate nel Subscription Service. Avete la possibilità di rispettare il periodo di disdetta o di disdire l’abbonamento immediatamente. Quando il periodo di disdetta viene rispettato, l’abbonamento proseguirà per il numero specificato di periodi di disdetta sulla versione del prodotto fino a quando l’abbonamento non termina definitivamente. Quando scegliete di disdire l’abbonamento immediatamente, l’abbonamento verrà interrotto, il canone del periodo verrà calcolato pro rata e verrà attivato un addebito con l’importo in sospeso. Se disdite un abbonamento, l’abbonamento verrà spostato nello stato terminating, in cui verranno addebitati gli importi in sospeso. Una volta che l’ultimo addebito è stato completato con successo, spostiamo l’abbonamento nello stato terminated.

Richiesta

spaceId=1&subscriptionId=2&respectTerminationPeriod=true

2Modificare un abbonamento

In genere un abbonamento cambia nel tempo. Esistono diversi motivi per un cambiamento. O l’utente desidera un piano diverso (ad es. passare dal basic plan al pro plan) oppure il prodotto stesso cambia. Un cambiamento del prodotto può richiedere che l’abbonamento venga aggiornato all’ultima versione del prodotto.

Un cambiamento può essere applicato immediatamente o secondo il periodo di disdetta. Quando viene richiesto un cambiamento immediato, il periodo attualmente in corso viene terminato e gli importi in sospeso vengono addebitati. In questo caso i canoni del periodo vengono calcolati pro rata. Le tariffe di attivazione vengono trattate in modo particolare, vedere Upgrade & Downgrade.

Un cambiamento può essere applicato tramite l’API oppure tramite il backend.

2.1Modificare abbonamenti nel backend

Gli abbonamenti possono essere modificati tramite il backend modificando gli abbonamenti. Potete selezionare il nuovo prodotto e definire se il periodo di disdetta debba essere considerato. Questo porta alla creazione di una nuova versione dell’abbonamento per l’abbonato che sarà attiva a seconda dell’impostazione di disdetta.

2.1.1Modificare abbonamenti tramite l’API

Potete anche avviare una modifica dell’abbonamento tramite l’API di servizio web utilizzando l’operazione applyChanges sul Subscription Service

La richiesta seguente aggiornerà il mio abbonamento con ID 8 al nuovo prodotto pro con ID 3. Queste modifiche avranno effetto immediato.

Richiesta

{
	"currency": "CHF",
	"product": {
		"id": 3
	},
	"respectTerminationPeriod": false,
	"selectedComponents": [{
		"id": 14
	}],
	"subscription": {
		"id": 8
	}
}

2.2Downgrade & Upgrade

Le tariffe di attivazione vincolano l’abbonato. Tuttavia, il vincolo nel passaggio tra prodotti dovrebbe essere ridotto. Pertanto di solito le tariffe di attivazione vengono rimborsate quando si passa da un prodotto all’altro. Ad esempio, passando dal basic plan al pro plan, l’abbonato non deve pagare di nuovo l’intera tariffa di attivazione del pro plan. Viene concesso uno sconto. Chiamiamo questo processo di passaggio tra prodotti con tariffe di attivazione upgrade risp. downgrade. Anche un aggiornamento della versione del prodotto può portare a un upgrade o a un downgrade.

Le sezioni seguenti sono rilevanti solo quando il prodotto ha tariffe di attivazione.

L’illustrazione qui sotto aiuta a mostrare come vengono calcolati i downgrade e gli upgrade.

iframe
Figure 3. Come vengono calcolati gli upgrade o i downgrade.

Se state eseguendo un upgrade o un downgrade viene determinato da due parametri:

  • weight: il peso può essere impostato sul componente del prodotto.

  • product-reference: anche il riferimento del prodotto viene impostato sul componente del prodotto.

Nel caso in cui modifichiate un abbonamento, confrontiamo i componenti della vecchia e della nuova versione del prodotto.

  1. Inizialmente la tariffa di attivazione della nuova versione del prodotto verrà addebitata all’abbonato. Nell’illustrazione sopra vedete che la nuova versione del prodotto ha una tariffa di attivazione di 150 EUR per il componente Support Pro. Questa verrà quindi addebitata immediatamente dopo l’esecuzione del cambiamento.

  2. In base al peso e alle impostazioni del componente nella vecchia versione del prodotto, verrà applicato un accredito di upgrade o downgrade sul suo ledger. Nell’illustrazione sopra abbiamo impostato sul componente Support che ci sarà un accredito di 50 EUR in caso di upgrade.

  3. Prima di tutto verifichiamo se il componente era già presente nella vecchia versione del prodotto nello stesso gruppo di componenti. Se troviamo il riferimento, confrontiamo i pesi per determinare se si tratta di un upgrade o di un downgrade.

  4. Poiché il weight del componente Support Pro è più alto, il cambiamento viene considerato un upgrade e i 50 EUR verranno accreditati sul ledger dell’abbonato.

  5. Nel caso in cui venga aggiunto al gruppo di componenti un nuovo componente che non era presente nella vecchia versione del prodotto, non verrà effettuato alcun accredito.

Il cambiamento della versione dell’abbonamento dell’abbonato comporta un accredito che può essere visto sul ledger dell’abbonamento dell’abbonato.

iframe
Figure 4. Vedete i 50 EUR che vengono accreditati sul ledger dell’abbonato.