Come ricevere pagamenti con ScuolaPay

ScuolaPay Web Payments API

SWP è il gateway di pagamento offerto da ScuolaPay

Scopo del documento è definire le specifiche tecniche e i flussi necessari per integrare il sistema di pagamento Payment Gateway ScuolaPay da parte di Provider (es. registri elettronici) a favore di Business (es. scuole), al fine di permettere pagamenti online da parte di utenti al Business, con i metodi sotto specificati.

Introduzione

SWP è un Hosted Payment Gateway, come Paypal, dove il l'utente viene reindirizzato alla pagina del gateway di pagamento, ospitato sui server di ScuolaPay. Una volta completato il pagamento, l'utente viene rimandato sul sito web/app originario.

La creazione della sessione di pagamento avviene tramite chiamata API Restful all’endpoint https://webpayment-api.scuolapay.it/session (ambiente di produzione) che fornirà in risposta l'url del Payment Gateway di SWP dove indirizzare il browser dell'utente che deve effetuare il pagamento, fornendo i dati per identificare l'ordine di pagamento, l'importo da pagare, una URL di ritorno, ed una causale descrittiva del pagamento.

Oltre a questi dati potranno essere inviate un elenco di operazioni legate all’ordine in modo tale che, al completamento del pagamento, il Business riceverà l’elenco delle operazioni pagate in modo da riconciliare il pagamento alle operazioni indicate.

La chiamata di creazione deve essere autenticata tramite le credenziali associate al Business via Basic Authentication, visibili all’interno del pannello ScuolaPay Business di ciascun Business.

Una volta indirizzato al Payment Gateway di SWP, all'utente verrà mostrato un riepilogo dei dati del pagamento da effetuare e gli verrà permesso di scegliere il metodo di pagamento che vuole utilizzare.

I metodi di pagamento che il servizio ScuolaPay mette a disposizione sono i seguenti:

Nel caso venga selezionato il pagamento tramite APP ScuolaPay, all'utente verrà richiesto di inserire il suo numero di telefono, tramite il quale riceverà una notifica di autorizzazione in APP. Al clic di autorizzazione, l'API di ScuolaPay trasferirà l'importo pagato dal conto di pagamento dell’utente (wallet) al conto di pagamento del Business associato al POS e tornerà all'url di ritorno dove visualizzerà l'esito del pagamento.

Nel caso venga selezionato il pagamento tramite carta di credito, all’utente verranno richiesti i dati della carta e una volta completato il pagamento, tornerà all'url del ritorno dove visualizzerà l'esito del pagamento.

Nel caso venga selezionato il pagamento tramite bonifico, all'utente verranno forniti i dati per eseguire il bonifico (il sistema si salva la “prenotazione” del pagamento), tornerà all'url di ritorno ma l'esito del pagamento verrà comunicato sul pannello Business Scuolapay.

Dopo il pagamento l'utente viene rinderizzato tramite La URL di ritorno, returnURL, è una pagina del sito web/app del Business/scuola, a cui l'utente viene reindirizzato dopo il pagamento, con il parametro query string session. Usando il valore di tale parametro, si può interrogare le api server to server di SWP, per avere informazioni sulla transazione, così da poter verificare l'esito del pagamento e presentare al proprio cliente un messaggio di conferma o rifiuto della operazione.

Nuova sessione di pagamento

Per creare una sessione di pagamento bisogna effettuare una chiamata POST con payload in formato json.

Ogni movimento dovrà avere una chiave univoca per poterlo identificare, che deve soddisfare le seguenti caratteristiche:

https://webpayments-api.scuolapay.it/session

ESEMPIO NODEJS

let payload = JSON.stringify({
 "transaction": "00001",
 "amount": 1000,
 "causal": "pagamento ordine 00001",
 "returnURL": "https://business.site/esito",
 "webhookURL": "https://business.site/webhook",
 "payer": {
   "name": "Mario",
   "surname": "Rossi",
   "email": "mario.rossi@scuolapay-demo.it",
   "birthdate": "1981-01-14",
 },
 "payment": {
   "operations": [{"id": "00001-001"}, {"id": "00001-002"}],
 },
});

let config = {
 method: 'post',
 url: 'https://webpayment-api.scuolapay.it/session',
 headers: {
   'Accept-Language': 'It_it',
   'Authorization': 'Basic NjE4NDBkNTIyYWE4OTY3ZjA5ZWJmNjM5OkdrSm9QNGVSY3ZmUTkydTQ=',
   'Content-Type': 'application/json',
 },
 data : payload
};

Parametri della chiamata (i campi contrassegnati con * sono obbligatori)

*transaction: Codice che identifica il carrello o l'ordine.

*amount: Totale carrello in centesimi di Euro

*returnURL: URL (protocollo compresso), a cui va indirizzato il cliente, dopo il pagamento. ScuolaPay concatena alla URL l’identificativo della sessione di pagamento, in query string (session).

causal: Causale del pagamento, può essere utilizzata come breve descrizione all’interno del Payment Gateway

webhookURL: URL ( protocollo compresso) in cui vengono notificati i cambi di stato della sessione di pagamento. [+info]

payer.name: Nome pagante, se fornita, viene utilizzata durante il pagamento con carta di credito

payer.surname: Cognome pagante, se fornita, viene utilizzata durante il pagamento con carta di credito

payer.email: Email pagante, se fornita, viene utilizzata durante il pagamento con carta di credito

payer.birthdate: Data di nascita del pagante in formato: YYYY-MM-DD, se fornita, viene utilizzata durante il pagamento con carta di credito

payment.operations: Array di oggetti con gli identificativi delle operazioni legate all’ordine (opzionale)

payment.operations[].id: Chiave identifica della singola operazione

ESEMPIO RISPOSTA

{
 "code": 200,
 "data": {
   "url": "https://webpayment.scuolapay.it/627a236b2f1f8d00828e6a67",
 },
 "requestTime": "68ms",
}

Dentro data.url è presente il link per inviare il client al Payment Gateway di SWP

API RPC sessione di pagamento

Una volta che il Payment Gateway di SWP torna alla returnURL del sito web/app, SWP espone una API RESTful con un singolo metodo RPC al backend del sito web/app, per controllare se una sessione di pagamento è andata a buon fine o meno, attraverso la restituzione di un documento JSON, tramite il parametro session in querystring fornito alla returnURL.

Basta fare una chiamata GET al seguente indirizzo

https://webpayment-api.scuolapay.it/rpc-session/:session

ESEMPIO DI RISPOSTA

Pagamento istantaneo (senza operazioni)

{
 "code": 200,
 "session": {
   "id": "627a236b2f1f8d00828e6a67",
   "amount": 100,
   "transaction": "00001",
   "status": "completed",
 },
}

Pagamento differito (con operazioni)

{
 "code": 200,
 "session": {
   "id": "627a236b2f1f8d00828e6a67",
   "amount": 100,
   "transaction": "00001",
   "payment": {
    "operations": [{"id": "00001-001"}, {"id": "00001-002"}],
   },
   "bankwire": {
     "holder": "Scuola Demo",
     "iban": "FR0000100010001000100010011",
     "bic": "MPAYFRP1XXX",
     "reference": "SP00000001",
    },
   "status": "completed",
 },
}

Pagamento con pisp - Account-to-Account (senza operazioni)

{
 "code": 200,
 "session": {
   "id": "627a236b2f1f8d00828e6a67",
   "amount": 100,
   "transaction": "00001",
   "pisp": {
     "fingerprintId": "95dec09ca909e9be661e5d324f66542b77ec21de755ee2100dfal4e5f6a038b3",
   },
 },
}

Parametri della risposta

session.id: ID SWP della sessione di pagamento.

session.amount: Totale carrello in centesimi di Euro

session.transaction: Codice che identifica il carrello o l'ordine.

session.bankwire: Dati legati alla prenotazione del pagamento tramite bonifico (opzionale)

session.bankwire.holder: Intestatario conto

session.bankwire.iban: Iban del conto

session.bankwire.bic: Bic/swift del conto

session.bankwire.reference: Causale identificativa che deve essere utilizzata dal cliente per completare il pagamento nel suo home banking

session.status: Stato della transazione

Webhook

SWP notificherà la creazione di una nuova sessione di pagamento ed eventuali aggiornamenti di successo, fallimento o prenotazione del pagamento della sessione a questa URL. SWP fa una richiesta HTTP POST con content-type application/json.

ESEMPIO

Pagamento differito (con operazioni)

{
 "code": 200,
 "session": {
   "id": "627a236b2f1f8d00828e6a67",
   "amount": 100,
   "transaction": "t00001",
   "payment": {
     "operations": [{"id": "00001-001"}, {"id": "00001-002"}],
   },
  "bankwire": {
    "holder": "Scuola Demo",
    "iban": "FR0000100010001000100010011",
    "bic": "MPAYFRP1XXX",
    "reference": "SP00000001",
  },
   "status": "created",
 },
 "sign": "3bfb59d230b6bfe290a2a29ecd9d8b3e1b89239abd5c63acb58b7572fa9906c2",
}

Parametri della risposta

session.id: ID SWP della sessione di pagamento.

session.amount: Totale carrello in centesimi di Euro

session.transaction: Codice che identifica il carrello o l'ordine.

session.payment: Oggetto contenente informazioni legate al pagamento

session.payment.operations: Array di oggetti con gli identificativi delle operazioni legate all’ordine (opzionale)

session.payment.operations[].id: Chiave identifica della singola operazione

session.payment.bankwire: Dati legati alla prenotazione del pagamento tramite bonifico (opzionale)

session.payment.bankwire.holder: Intestatario conto

session.payment.bankwire.iban: Iban del conto

session.payment.bankwire.bic: Bic/swift del conto

session.payment.bankwire.reference: Causale identificativa che deve essere utilizzata dal cliente per completare il pagamento nel suo home banking

session.status: Stato della transazione

sign: Firma digitale del payload della risposta

Firma digitale (campo sign)

La sua funzione è quella di garantire l'integrità dei dati della sessione nella risposta. Per generarlo, basta creare un hash SHA256 con i valori serializzati dell’oggetto session nella risposta [*], come JSON, concatenata alla pass delle credenziali di basic authentication)

[*] Fare particolare attenzione al processo di serializzazione, alcuni linguaggi di programmazione non rispettano l'ordine delle key dell’oggetto serializzato, se l'ordine delle key serializzate non coincide con l'ordine delle key inoltrate nella richiesta HTTP, la verifica della firma lato SWP fallirà.

Specifiche tecniche di integrazione

Ci sono due metodi diversi di pagamento a seconda delle informazioni trasmesse dal Provider a ScuolaPay:

In entrambi i casi il Provider trasmetterà direttamente le informazioni al gateway di pagamento offerto da ScuolaPay, dove in caso di movimenti accorpati verranno fornite gli identificativi dei movimenti coinvolti all’interno della richiesta, in modo tale da tenere traccia dei movimenti che si sta pagando tramite il Payment Gateway ScuolaPay.

In entrambi i casi, il Payment Gateway restituisce l’esito del pagamento in tempo reale per i pagamenti istantanei (es. carta di credito) o in tempo differito per quelli con esito differito (bonifico bancario, Payment Initiation, ecc.).

DIAGRAMMA DI FLUSSO

Il diagramma mostra l’intero flusso di pagamento e si compone dei seguenti elementi:

Gestione esito pagamento

In caso di pagamenti con esito differito, si può concordare un periodo massimo di attesa del pagamento oltre il quale l’esito risulterà considerato fallito (es: 30gg).

Alla ricezione di un nuovo pagamento, il Payment Gateway di ScuolaPay dovrà verificare i dati ricevuti e valutare la riconciliazione delle operazioni coinvolte.

Questa fase è necessaria per via di alcune casistiche che possono avvenire:

Note

Ambiente di produzione

https://webpayment-api.scuolapay.it

Ambiente di sviluppo

https://webpayment-api-dev.scuolapay.it

Contatti

ScuolaPay

School Mission Srl

Società soggetta alla direzione e coordinamento di GrowishPay Srl

Via Doria 2 - 20834 Nova Milanese (MB)

P.IVA 11766700964

info@scuolapay.it