L’aggregatore OnPay è lo strumento di pagamenti da remoto per l’intermediario che desidera far pagare i propri clienti anche a distanza con vantaggi tangibili di velocità e precisione nella gestione dei flussi di pagamento.
Al nostro marketplace bancario ci si può accedere con un connettore API integrato che viene illustrato nel documento tecnico sotto riportato.
Autore: Avolio Sergio (ItaliaOnSite s.r.l.)
Versione 1.7 del 03/05/2022
Chiave univoca di connessione: fornita separatamente a questo documento
Tipo di chiamata: POST
Request Content Type: application/x-www-form-urlencoded
Response Content Type: application/json
Il sistema OnPay permette di generare i link di pagamento dai vari circuiti configurati e scaricare tutte le notifiche provenienti dai circuiti. Non è possibile modificare o annullare un link generato, ma solo consultarne lo stato.
Questo sistema non necessita che il cliente finale registri le chiavi API generate dai circuiti al di fuori del proprio gestionale. Le chiavi delle API dei circuiti verranno inviate ad ogni richiesta di generazione link.
Questa procedura garantisce per i partner il completo anonimato del proprio cliente intermediario che utilizza il suo gestionale.


Il sistema prevede le seguenti chiamate:
1. Richiesta Link, per generare un singolo link di pagamento
2. Richiesta Notifiche, per scaricare tutte le notifiche di un link o da una data
3. Lista utenti per ottenere una lista di tutte le chiavi utilizzate dai clienti in un dato intervallo di tempo.
4. Lista metodi pagamento per ottenere la lista di tutti i metodi di pagamento registrati, eventualmente accorpati
5. Attivazione chiave di produzione per ottenere la chiave da utilizzare nel sistema.
E’ necessario avere una chiave di attivazione per ottenere quella di produzione
Tipi di dato
varchar(number): stringa di lunghezza variabile. ‘number’ rappresenta la lunghezza massima della colonna in caratteri.
int: numero intero
datetime: data e ora nel formato “YYYY-mm-dd HH:ii:ss”.
boolean: può contenere i valori “true” e “false”
array JSON: gli array iniziano con “[“ (parentesi quadra sinistra) e terminano con (parentesi quadra destra). I valori sono in formato JSON e separati da “,” (virgola)
Area di test
Per utilizzare l’account di test e creare dei finti link di pagamento, è necessario iscriversi ai circuiti di test:
Multisafepay: https://testmerchant.multisafepay.com
Nexi: https://ecommerce.nexi.it/area-test
Una volta registrato è necessario generare le API key
1. Richiesta link
Endpoint test: https://testpagamenti.erpweb.it/api/get_link/
Endpoint produzione: https://onpay.erpweb.it/api/get_link/
Con questa chiamata si potrà generare un link alla volta.
Ad ogni link verrà associato un id esterno, necessario per poterlo gestire nel sistema di notifiche.
Richiesta Link – DATI INPUT
Nome Campo | Tipo Campo | Descrizione |
*key | varchar(200) | Chiave concordata tra Italia On Site e Api |
*gateway | varchar(50) | Nome del gateway richiesto. Valori possibili: "nexi", "multisafepay" |
*gatewayApiKey | varchar(500) | Chiave per l'autenticazione (fornita dal gateway) |
gatewaySecretKey | varchar(500) | Secret per l'autenticazione (è richiesta solo per Nexi). |
*extId | varchar(1000) | Id univoco. Verrà associato al link generato. Servirà per la sua gestione. E’ un valore univoco rispetto alla quaterna key – gateway – gatewayApiKey – gatewaySecretKey |
*orderAmount | int | Ammontare che deve essere pagato. Nota: il valore è un intero composto dal valore intero della cifra seguito dai due decimali. Es. 100,5 euro => 10050. Il fatto di non utilizzare numeri con virgola riduce la possibilità di problemi che si possono verificare sia nel salvataggio che nella conversione |
orderCurrency | varchar(3) | Valuta. Valore di default: "EUR", vedi lista valute. Nexi permette solo Euro |
orderDescription | varchar(200) | Descrizione dell'ordine. Massimo. 200 caratteri alfanumerici (no caratteri speciali) |
*expDate | datetime | Data e ora di scadenza del link di pagamento |
completedUrl | varchar(1000) | URL dove reindirizzare il cliente una volta effettuata la procedura di pagamento. Se non definito, verrà utilizzata una pagina standard |
canceledUrl | varchar(1000) | URL dove reindirizzare il cliente in caso scelga di interrompere la procedura pagamento. Se non definito, verrà utilizzata una pagina standard |
Richiesta Link – DATI OUTPUT
Nome Campo | Tipo Campo | Descrizione |
*success | boolean | tru =>link generato correttamente, false =>errore, vedi errors |
*extId | varchar(1000) | Id univoco associato al link |
*orderId | varchar(1000) | Id univoco associato al link generato dal circuito |
link | varchar(1000) | Link diretto al circuito di pagamento. Nullo in caso di errore |
error | varchar(1000) | In caso di errore, viene descritto qui (l’errore può provenire dal sistema o dal circuito). Può essere nullo. |
* I campi segnati sono obbligatori
- Esempio di chiamata in CURL
curl -d “key=XXX&gateway=XXXgatewayApiKey=XXX&gatewaySecretKey=XXX&extId=X&orderAmount=25000&orderCurrency=EUR&orderDescription=testIOS&expDate=2021-05-15 23:00:00&completedUrl=https://completeurl.it&canceledUrl=https://norcompleteurl.it” https://testpagamenti.erpweb.it/api/get_link/
Esempio di risposta
{“success”:”true”,”extId”:”X”,”orderId”:”XYZ”,”link”:”https:\/\/testpayv2.multisafepay.com\/connect\/xxx\/?lang=it_IT”}
- Esempio di chiamata in C#
C# static async Task CallOnPay() { string url = "https://testpagamenti.erpweb.it/api/get_link/"; string key = "XXX*XXX*XXX"; string gateway = "multisafepay"; string gatewayApiKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; string gatewaySecretKey = ""; string extId = "20210927A_1"; int orderAmount = 25000; string orderCurrency = "EUR"; string orderDescription = "testIOS"; string expDate = "2021-10-25"; string completedUrl = ""; string canceledUrl = ""; try { var listPost = new List<KeyValuePair<string, string>>(); listPost.Add(new KeyValuePair<string, string>("key", key)); listPost.Add(new KeyValuePair<string, string>("gateway", gateway)); listPost.Add(new KeyValuePair<string, string>("gatewayApiKey", gatewayApiKey)); listPost.Add(new KeyValuePair<string, string>("gatewaySecretKey", gatewaySecretKey)); listPost.Add(new KeyValuePair<string, string>("extId", extId)); listPost.Add(new KeyValuePair<string, string>("orderAmount", orderAmount.ToString())); listPost.Add(new KeyValuePair<string, string>("orderCurrency", orderCurrency)); listPost.Add(new KeyValuePair<string, string>("orderDescription", orderDescription)); listPost.Add(new KeyValuePair<string, string>("expDate", expDate)); listPost.Add(new KeyValuePair<string, string>("completedUrl", completedUrl)); listPost.Add(new KeyValuePair<string, string>("canceledUrl", canceledUrl)); var data = new FormUrlEncodedContent(listPost); var client = new HttpClient(); var response = await client.PostAsync(url, data); string jsonresult = await response.Content.ReadAsStringAsync(); Console.WriteLine(jsonresult); Console.ReadLine(); } catch (Exception Ex) { } return; }
- Esempio di chiamata in PHP
<?php $url = "https://testpagamenti.erpweb.it/api/get_payment_method/"; $key = "XXX*XXX*XXX"; $gateway = "multisafepay"; $gatewayApiKey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; $gatewaySecretKey = ""; $extId = "20210927A_2"; $orderAmount = 25000; $orderCurrency = "EUR"; $orderDescription = "testIOS"; //datetime $expDate = "2021-10-25"; $completedUrl = ""; $canceledUrl = ""; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL,"https://testpagamenti.erpweb.it/api/get_link/"); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, "key=".$key."&gateway=".$gateway."&gatewayApiKey=".$gatewayApiKey. "&gatewaySecretKey=".$gatewaySecretKey."&extId=".$extId."&orderAmount=".$orderAmount. "&orderCurrency=".$orderCurrency."&orderDescription=".$orderDescription."&expDate=".$expDate); curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded')); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $server_output = curl_exec ($ch); print_r($server_output); curl_close ($ch); ?>
2. Richiesta Notifiche
Endpoint test: https://testpagamenti.erpweb.it/api/get_notifications/
Endpoint produzione: https://onpay.erpweb.it/api/get_notifications/
Con questa chiamata si può ricevere un Array JSON contenente tutte le notifiche relative a un certo extId, o a partire da una certa data. Tutte le notifiche comprendono anche la data di validazione, quindi sono validate: questa data rappresenta la validazione della notifica da parte del circuito di appartenenza. La data di validazione può differire dalla data di notifica anche di alcuni giorni
N.B. La notifica di avvenuto pagamento, solitamente, arriva dal circuito entro un’ora dal pagamento
Le notifiche possono essere:
Basilari (quelle di default): indicano solo la data di pagamento del link creato;
Complete: riportano tutti gli status ricevuti dal circuito (la lista completa degli status possibili dipende dal circuito);
Richiesta Notifiche – DATI INPUT
Nome Campo | Tipo Campo | Descrizione |
*key | varchar(100) | Chiave concordata tra Italia On Site e Api |
*gateway | varchar(100) | Nome del gateway richiesto. Valori possibili: "nexi", "multisafepay" |
*gatewayApiKey | varchar(100) | Chiave per l'autenticazione (fornita dal gateway) |
*gatewaySecretKey | varchar(100) | Secret per l'autenticazione (è richiesta solo per Nexi, lasciare vuoto). |
extId | varchar(1000) | Id univoco associato al link generato. Può essere nullo. E’ un valore univoco rispetto alla quaterna key – gateway – gatewayApiKey – gatewaySecretKey |
date | datetime | Data dalla quale scaricare le notifiche. Può essere nullo |
allnotifications | boolean | True => il campo “status” di “JSON notifications” contiene lo stato proveniente dal circuito. La lista degli stati possibili è da cercare nel circuito di riferimento. False => il campo “status” di “JSON notifications” può essere solo come definito in tabella “Lista status”. Default false |
Richiesta Notifiche – DATI OUTPUT
Nome Campo | Formato Campo | Descrizione |
*success | boolean | true => link generato correttamente, false => errore, vedi errors |
notifications | Array JSON | Vedi JSON notifications |
errors | varchar(1000) | In caso di errore, viene descritto qui (l’errore può provenire dal sistema o dal circuito). Può essere nullo. |
Richiesta Notifiche – JSON notifications
Nome Campo | Tipo Campo | Descrizione |
*extId | varchar(1000) | Id univoco associato al link generato. E’ un valore univoco rispetto alla quaterna key – gateway – gatewayApiKey – gatewaySecretKey |
*gateway | varchar(100) | Nome del gateway richiesto. Valori possibili: "nexi", "multisafepay" |
*status | varchar(100) | Stato del pagamento al momento della ricezione della notifica (vedi lista status) |
*orderAmount | int | Ammontare che deve essere pagato. Nota: il valore è un intero. Es. 100,5 euro => 10050 |
*orderCurrency | varchar(3) | Valuta, vedi lista valute. Valore di default “EUR” |
*notification_date | datetime | Data notifica |
*validation_date | datetime | Data della validazione della notifica |
*payment_type | int | Codice del metodo di pagamento, vedere campo “code_number” del JSON payment_method_list |
* I campi segnati sono obbligatori
Esempio di chiamata in CURL
curl -d “key=xxx&gateway=xxx&gatewayApiKey=xxx&gatewaySecretKey=xxx” https://testpagamenti.erpweb.it/api/get_notifications/
Esempio di risposta {“success”:”true”,”notifications”:[{“extId”:”7″,”gateway”:”xxx”,”status”:”completed”,”orderAmount”:”15000″,”orderCurrency”:”GBP”,”notification_date”:”2021-05-11″,”validation_date”:”2021-05-11″}]}
3. Lista utenti
Endpoint test https://testpagamenti.erpweb.it/api/get_users/
Endpoint produzione: https://onpay.erpweb.it/api/get_users/
Con questa chiamata si può ricevere un Array JSON contenente tutte le chiavi utilizzate nel periodo dato, le chiavi associate agli utenti finali sono univoche e composte dalla quaterna:
key – gateway – gatewayApiKey – gatewaySecretKey.
Lista Utenti – DATI INPUT
Nome Campo | Tipo Campo | Descrizione |
*key | varchar(100) | chiave concordata tra Italia On Site e Api |
gateway | varchar(100) | Nome del gateway richiesto. Valori possibili: "nexi", "multisafepay" |
gatewayApiKey | varchar(100) | Chiave per l'autenticazione (fornita dal gateway) |
gatewaySecretKey | varchar(100) | Secret per l'autenticazione (è richiesta solo per Nexi). |
*datefrom | datetime | Data dalla quale calcolare le chiavi usate |
*dateto | datetime | Data fino alla quale calcolare le chiavi usate |
Lista Utenti – DATI OUTPUT
Nome Campo | Formato Campo | Descrizione |
status | boolean | True => link generato correttamente, false =>errore, vedi errors |
userslist | array JSON | Vedi JSON userslist |
errors | varchar(1000) | In caso di errore, viene descritto qui (l’errore può provenire dal sistema o dal circuito). Può essere nullo |
Lista Utenti – JSON userlist
Nome Campo | Tipo Campo | Descrizione |
*gateway | varchar(100) | Nome del gateway richiesto. Valori possibili: "nexi", "multisafepay" |
*gatewayApiKey | varchar(100) | Chiave per l'autenticazione (fornita dal gateway) |
*gatewaySecretKey | varchar(100) | Secret per l'autenticazione (è richiesta solo per Nexi). |
*nrlink | int | Numero di link generati nel periodo di ricerca |
*datafirstlink | datetime | Date e ora prima occorrenza trovata nel periodo di ricerca |
*datalastlink | datetime | Date e ora ultima occorrenza trovata nel periodo di ricerca |
* I campi segnati sono obbligatori
Esempio di chiamata in CURL
curl -d “key=xxx&datefrom=2021-05-01 00:00:00&dateto=2021-05-25 23:59:59” https://testpagamenti.erpweb.it/api/get_users/
Esempio di risposta {“success”:”true”,”userslist”:[{“gateway”:”xxx”,”gatewayApiKey”:”xxx”,”gatewaySecretKey”:”xxx”,”nrlink”:”8″,”datafirstlink”:”2021-05-10 14:44:43″,”datalastlink”:”2021-05-13 12:41:09″}]}
4. Lista metodi di pagamento
Endpoint test: https://testpagamenti.erpweb.it/api/get_payment_method/
Endpoint produzione: https://onpay.erpweb.it/api/get_payment_method/
Questa chiamata ritorna la lista dei metodi di pagamento transati tramite API. I metodi di pagamento sono univoci e vengono inseriti quando viene trovato in una nuova notifica. Ogni metodo di pagamento ha un codice numerico univoco e un codice numerico accorpato che serve ad uniformare metodi di pagamento provenienti da circuiti diversi. Ad esempio potrebbe capitare che un circuito ritorni “VISA” e un altro ritorni “VISA CREDIT CARD”, avrebbero codici univoci diversi ma codici accorpati uguali.
Lista Metodi di Pagamento – DATI INPUT
Campo | Tipo | Descrizione |
*key | varchar(100) | chiave concordata tra Italia On Site e Api |
Lista Metodi di Pagamento – DATI OUTPUT
Campo | Tipo | Descrizione |
*success | boolean | true => link generato correttamente, false =>errore, vedi errors |
payment_method_list | array JSON | Vedi JSON payment_method_list |
errors | varchar(1000) | In caso di errore, viene descritto qui. Può essere nullo. |
JSON payment_method_list
Campo | Tipo | Descrizione |
*code_number | int | Codice numerico |
*code_description | varchar(100) | Descrizione del codice proveniente dal circuito |
*code_number_merged | int | Codice numerico accorpato |
* I campi segnati sono obbligatori
Esempio di chiamata in CURL
curl -d “key=xxx” https://testpagamenti.erpweb.it/api/get_payment_method/
Esempio di risposta
{“success”:”true”,”payment_method_list”:[{“code_number”:”1″,”code_description”:”VISA”,”code_number_merged”:”1″},{“code_number”:”2″,”code_description”:”MASTERCARD”,”code_number_merged”:”2″},{“code_number”:”3″,”code_description”:”VISA CREDIT CARD”,”code_number_merged”:”1″}]}
5. Attivazione chiave di produzione
Endpoint test: https://testpagamenti.erpweb.it/api/get_onpay_key/
Endpoint produzione: https://onpay.erpweb.it/api/get_onpay_key/
Con questa chiamata si potrà generare una chiave per utilizzare le API OnPay.
Questa procedura dovrà essere eseguita una sola volta con la chiave di attivazione fornita.
Attivazione chiave di produzione – DATI INPUT
Campo | Tipo | Descrizione |
*key | varchar(100) | Chiave temporanea rilasciata da Italia On Site |
Attivazione chiave di produzione – DATI OUTPUT
Campo | Tipo | Descrizione |
*success | boolean | true => link generato correttamente, false =>errore, vedi errors |
onpaykey | array JSON | Chiave OnPay produzione valida |
errors | varchar(1000) | In caso di errore, viene descritto qui. Può essere nullo. |
* I campi segnati sono obbligatori
Esempio di chiamata in CURL
curl -d “key=XXX” https://onpay.erpweb.it/api/get_onpay_key/
Esempio di risposta
{“success”:”true”,”onpaykey”:”XYZ”}
Lista Valute possibili per MultiSafePay
Le seguenti valute sono disponibili per tutti i tipi di pagamento:
VALUTA | Descrizione |
EUR | Euro |
GBP | Pound Sterling |
Le seguenti valute sono disponibili per Visa, MasterCard e Maestro:
VALUTA | Descrizione |
EUR | Euro |
USD | United States dollar |
GBP | Pound Sterling |
VEF | Venezuelan bolívar |
AUD | Australian dollar |
BRL | Brazilian real |
CHF | Swiss franc |
CLP | Chilean peso |
COP | Colombian peso |
CZK | Czech koruna |
DKK | Danish krone |
INR | Indian rupee |
MXN | Mexican peso |
PEN | Peruvian Sol |
PLN | Polish złoty |
RON | Romanian leu |
SEK | Swedish krona |
NOK | Norwegian krone |
CAD | Canadian dollar |
HRK | Croatian kuna |
HKD | Hong Kong dollar |
TWD | New Taiwan dollar |
KRW | South Korean won |
HUF | Hungarian forint |
PHP | Philippine peso |
ZAR | South African rand |
CNY | Chinese yuan |
JPY | Japanese yen |
MYR | Malaysian ringgit |
AED | United Arab Emirates dirham |
ILS | Israeli new shekel |
RUB | Russian ruble |
SGD | Singapore dollar |
NZD | New Zealand dollar |
TRY | Turkish lira |
ISK | Icelandic króna |
THB | Thai baht |
Lista Status
In caso che il parametro “allnotifications” della chiamata “Richiesta Notifiche” sia false (valore di default), il sistema riporterà solo lo status “completed” per indicare che il pagamento è stato completato. Se il parametro “allnotifications” è true, verranno riportati tutti gli stati generati dai circuiti. Per una lista completa e aggiornata degli status disponibili, consultare i manuali delle API dei circuiti
Status | Descrizione |
completed | Una transazione di pagamento è stata completata |