Connettore APIkey

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

Richiesta Link – DATI OUTPUT

* 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“}

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;

        }

<?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

Richiesta Notifiche – DATI OUTPUT

Richiesta Notifiche – JSON notifications

* 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

Lista Utenti – DATI OUTPUT

Lista Utenti – JSON userlist

* 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

Lista Metodi di Pagamento – DATI OUTPUT

JSON payment_method_list

* 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

Attivazione chiave di produzione – DATI OUTPUT

* 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:

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.