Esercitazione sull’API del commerciante

3.1.2. Esercitazione sull’API del commerciante#

3.1.2.1. Introduzione#

3.1.2.1.1. Informazioni su GNU Taler#

GNU Taler è un protocollo aperto per un sistema di pagamento elettronico con un’implementazione di riferimento di software libero. GNU Taler offre un’elaborazione dei pagamenti sicura, veloce e semplice, utilizzando tecniche crittografiche ben conosciute. GNU Taler consente ai clienti di rimanere anonimi, garantendo al contempo che i commercianti possano essere ritenuti responsabili dai governi. Pertanto, GNU Taler è compatibile con le normative antiriciclaggio (AML) e di conoscenza dei clienti (KYC), nonché con le normative sulla protezione dei dati (come il GDPR).

3.1.2.1.2. Informazioni su questo tutorial#

Questo tutorial spiega come elaborare i pagamenti utilizzando il backend commerciale di GNU Taler. Il pubblico di questo tutorial è costituito da sviluppatori di commercianti (come i negozi Web) che stanno lavorando all’integrazione di GNU Taler con il Frontend rivolto ai clienti e il Backoffice rivolto al personale.

Questo capitolo spiega alcuni concetti di base. Nel secondo capitolo si apprenderà come effettuare i pagamenti di base.

Questa versione del tutorial contiene esempi per Python3. Utilizza la libreria requests per le richieste HTTP. Sono disponibili anche versioni per altri linguaggi/ambienti.

Se volete vedere alcuni esempi semplici e funzionanti, date un’occhiata a questi:

  • Il commerciante di saggi che vende singoli capitoli di un libro.

  • La pagina delle donazioni che accetta le donazioni per i progetti software e fornisce le ricevute delle donazioni.

  • Il plugin WooCommerce che rappresenta un’integrazione completa in un negozio Web, compreso il processo di rimborso.

3.1.2.1.3. Panoramica dell’architettura#

Lo stack software Taler per un commerciante è costituito dai seguenti componenti principali:

  • Un frontend che interagisce con il browser del cliente. Il frontend consente al cliente di creare un carrello della spesa e di effettuare un ordine. Al momento del pagamento, attiva la rispettiva logica aziendale per soddisfare l’ordine. Questo componente non è incluso in Taler, ma si presume che esista presso il commerciante. Questa esercitazione descrive come sviluppare un frontend Taler.

  • Un backend per i pagamenti specifico di Taler che facilita il frontend nell’elaborazione delle transazioni finanziarie con Taler. Per questa esercitazione, si utilizzerà un backend sandbox pubblico. Per l’uso in produzione, è necessario configurare il proprio backend o chiedere a un’altra persona di farlo per voi.

L’immagine seguente illustra le varie interazioni di questi componenti chiave:

../../_images/arch-api.png

Il backend fornisce il supporto del protocollo crittografico, memorizza le informazioni finanziarie specifiche di Taler e comunica con lo scambio GNU Taler su Internet. Il frontend accede al backend tramite un’API RESTful. Di conseguenza, il frontend non deve mai comunicare direttamente con l’exchange e non tratta dati sensibili. In particolare, le chiavi di firma e le informazioni sul conto bancario dell’esercente sono incapsulate nel backend di Taler.

Alcune funzionalità del backend (l“«interfaccia pubblica») sono esposte direttamente al browser del cliente. Nell’API HTTP, tutti gli endpoint privati (per il Backoffice) hanno il prefisso /private/. Questa esercitazione si concentra sugli endpoint /private/. L’interfaccia pubblica è utilizzata direttamente dal portafoglio e non è rilevante per il commerciante (a parte il fatto che l’API deve essere esposta).

3.1.2.1.4. Backend Sandbox pubblico e autenticazione#

Il modo in cui il frontend si autentica al backend Taler dipende dalla configurazione. Vedere il Merchant Backend Operator Manual.

Il backend sandbox pubblico https://backend.demo.taler.net/instances/sandbox/ utilizza una chiave API nell’intestazione Authorization. Il valore di questa intestazione deve essere Bearer secret-token:sandbox per il backend sandbox pubblico.

>>> import requests
>>> requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders",
...              headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Se viene restituito un codice di stato HTTP diverso da 200, qualcosa è andato storto. È necessario capire qual è il problema prima di continuare con questa esercitazione.

Il backend sandbox https://backend.demo.taler.net/instances/sandbox/ utilizza KUDOS come moneta immaginaria. Le monete denominate in KUDOS possono essere prelevate da https://bank.demo.taler.net/.

3.1.2.1.5. Istanze del commerciante#

Un singolo server backend di Taler può essere utilizzato da più commercianti che sono entità commerciali separate. A ciascuna di queste entità commerciali separate viene assegnata un’istanza merchant, identificata da un identificatore di istanza alfanumerico. Se l’istanza viene omessa, viene assunto l’id di istanza admin.

Le seguenti istanze commerciali sono configurate su https://backend.demo.taler.net/:

Nota

Si tratta di commercianti fittizi utilizzati per i nostri dimostratori e non affiliati o approvati ufficialmente dai rispettivi progetti.

Tutti gli endpoint delle istanze offrono la stessa API. Pertanto, l’istanza da utilizzare è semplicemente inclusa nell’URL di base del backend del commerciante.

3.1.2.2. Elaborazione dei pagamenti dei commercianti#

3.1.2.2.1. Creare un ordine per un pagamento#

I pagamenti in Taler ruotano attorno a un ordine, che è una descrizione leggibile a macchina della transazione commerciale per la quale deve essere effettuato il pagamento. Prima di accettare un pagamento Taler come commerciante, è necessario creare un ordine di questo tipo.

Ciò avviene inviando un oggetto JSON all’endpoint API /private/orders del backend. All’interno del campo ordine devono essere indicati almeno i seguenti campi:

  • importo: L’importo da pagare, come stringa nel formato CURRENCY:DECIMAL_VALUE, ad esempio EUR:10 per 10 euro o KUDOS:1.5 per 1.5 KUDOS.

  • sommario: Un riassunto leggibile per il contenuto del pagamento. Il riassunto deve essere abbastanza breve da poter essere inserito nei titoli, anche se non viene imposto un limite rigido.

  • fulfillment_url: Un URL che verrà visualizzato una volta completato il pagamento. Per i beni digitali, dovrebbe essere una pagina che mostra il prodotto acquistato. Quando il pagamento va a buon fine, il portafoglio aggiunge automaticamente il ordine_id come parametro della query, così come il session_sig per i pagamenti legati alla sessione (discusso di seguito).

Gli ordini possono avere molti altri campi, vedere Il formato dell’ordine di Taler. Quando si invia un ordine, è possibile specificare ulteriori dettagli, come ad esempio un override per la durata del rimborso e le istruzioni per la gestione dell’inventario. Questi dettagli sono raramente necessari e non sono trattati in questa esercitazione; per i dettagli si rimanda al manuale di riferimento.

Uno snippet Python minimale per la creazione di un ordine sarebbe simile a questo:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Il backend inserirà alcuni dettagli mancanti nell’ordine, come l’indirizzo dell’istanza del commerciante. I dettagli completi sono chiamati condizioni contrattuali.

Nota

La richiesta precedente disabilita l’uso dei claim token impostando l’opzione create_token a false. Se si ha bisogno di token di richiesta, è necessario modificare il codice per costruire l’URI taler://pay/ dato di seguito per includere il token di richiesta.

Dopo aver effettuato con successo una POST a /private/orders, verrà restituito un JSON contenente solo un campo order_id con una stringa che rappresenta l’ID dell’ordine. Se si ottiene anche un token di richiesta, verificare che la richiesta sia stata utilizzata come descritto sopra.

Insieme all”instance del commerciante, l’id dell’ordine identifica in modo univoco l’ordine all’interno del backend del commerciante. Utilizzando l’ID dell’ordine, è possibile costruire banalmente il rispettivo URI taler://pay/ che deve essere fornito al portafoglio. Sia example.com il nome del dominio in cui sono raggiungibili gli endpoint pubblici dell’istanza. L’URI di Taler pay è quindi semplicemente taler://pay/example.com/$ORDER_ID/ dove $ORDER_ID deve essere sostituito con l’ID dell’ordine restituito.

È possibile inserire l’URI taler:// come destinazione di un link per aprire il portafoglio Taler tramite lo schema taler://, oppure inserirlo in un codice QR. Tuttavia, per un negozio Web, il modo più semplice è semplicemente reindirizzare il browser a https://example.com/orders/$ORDER_ID. Questa pagina attiverà il portafoglio Taler. Il backend genera la logica giusta per attivare il portafoglio, supportando i vari tipi di portafoglio Taler esistenti. Invece di costruire a mano l’URL di cui sopra, è possibile ottenerlo anche controllando lo stato del pagamento, come descritto nella prossima sezione.

Quando si costruisce manualmente questo URL, assicurarsi di fornire il token di richiesta (a meno che non sia stato disabilitato) e se il backend è in esecuzione senza TLS utilizzare taler+http:// (si noti che quest’ultimo è supportato solo dai portafogli in esecuzione in modalità debug).

Nota

Un modo banale per ottenere il payment_redirect_url corretto è controllare lo stato del pagamento (vedere sotto). Quindi, se non si è ancora sicuri di come costruirlo, si può semplicemente chiedere al backend di farlo per noi. Tuttavia, in produzione si dovrebbe probabilmente costruirlo manualmente, evitando una richiesta extra al backend.

3.1.2.2.2. Verifica dello stato dei pagamenti e richiesta di pagamento#

Dato l’ID dell’ordine, lo stato di un pagamento può essere controllato con l’endpoint /private/orders/$ORDER_ID. Se il pagamento deve ancora essere completato dal cliente, /private/orders/$ORDER_ID fornirà al frontend un URL (con il nome payment_redirect_url) che attiverà il portafoglio del cliente per eseguire il pagamento. Questo è fondamentalmente l’URL https://example.com/orders/$ORDER_ID di cui abbiamo parlato sopra.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Se il campo stato_ordine nella risposta è pagato, non si otterrà un payment_redirect_url` e invece informazioni sullo stato del pagamento, tra cui:

  • termini_contrattuali: Le condizioni contrattuali complete dell’ordine.

  • refunded: true se è stato concesso un rimborso (eventualmente parziale) per questo acquisto.

  • importo_rimborsato: Importo rimborsato

Una volta che il frontend ha confermato che il pagamento è andato a buon fine, di solito deve attivare la logica di business per l’esercente per adempiere agli obblighi del contratto.

Nota

Non è necessario continuare a interrogare per notare le modifiche allo stato della transazione dell’ordine. Gli endpoint supportano il polling lungo, basta specificare un parametro di query timeout_ms con il tempo massimo che si desidera attendere affinché lo stato dell’ordine cambi in pagato.

3.1.2.3. Rimborsi#

Un rimborso in GNU Taler è un modo per «annullare» un pagamento. Deve essere autorizzato dall’esercente. I rimborsi possono riguardare qualsiasi frazione dell’importo originale pagato, ma non possono superare il pagamento originale. I rimborsi sono limitati nel tempo e possono avvenire solo mentre la borsa detiene i fondi per un determinato pagamento in deposito. Il tempo durante il quale è possibile effettuare un rimborso può essere controllato impostando la scadenza_rimborso in un ordine. Il valore predefinito per questa scadenza di rimborso è specificato nella configurazione del backend del commerciante.

Il frontend può istruire il backend dell’esercente ad autorizzare un rimborso tramite POST all’endpoint /private/orders/$ORDER_ID/refund.

L’oggetto JSON della richiesta di rimborso ha solo due campi:

  • Rimborso»: Importo da rimborsare. Se è stato autorizzato un rimborso precedente per lo stesso ordine, il nuovo importo deve essere superiore, altrimenti l’operazione non ha effetto. Il valore indica l’importo totale da rimborsare, non un aumento del rimborso.

  • ragione: Giustificazione leggibile per il rimborso. Il motivo viene utilizzato solo dal Back Office e non viene esposto al cliente.

Se la richiesta ha esito positivo (indicato dal codice di stato HTTP 200), la risposta include un taler_refund_uri. Il frontend deve reindirizzare il browser del cliente a tale URL per consentire l’elaborazione del rimborso da parte del portafoglio.

Questo frammento di codice illustra l’erogazione di un rimborso:

>>> import requests
>>> refund_req = dict(refund="KUDOS:10",
...                   reason="Customer did not like the product")
>>> requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders/"
...               + order_id + "/refund", json=refund_req,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Nota

Dopo aver concesso un rimborso, l’endpoint pubblico https://example.com/orders/$ORDER_ID cambierà la sua interazione con il portafoglio, passando dalla richiesta di pagamento all’offerta di rimborso. Pertanto, i frontend possono nuovamente reindirizzare i browser a questo endpoint. Tuttavia, per farlo, è necessario aggiungere un campo h_contract (?h_contract=$H_CONTRACT), poiché l’endpoint pubblico lo richiede per autenticare il cliente. Il valore richiesto $H_CONTRACT viene restituito nella risposta di rimborso sotto il campo h_contract.

3.1.2.4. Rilevamento dei riacquisti e URL di adempimento#

Un possibile problema per i commercianti che vendono l’accesso agli articoli digitali è che un cliente potrebbe aver pagato per un articolo su un dispositivo, ma potrebbe poi volerlo leggere su un altro dispositivo, magari uno che non ha nemmeno un portafoglio Taler installato.

Naturalmente, a questo punto al cliente verrebbe richiesto di pagare nuovamente l’articolo. Se il cliente apre il link taler:// nel portafoglio che ha precedentemente pagato l’articolo (ad esempio scansionando il codice QR sul desktop con l’app Android), il portafoglio rivendica il contratto, rileva che l’URL di adempimento è identico a uno per il quale ha già effettuato un pagamento in passato e avvia il reindirizzamento all’acquisto: In questo caso, il portafoglio contatterà il commerciante e riprodurrà il pagamento precedente, ma questa volta utilizzando l’ID di sessione (corrente) del browser (apprende l’ID di sessione dal codice QR).

Il backend del commerciante aggiorna quindi l’ID di sessione dell’ordine esistente con l’ID di sessione corrente del browser. Quando viene controllato lo stato di pagamento del «nuovo» ordine non pagato (o già in long-polling), il backend rileva che per l”ID di sessione e l”URL di evasione del browser esiste un contratto già pagato. Quindi dice al browser di reindirizzare immediatamente all’URL di evasione dove è disponibile l’articolo già pagato.

Per garantire che questo meccanismo funzioni come previsto, gli esercenti devono assicurarsi di non utilizzare lo stesso URL di adempimento per prodotti diversi o per prodotti fisici per i quali si prevede che i clienti acquistino l’articolo più volte. Allo stesso modo, è fondamentale che i commercianti utilizzino costantemente lo stesso URL di adempimento per lo stesso prodotto digitale, quando si desidera un rilevamento dei riacquisti.

Si noti che la modifica dell’ID di sessione a un dispositivo diverso richiede il coinvolgimento del portafoglio che ha effettuato il pagamento, limitando così ragionevolmente la possibilità di condividere ampiamente gli acquisti digitali. Il rilevamento dei riacquisti viene inoltre effettuato solo per gli URL di adempimento HTTP(S). In particolare, ciò significa che gli URI di adempimento come taler://fulfillment-success/$MESSAGE non sono considerati identificativi di una risorsa per cui si può pagare e quindi non devono essere univoci.

3.1.2.5. Argomenti avanzati#

3.1.2.5.1. Pagamenti legati alla sessione#

A volte controllare se un ordine è stato pagato non è sufficiente. Ad esempio, quando si vende l’accesso ai media online, l’editore potrebbe voler essere pagato per lo stesso prodotto da ogni cliente. Taler supporta questo modello consentendo al mechant di verificare se la «ricevuta di pagamento» è disponibile sul dispositivo corrente dell’utente. Questo impedisce agli utenti di condividere facilmente l’accesso ai supporti trasmettendo un link alla pagina di adempimento. Naturalmente, anche gli utenti più sofisticati potrebbero condividere le ricevute di pagamento, ma non è facile come condividere un link e in questo caso è più probabile che condividano direttamente i media.

Per utilizzare questa funzione, il commerciante deve prima assegnare al browser corrente dell’utente un session_id effimero, di solito tramite un cookie di sessione. Quando si esegue o si riproduce un pagamento, il portafoglio riceve una firma aggiuntiva (session_sig). Questa firma certifica che il portafoglio ha mostrato una ricevuta di pagamento per il rispettivo ordine nella sessione corrente.

I pagamenti legati alla sessione si attivano passando il parametro session_id all’endpoint /check-payment. Il portafoglio rimanderà alla pagina di adempimento, ma includerà un parametro aggiuntivo session_sig. Il frontend può interrogare /check-payment con entrambi i parametri session_id e session_sig per verificare che la firma sia corretta.

L’ultimo ID di sessione che è stato usato con successo per dimostrare che la ricevuta di pagamento è nel portafoglio dell’utente è disponibile anche come last_session_id nella risposta a /check-payment.

3.1.2.5.2. Identificazione del prodotto#

In alcune situazioni l’utente potrebbe aver pagato per un bene digitale, ma il frontend non conosce l’ID esatto dell’ordine e quindi non può istruire il wallet a rivelare la ricevuta di pagamento esistente. Questa situazione è comune per i negozi semplici che non dispongono di un sistema di login. In questo caso, all’utente verrebbe richiesto di pagare nuovamente, anche se ha già acquistato il prodotto.

Per consentire al portafoglio di trovare la ricevuta di pagamento esistente, il negozio deve utilizzare un URL di adempimento unico per ogni prodotto. Quindi, il frontend deve fornire un parametro aggiuntivo resource_url a /check-payment. Esso deve identificare questo URL di adempimento unico per il prodotto. Il portafoglio controllerà quindi se ha già pagato un contratto con lo stesso resource_url e, in tal caso, riprodurrà il pagamento precedente.

3.1.2.5.3. Il formato dell’ordine di Taler#

Un ordine Taler può specificare molti dettagli sul pagamento. Questa sezione descrive in modo approfondito ciascuno dei campi.

Gli importi finanziari sono sempre specificati come stringa nel formato CURRENCY:DECIMAL_VALUE.

importo

Specifica l’importo totale che il cliente deve pagare all’esercente.

max_fee

Questo è l’importo totale massimo delle commissioni di deposito che il commerciante è disposto a pagare. Se le spese di deposito per le monete superano questo importo, il cliente deve includerlo nel totale del pagamento. La commissione viene specificata utilizzando lo stesso formato usato per importo.

tariffa max_wire

Commissione massima per il bonifico accettata dall’esercente (la quota del cliente deve essere divisa per il fattore wire_fee_amortization e ulteriormente ridotta se le commissioni di deposito sono inferiori a max_fee). Se manca, il valore predefinito è zero.

ammortamento_filo

Su quante transazioni del cliente l’esercente prevede di ammortizzare in media le commissioni bancarie? Se la commissione di bonifico dello scambio è superiore alla max_wire_fee, la differenza viene divisa per questo numero per calcolare il contributo previsto del cliente alla commissione di bonifico. Il contributo del cliente può essere ulteriormente ridotto dalla differenza tra la max_fee e la somma delle commissioni di deposito effettive. Opzionale, il valore predefinito se mancante è 1. I valori zero e negativi non sono validi e vengono interpretati come 1.

indirizzo_pagamento

Quale URL accetta i pagamenti. Questo è l’URL in cui il portafoglio POSTUMA le monete.

url_adempimento

A quale URL deve andare il portafoglio per ottenere l’adempimento, ad esempio l’HTML o il PDF di un articolo acquistato, o un sistema di tracciamento degli ordini per le spedizioni, o una semplice pagina Web leggibile dall’uomo che indichi lo stato del contratto.

ordine_id

Identificatore alfanumerico, liberamente definibile dall’esercente. Utilizzato dall’esercente per identificare in modo univoco la transazione.

sintesi

Breve riepilogo del contratto, leggibile dall’uomo. Da utilizzare quando si visualizza il contratto in una sola riga, ad esempio nella cronologia delle transazioni del cliente.

timestamp

Ora in cui è stata generata l’offerta.

scadenza_pagamento

Timestamp dell’ora entro la quale il commerciante desidera che l’exchange trasferisca definitivamente il denaro dovuto da questo contratto. Una volta scaduto questo termine, l’exchange aggregherà tutti i depositi in cui i contratti hanno superato la scadenza_di_rimborso ed eseguirà un unico grande pagamento via bonifico. Gli importi saranno arrotondati per difetto all’unità di bonifico; se l’importo totale è ancora inferiore all’unità di bonifico, non sarà erogato.

termine_di_rimborso

Data limite fino alla quale il commerciante è disposto (e in grado) di fornire rimborsi per il contratto utilizzando Taler. Si noti che lo scambio Taler terrà il pagamento in deposito almeno fino a questa scadenza. Fino a questo momento, il commerciante potrà firmare un messaggio per attivare un rimborso al cliente. Dopo questo termine, non sarà più possibile rimborsare il cliente. Deve essere inferiore al pay_deadline.

prodotti

Array di prodotti venduti al cliente. Ogni voce contiene una tupla con i seguenti valori:

descrizione

Descrizione del prodotto.

quantità

Quantità degli articoli da spedire. Può specificare un’unità (ad esempio, 1 kg) o solo il numero.

prezzo

Prezzo per quantità di unità di questo prodotto spedite alla data località_di_consegna. Si noti che di solito la somma di tutti i prezzi dovrebbe sommare l’importo totale del contratto, ma potrebbe essere diversa a causa di sconti o perché i singoli prezzi non sono disponibili.

prodotto_id

ID univoco del prodotto nel catalogo del commerciante. Può essere scelto liberamente, poiché ha un significato solo per il commerciante, ma dovrebbe essere un numero nell’intervallo [0,2^{51}).

tasse

Mappa delle imposte applicabili che il commerciante deve pagare. L’etichetta è il nome dell’imposta, ad esempio IVA, imposta sulle vendite o imposta sul reddito, mentre il valore è l’importo dell’imposta applicabile. Si noti che sono consentite etichette arbitrarie, purché siano utilizzate per identificare il regime fiscale applicabile. I dettagli possono essere specificati dal regolatore. L’informazione viene utilizzata per dichiarare al cliente quali tasse l’esercente intende pagare e può essere utilizzata dal cliente come ricevuta. È probabile che le informazioni vengano utilizzate anche in caso di controlli fiscali sull’esercente.

data_di_consegna

Tempo entro il quale il prodotto deve essere consegnato alla località_di_consegna.

posizione_di_consegna

Questo dovrebbe fornire un’etichetta nella mappa locations, specificando dove l’oggetto deve essere consegnato.

I valori possono essere omessi se non sono applicabili. Ad esempio, se un acquisto riguarda un pacchetto di prodotti che non hanno prezzi individuali o ID prodotto, il product_id o il price possono non essere specificati nel contratto. Allo stesso modo, per i prodotti virtuali consegnati direttamente tramite l’URI di adempimento, non c’è alcun locale_di_consegna.

commerciante
indirizzo

Questo dovrebbe fornire un’etichetta nella mappa locations, specificando dove si trova il commerciante.

nome

Questo dovrebbe indicare un nome leggibile per l’attività del commerciante.

giurisdizione

Questo dovrebbe fornire un’etichetta nella mappa locations, specificando la giurisdizione sotto la quale questo contratto deve essere arbitrato.

luoghi

Mappa associativa dei luoghi utilizzati nel contratto. Le etichette dei luoghi in questa mappa possono essere scelte liberamente e utilizzate ogni volta che un luogo è richiesto in altre parti del contratto. In questo modo, se lo stesso luogo è richiesto più volte (come l’indirizzo di lavoro del cliente o dell’esercente), deve essere elencato (e trasmesso) solo una volta e può essere altrimenti richiamato tramite l’etichetta. Un elenco non esaustivo di attributi di ubicazione è il seguente:

nome

Nome del destinatario per la consegna, sia esso un’azienda o una persona.

Paese

Nome del Paese di consegna, come si trova su un pacco postale, ad esempio «Francia».

Stato

Nome dello Stato di consegna, come si trova su un pacco postale, ad esempio «NY».

regione

Nome della regione di consegna, come si trova su un pacco postale.

province

Nome della provincia di consegna, come si trova su un pacco postale.

città

Nome della città di consegna, come si trova su un pacco postale.

codice postale

Codice di avviamento postale per la consegna, come si trova su un pacco postale.

strada

Nome della via per la consegna, come si trova su un pacco postale.

numero_di_strada

Numero civico (numero dell’abitazione) per la consegna, come si trova su un pacco postale.

Nota

Le località non sono obbligate a specificare tutti questi campi e possono anche avere campi aggiuntivi. I renderizzatori di contratti devono rendere almeno i campi elencati sopra e dovrebbero rendere i campi che non comprendono come un elenco di valori-chiave.