Integration Types
Altre funzionalità
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
Reporting consente di scaricare report delle transazioni tramite l'API Reporting.
È possibile ottenere report su ordini e transazioni in tre modi diversi:
È possibile scaricare le transazioni contenute nell'elenco dei risultati di ricerca nel portale Amministrazione dell'esercente in formato CSV (Comma Separated Value).
Reporting registra tutti gli eventi associati a una transazione. Quando si richiede un report delle transazioni, nel report vengono inseriti tutti gli eventi associati a una transazione specifica nel periodo indicato. Sono inclusi tutti gli eventi di aggiornamento associati alla transazione. È inoltre possibile filtrare i dati in base alle esigenze aziendali specifiche.
L'immagine riportata di seguito illustra il meccanismo di creazione di report. Un report delle transazioni richiesto per il periodo compreso tra il 1 e il 29 febbraio 2012 restituisce Evento 1 ed Evento 2. Entrambi sono associati alla stessa transazione. Sebbene anch'esso associato alla transazione, Evento 3 si è verificato dopo la fine del periodo specificato, pertanto non verrà incluso nel report.
Quando si usa Reporting, è necessaria una richiesta http GET come quella mostrata di seguito.
GET /history/version/1/merchant/<merchant>/transaction?timeOfRecord.start=<starttime>&timeOfRecord.end=<endtime>&columns=<columns>&columnHeaders=<columnheaders>
Dove:
<merchant>
è l'ID esercente.<starttime>
e <endtime> indicano il periodo di tempo da coprire. <columns>
sono i campi da includere nel report, separati da virgole. Per i nomi vene rilevata la distinzione tra maiuscole e minuscole.<columnheaders>
è l'elenco delle intestazioni di colonna da includere nel report, separate da virgole. L'ora di inizio è inclusa (orario transazione >= orario di inizio), mentre l'ora di fine non lo è (orario transazione < orario di fine).
L'ora di inizio e l'ora di fine vengono passate come parametri in formato ISO 8601: yyyy-mm-ddThh:mm:ssZ
, dove Z
indica che l'ora è UTC. Se l'ora non è UTC, è necessario specificare un fuso orario come +/-hh[:mm], ad esempio, 12:31+10
(UTC + 10 ore), o 12:31:30-06:30
(UTC meno 6 ore e 30 minuti). Eventuali valori temporali visualizzati nel report sono UTC.
Il primo secondo di un giorno inizia dall'ora 00:00. L'ora di fine del report (timeOfRecord.end) non è inclusa pertanto, per includere nel report il giorno intero, è necessario specificare come ora di fine il primo secondo del giorno successivo (00:00). Analogamente, se si desidera ottenere dati orari, specificare una finestra come inizio di un'ora e l'inizio di quella successiva.
Nella richiesta è possibile specificare due parametri facoltativi:
csv.timeZone=<+ or ->HH:MM
Se specificato, l'orario del record viene mostrato nel fuso orario indicato e senza un indicatore di fuso orario. Si tenga presente che i simboli + e - devono essere codificati in UTF-8. Se ad esempio si imposta csv.timeZone=%2B10:00
, (vale a dire +10.00
) gli orari degli eventi vengono visualizzati nel report come UTC+10 ore.
Se viene omesso, l'output sarà UTC con l'aggiunta di una "Z", a indicare il fuso orario UTC.
csv.timeFormat=<iso8601 or iso8601-T>
Se viene specificato come iso8601-T
, l'output utilizza uno spazio anziché una T come separatore di data e ora.
Se viene omesso o specificato come iso8601
, il separatore di data e ora sarà una "T".
Si consiglia di ignorare l'ora legale per i download dei report. Se tuttavia si desidera che i download dei report siano inseriti in finestre in base all'ora legale, è necessario:
Per evitare complicazioni legate all'ora legale, utilizzare il fuso orario UTC per specificare la finestra dell'ora.
Il parametro delle colonne specifica i campi che devono essere visualizzati nel report. I campi che possono essere specificati sono descritti nell'operazione Retrieve Transaction per la versione di DirectAPI supportata. Si tenga presente che la versione dell'API di creazione dei report è diversa dalla versione di DirectAPI. I campi selezionabili per la versione più recente di DirectAPI sono disponibili qui.
order.item[n].detail
.Se si elaborano transazioni utilizzando più versioni dell'API, è possibile specificare i campi comuni a diverse versioni o quelli univoci di una versione specifica. I dati che non esistono per un record specifico verranno mostrati come valore vuoto nel CSV. Tuttavia ogni nome di campo deve essere valido per almeno una versione dell'API.
Se si specificano solo intestazioni di colonna personalizzate nel parametro columnHeaders, l'elenco dei nomi corrisponde a quello dei campi dell'elenco "colonne". Il parametro &columnHeaders e &l'elenco colonne devono avere lo stesso numero di membri.
Se nella richiesta non sono incluse intestazioni (si omette &columnHeaders), le intestazioni di colonna saranno i nomi dei campi. Se viene passato un parametro di intestazione vuoto (&columnHeaders=), il file di output non conterrà righe di intestazione.
Una volta deciso quali sono i campi da includere nella richiesta, è possibile inoltrarla a Mastercard Gateway. La richiesta viene inviata al gateway di pagamento mediante un richiesta HTTPS GET. Mastercard Gateway presuppone la codifica F-8 per la richiesta URL e supporta tutti i caratteri Unicode utili. È necessario rispettare le regole di codifica URL (vedere RFC 3986).
Per impostazione predefinita, il tipo di contenuto del download è CSV con codifica ISO8859-1. È possibile specificare gli elementi elencati di seguito utilizzando il tipo mime appropriato nell'intestazione Content-Type:
Ad esempio per scaricare in UTF-8, specificare "Accept-Charset : UTF-8".
L'ID dell'esercente è incluso nell'URL. L'autenticazione della password avviene mediante l'autenticazione HTTP di base. La password è la password di Reporting del profilo dell'esercente configurata in Amministrazione dell'esercente (nota: non è uguale alla password di DirectAPI). Vedere Generazione di una password per Reporting
Il nome utente dell'autenticazione di base è "merchant.default".
Esempio di script bash
Gli esempi di script bash utilizzano curl per scaricare i report (vedere http://curl.haxx.se/). Curl presuppone che la password venga impostata nel file .netrc. Tale password deve essere creata nella directory home dell'utente. È necessario aggiungere la riga seguente al file .netrc; <password> deve essere sostituito dalla password dell'esercente:
machine eu-gateway.mastercard.com login merchant.default password <password>
Esempio di Windows PowerShell
La password dell'API viene archiviata crittografata nel file reportingPassword nella cartella principale ($HOME). Per generare il file reportingPassword, eseguire lo script setpassword.ps1 incluso nel bundle scaricato.
Per ulteriori informazioni su come impostare le credenziali, guardare qui.
Se non si invia una password con la richiesta o non si scarica lo script, verrà richiesto (se il client/browser https in uso supporta questa funzione) di fornire una password quando si effettua la chiamata.
Per automatizzare i download, il sistema può eseguire una serie di chiamate di download utilizzando un linguaggio di scripting attivato da un processo timer (ad esempio cron on Linux o Attività pianificate in Windows). Anche i prodotti Managed File Transfer possono funzionare in questo modo.
È possibile scegliere la frequenza con cui eseguire il download. Se si impostano intervalli di dieci minuti, si otterranno dati quasi in tempo reale, tuttavia risulta più efficiente l'uso di intervalli giornalieri. I download dovrebbero avere una frequenza tale da impedire che i file diventino troppo grandi o restino troppo indietro – entrambi i problemi evidenziano l'importanza di un download non riuscito e l'urgenza di risolverlo.
In teoria si imposta l'ora di inizio (timeOfRecord.start) di ogni chiamata come ora di fine (timeOfRecord.end) della chiamata precedente. In questo modo si ha la certezza di ricevere tutti i record una sola volta. Utilizzare il codice di stato HTTP per verificare l'esito dell'ultima chiamata. Se la chiamata non è riuscita, lo script deve attendere qualche minuto e riprovare. Esiste un ritardo di qualche minuto da quando Mastercard Gateway elabora una transazione a quando è disponibile per il download. Se si prova a scaricare i record relativi a quel periodo di tempo, il Mastercard Gateway rifiuta la richiesta con una risposta DATA_AVAILABLE_AFTER e l'ultima ora di fine consentita.
Il bundle degli script di esempio include i seguenti script:
Con l'esempio di script Bash, lo script si basa sul presupposto che la password di Reporting sia stata configurata nel file .netrc.
In risposta a una richiesta GET autenticata valida, Reporting fornisce un file CSV contenente tutti i record delle transazioni di DirectAPI filtrati in base ai singoli campi specificati nella richiesta che sono stati creati o aggiornati nell'intervallo di tempo definito dalla data di inizio e di fine. I record sono disposti in ordine crescente dalla transazione meno recente a quella più recente.
Nel report i numeri della carta di credito sono oscurati.
Di seguito è riportato un report di transazione di esempio:
time,order id,transaction id,card number,card expiry month,card expiry year,amount,currency,type,acquirer,acquirerCode 2012-05-14T06:23:10.859Z,11336976611,1,345678xxxxx4564,5,13,60.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T01:25:19.694Z,11337131511,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T06:33:31.709Z,11337150032,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-16T22:15:53.276Z,11337206569,1,345678xxxxx4564,5,13,75.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T00:22:14.516Z,11337214154,1,345678xxxxx4564,5,13,72.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T01:41:17.447Z,11337218888,1,345678xxxxx4564,5,13,60.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-17T01:41:43.533Z,11337218921,1,345678xxxxx4564,5,13,78.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-21T11:15:00.093Z,11337598863,1,345678xxxxx4564,5,13,39.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-21T12:29:52.954Z,11337603409,1,345678xxxxx4564,5,13,39.00,USD,AUTHORIZATION,AMEXGWS,000 2012-05-22T01:51:09.996Z,11337651486,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000
Se la richiesta non è valida, o se l'ID esercente e la password inviati non sono validi o non autorizzati per l'accesso all'API dei report, viene restituito un messaggio di errore con i dettagli.
Se si inviano due richieste e la data/ora di inizio della prima richiesta corrisponde a quella della seconda richiesta, non ci saranno record di transazioni mancanti o duplicati. Se non ci sono record fino alla data/ora di fine, viene restituito un messaggio di errore che indica l'ultima data/ora possibile.
Se per il periodo del report specificato non esistono record, verrà restituito un file CSV con intestazione ma senza righe.
È possibile richiedere direttamente i report utilizzando un browser Web. I report possono essere configurati nell'URL fornito nella richiesta.
Creare un URL dal modello di seguito:
https://YOUR_GATEWAY_SERVER/history/version/1/merchant/
YOUR_MERCHANT_ID/transaction?REPORT_CONTENTS_AND_FORMAT
REPORT_CONTENTS_AND_FORMAT
example:columns=merchant,order.id,transaction.id, transaction.amount,transaction.amount& columnHeaders=Merchant,OrderID,TransactionID,Currency,Amount
&timeOfRecord.end=2015-01-24T18:43:54
&timeOfRecord.start=2015-01-12T18:38:40
Questo esempio recupera un report contenente esercente, ID ordine, ID transazione, valuta della transazione e importo per le transazioni comprese tra il 15 gennaio 2015 alle ore 18.43.54 e il 24 gennaio 2015 alle ore 18.38.40. Le intestazioni di colonna mostreranno "Merchant", "OrderID", "TransactionID", "Currency" e "Amount".
Incollare l'URL nel browser. Verrà richiesto di inserire la password. La password è la password di Reporting del profilo dell'esercente configurata in Amministrazione dell'esercente (nota: non è uguale alla password di DirectAPI). Vedere Generazione di una password per Reporting. Come nome utente immettere merchant.default.
Per la Reporting è necessaria una richiesta autenticata da password a Mastercard Gateway. È possibile generare la password in Amministrazione dell'esercente.
La password generata dal sistema è un valore a 16 byte, generato casualmente e codificato come stringa esadecimale. Sebbene sia di lunghezza e qualità sufficienti a resistere a qualsiasi tentativo di violazione, è consigliabile proteggerla con le stesse modalità previste per le password utente e gli altri dati sensibili.
È sempre necessario disporre di almeno una password generata e abilitata ma è possibile impostare fino a due password. Per motivi di sicurezza, è consigliabile cambiare periodicamente la password. A questo scopo, generare una nuova password e aggiornare lo script di download del report. In questa fase di passaggio funzioneranno entrambe le password.