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.8 del 22/09/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 acquirer configurati e scaricare tutte le notifiche provenienti dagli acquirer. 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 dagli acquirer al di fuori del proprio gestionale. Le chiavi delle API degli acquirer 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.
E’ necessario richiedere preventivamente una chiave TEMPORANEA di attivazione al team OnPay.
Una volta ottenuta andrà utilizzata in questa chiamata per ottenere la chiave di produzione.
La chiave di produzione corrisponde al campo “Key” per tutte le altre chiamate.
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 agli acquirer di test:
Multisafepay: https://testmerchant.multisafepay.com
Nexi: https://ecommerce.nexi.it/area-test
Volt: fornita separatamente a questo documento, su richiesta
Una volta registrato è necessario generare le API key
Changelog
Versione 1.8 del 22/09/22: aggiunto Acquirer VOLT
– aggiunti parametri chiamata 1 Richiesta Link: gatewayUsername, gatewayPassword, gatewayNotificationKey necessari solo per Volt
– aggiunti parametri chiamata 2 Richiesta Notifiche: gatewayUsername, gatewayPassword necessari solo per Volt
– aggiunti parametri chiamata 3 Lista Utenti: gatewayUsername, gatewayPassword necessari solo per Volt
– aggiunti parametri JSON notifications chiamata 3 Lista utenti: gatewayUsername, gatewayPassword, nrlink_paid, amount_paid.
Versione 1.7 del 01/12/2021: aggiunta chiamata 5. Attivazione chiave di produzione.
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 il team OnPay e il partner |
*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 e Volt). |
gatewayUsername | varchar(500) | Username per l'autenticazione (è richiesta solo per Volt). |
gatewayPassword | varchar(500) | Password per l'autenticazione (è richiesta solo per Volt). |
gatewayNotificationKey | varchar(500) | Chiave per le notifiche (è richiesta solo per Volt). |
*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 https://testpagamenti.erpweb.it/api/get_link/ -F key=XXKEYXX -F gateway=volt -F gatewayApiKey= XXAPIKEYXX -F gatewaySecretKey=XXXSECRETKEYXXX -F gatewayusername=”XXXUSERNAMEXXX@volt.io” -F gatewayPassword=”XXXPASSWORDXXX” -F gatewayNotificationKey=XXXNOTIFICATIONKEYXXX -F extId=PROVA1 -F orderAmount=5000 -F orderCurrency=EUR -F orderDescription=testIOS -F expDate=2022-09-30
Esempio di risposta
{“success”:”true”,”extId”:”X”,”orderId”:”XYZ”,”link”:”https://checkout.sandbox.volt.io/XXXxxxXXX“}
- 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 dell’acquirer 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 dall’acquirer 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 dall’acquirer (la lista completa degli status possibili dipende dall’acquirer);
Richiesta Notifiche – DATI INPUT
Nome Campo | Tipo Campo | Descrizione |
*key | varchar(200) | Chiave concordata tra il team OnPay e il partner |
*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 e Volt, altrimenti lasciare vuoto). |
gatewayUsername | varchar(500) | Username per l'autenticazione (è richiesta solo per Volt). |
gatewayPassword | varchar(500) | Password per l'autenticazione (è richiesta solo per Volt). |
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(200) | Chiave concordata tra il team OnPay e il partner |
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 e Volt). |
gatewayUsername | varchar(500) | Username per l'autenticazione (è richiesta solo per Volt). |
gatewayPassword | varchar(500) | Password per l'autenticazione (è richiesta solo per Volt). |
*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(50) | Nome del gateway richiesto. Valori possibili: "nexi", "multisafepay", "volt" |
*gatewayApiKey | varchar(500) | Chiave per l'autenticazione (fornita dal gateway) |
*gatewaySecretKey | varchar(500) | Secret per l'autenticazione (è richiesta solo per Nexi). |
*gatewayUsername | varchar(500) | Username per l'autenticazione (è richiesta solo per Volt). |
*gatewayPassword | varchar(500) | Password per l'autenticazione (è richiesta solo per Volt). |
*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 |
*nrlink_paid | int | Numero di link incassati nel periodo di ricerca |
*amount_paid | int | Ammontare incassato nel periodo di ricerca. Nota: il valore è un intero composto dal valore intero della cifra seguito dai due decimali. Es. 100,5 euro => 10050. |
* 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 acquirer diversi. Ad esempio potrebbe capitare che un acquirer 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(200) | Chiave concordata tra il team OnPay e il partner |
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/
E’ necessario richiedere preventivamente una chiave TEMPORANEA di attivazione al team OnPay.
Una volta ottenuta andrà utilizzata in questa chiamata per ottenere la chiave di produzione.
La chiave di produzione corrisponde al campo “Key” per tutte le altre chiamate.
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 | varchar(200) | 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 disponibili:
VALUTA | Descrizione | Circuito |
EUR | Euro | Nexi, MultisafePay, Volt |
USD | United States dollar | Nexi |
GBP | Pound Sterling | Nexi, MultisafePay |
VEF | Venezuelan bolívar | Nexi |
AUD | Australian dollar | Nexi |
BRL | Brazilian real | Nexi |
CHF | Swiss franc | Nexi |
CLP | Chilean peso | Nexi |
COP | Colombian peso | Nexi |
CZK | Czech koruna | Nexi |
DKK | Danish krone | Nexi |
INR | Indian rupee | Nexi |
MXN | Mexican peso | Nexi |
PEN | Peruvian Sol | Nexi |
PLN | Polish złoty | Nexi |
RON | Romanian leu | Nexi |
SEK | Swedish krona | Nexi |
NOK | Norwegian krone | Nexi |
CAD | Canadian dollar | Nexi |
HRK | Croatian kuna | Nexi |
HKD | Hong Kong dollar | Nexi |
TWD | New Taiwan dollar | Nexi |
KRW | South Korean won | Nexi |
HUF | Hungarian forint | Nexi |
PHP | Philippine peso | Nexi |
ZAR | South African rand | Nexi |
CNY | Chinese yuan | Nexi |
JPY | Japanese yen | Nexi |
MYR | Malaysian ringgit | Nexi |
AED | United Arab Emirates dirham | Nexi |
ILS | Israeli new shekel | Nexi |
RUB | Russian ruble | Nexi |
SGD | Singapore dollar | Nexi |
NZD | New Zealand dollar | Nexi |
TRY | Turkish lira | Nexi |
ISK | Icelandic króna | Nexi |
THB | Thai baht | Nexi |
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 dagli acquirer. Per una lista completa e aggiornata degli status disponibili, consultare i manuali delle API degli acquirer.
Status | Descrizione |
completed | Una transazione di pagamento è stata completata |