Connettore Sna Pay – API

Il primo aggregatore bancario per i pagamenti da remoto

Sna Pay è un aggregatore bancario nato da Italia On Site e Plurisoft per il sindacato SNA.
Il progetto Sna Pay nasce per:

  • Incassare da remoto pagamenti 24 ore su 24 inviando link al cliente finale via mail e/o SMS
  • Difendere la centralità del ruolo di agente riducendo il rischio di disintermediazione
  • Aumentare la redditività di agenzia con risultati tracciabili sempre aggiornati
    L’aggregatore Sna Pay è predisposto per essere utilizzato manualmente anche in mancanza di collegamento ad altre piattaforme software.
    Su grandi volumi di transazioni bancarie performa al suo meglio con un collegamento tramite REST API verso altri gestionali proprietari, automatizzando tutto il processo.
    Trattandosi di pagamenti da remoto (pay-by-link) il cliente finale dell’intermediario riceve tramite mail e/o SMS un link di pagamento con scadenza determinata dall’agente.
    Per creare uno o più link di pagamento è necessario configurare il “lotto” che è il contenitore dei diversi link.

Indice API

API Sna Pay

Chiamate Connettore SnaPay

Autore: Avolio Sergio (ItaliaOnSite s.r.l.)
Versione 1.4 del 15/03/2021
Chiave univoca di connessione: Generata all’interno del gestionale
Tipo di chiamata: POST
Content Type: application/x-www-form-urlencoded
Tipo di risposta; JSON

Il sistema Sna Pay è composto da un’interfaccia WEB e una REST API.
Per poter utilizzare l’API è necessario prima configurare una nuova utenza all’indirizzo https://snapay.erpweb.it [piattaforma di test]
Dopo aver registrato la propria utenza, bisogna acquistare il o i circuiti di pagamento e configurarlo all’interno del sistema.
Una volta configurato il sistema sarà possibile ottenere la chiave personale per utilizzare il webservice messo a disposizione.
L’utilizzo del webservice permetterà di generare i link e riportarli all’interno di propri gestionali, che avranno la possibilità di generare e mantenere i link di pagamento.
Tutti i link generati sono compresi in un contenitore chiamato lotto.
Il lotto ha una data di scadenza che corrisponde con la scadenza di tutti i link al suo interno. La lista dei link da generare non verrà rielaborata, non verranno raggruppati i link generati, come invece può accadere con l’interfaccia web (se configurata l’opzione “raggruppa per Codice fiscale o partita IVA).

Changelog

VersioneDataCambiamenti
1.415/03/2021– Aggiunta chiamata get_payments
– Lista pagamenti, campo id_esterno esteso a 1000 caratteri
– Lista pagamenti, campo causale esteso a 500 caratteri
– Lista pagamenti, aggiunto campo partita_iva
– Lista pagamenti, aggiunto campo codice_fiscale

Collegamenti

Sistema di test:

Handpoint: https://snapay.erpweb.it/api/CHIAMATA

Sistema in produzione:

Handpoint: https://aggregatore.snapay.it/api/CHIAMATA

Chiamate Connettore SnaPay:

set_data: in cui si può creare un nuovo lotto e passare l’array JSON con i dati dei pagamenti da effettuare

get_data: in cui si ottengono i dati sui pagamenti caricati con la precedente chiamata e il loro stato pagamento

update_data: per aggiornare i dati dei pagamenti

get_payments: in cui si può ottenere la lista di tutti i pagamenti ricevuti dalla data specificata

Chiamata set_data

Chiamata dai sistemi di agenzia per inserire un nuovo lotto e i pagamenti collegati, così da generare i link di pagamento:

INPUT Chiamata set_data

OUTPUT chiamata set_data

OUTPUT chiamata set_data: JSON set_pagamenti

ESEMPIO CURL

CURL Chiamata set_data

curl -d “chiave=xxx&pagamenti=[{\”id_esterno\”: \”123\”,\”nominativo\”: \” nome e cognome 1\”,\”partita_iva\”: \”0123456789\”,\”codice_fiscale\”: \”CDCFSC01A01A000B\”,\”polizza\”: \”P0001\”,\”causale\”: \”Pagamento polizza P001 del 20/11/2020\”,\”data_scadenza\”: \”2020-11-20\”,\”importo\”: \”180.00\”,\”email\”: \”mail@mail.it\”,\”cellulare\”: \”\”,\”metodo_pagamento\”: \”nexi\”},{\”id_esterno\”: \”122\”,\”nominativo\”: \”nome e cognome 2\”,\”partita_iva\”: \”0123456789\”,\”codice_fiscale\”: \”CDCFSC01A01A000B\”,\”polizza\”: \”P0002\”,\”causale\”: \”Pagamento polizza P002 del 22/11/2020\”,\”data_scadenza\”: \”2020-11-22\”,\”importo\”: \”170.00\”,\”email\”: \”mail2@mail.it\”,\”cellulare\”: \”\”,\”metodo_pagamento\”: \”multisafepay\”}]” https://snapay.erpweb.it/api/set_data.php

JSON risposta set_data

{“status”:0,”nome_lotto”:”Lotto 16 del 24\/02\/2021″,”data_creazione”:”2021-02-24″,”data_chiusura”:”2021-03-08″,”id_lotto”:”75577xxx”}

Chiamata get_data

Chiamata dai sistemi di agenzia per ricevere tutti i dati dei pagamenti di un lotto inserito con la chiamata precedente.
Verranno riportati tutti i pagamenti presenti nel lotto indipendentemente dal loro stato.

INPUT Chiamata get_data

OUTPUT Chiamata get_data

OUTPUT Chiamata get_data: JSON get_pagamenti

ESEMPIO CURL

CURL Chiamata get_data

curl -d “chiave=xxx&id_lotto=75577xxx ” https://snapay.erpweb.it/api/get_data.php

JSON risposta get_data

{“status”:0,”id_lotto”:”75577xxx “,”pagamenti”:[{“status_pagamento”:”1″,”id_esterno”:”123″,”nominativo”:” nome e cognome 1″,”partita_iva”:”0123456789″,”codice_fiscale”:”CDCFSC01A01A000B”,”polizza”:”P0001″,”causale”:”Pagamento polizza P001 del 20\/11\/2020″,”data_scadenza”:”2020-11-20″,”importo”:”180″,”email”:”mail@mail.it”,”cellulare”:””,”metodo_pagamento”:”2″,”data_pagamento”:null,”link_pagamento”:”https:\/\/snapay.erpweb.it\/api\/?&v=c20d8a3284f4958ec05cc7b655b0b4b3″},{“status_pagamento”:”1″,”id_esterno”:”122″,”nominativo”:”nome e cognome 2″,”partita_iva”:”0123456789″,”codice_fiscale”:”CDCFSC01A01A000B”,”polizza”:”P0002″,”causale”:”Pagamento polizza P002 del 22\/11\/2020″,”data_scadenza”:”2020-11-22″,”importo”:”170″,”email”:”mail2@mail.it”,”cellulare”:””,”metodo_pagamento”:”2″,”data_pagamento”:null,”link_pagamento”:”https:\/\/snapay.erpweb.it\/api\/?&v=f08d4497eeacba0e3f21a53d3d605acd”}]}

Chiamata update_data

Chiamata dai sistemi di agenzia per aggiornare i dati di un pagamento. Tutti i dati non presenti nell’array JSON update_pagamenti non verranno aggiornati.

INPUT Chiamata update_data

OUTPUT Chiamata update_data

OUTPUT Chiamata update_data: JSON update_pagamenti

ESEMPIO CURL

Curl chiamata update_data

curl -d “chiave=xxx&id_lotto=75577xxx&pagamenti=[{\”id_esterno\”: \”123\”,\”nominativo\”: \” nome e cognome nuovo\”},{\”id_esterno\”: \”122\”,\”metodo_pagamento\”: \”multisafepay\”}]” https://snapay.erpweb.it/api/update_data.php

JSON risposta update_data

{“status”:0,”id_lotto”:”75577xxx “}

Chiamata get_payments

Chiamata dai sistemi di agenzia per ottenere la lista dei pagamenti ricevuti dalla data e ora indicata. La lista verrà suddivisa per lotto

INPUT Chiamata get_payments

OUTPUT Chiamata get_payments

OUTPUT Chiamata get_payments: JSON get_payments_pagamenti

ESEMPIO CURL

Curl chiamata get_payments

curl -d “chiave=xxx&data=2021-03-11 12:00” https://snapay.erpweb.it/api/get_payments.php

JSON risposta

Curl chiamata get_payments

{“status”:0,”pagamenti”:[{“id_lotto”:”75577xxx”, “status_pagamento”:”5″, “id_esterno”:”123″, “nominativo”:”nome e cognome 1″, “partita_iva”:”0123456789″, “codice_fiscale”:”CDCFSC01A01A000B”, “polizza”:”P0001″, “causale”:”Pagamento polizza P001 del 20\/11\/2020″, “data_scadenza”:”2020-11-20″, “importo”:”180″, “email”:”mail@mail.it”, “cellulare”:””, “metodo_pagamento”:”nexi”, “data_pagamento”:”2021-03-09 11:07:16″, “link_pagamento”:”https:\/\/snapay.erpweb.it\/api\/?&v=e0d31115e431ee99a5162c1cda968220″}] }

Codici Status

Casi d’uso

Caso d’uso 1 (crea e aggiorna lotto con pagamenti):

1. Si effettua la chiamata “set_data”, passando il JSON con i link da creare. Il sistema crea i link e restituisce l’id univoco del lotto, oltre al nome e alle date di apertura e chiusura. Tutti i link generati all’interno di questo lotto scadranno nella data di chiusura lotto. La data di chiusura lotto non è più modificabile.

2. Si effettua la chiamata “get_data” con l’id univoco del lotto ottenuto nella chiamata precedente per ottenere la lista completa dei pagamenti contenuti nel lotto, comprensiva di link generato e status pagamento. La chiamata “get_data” deve essere eseguita ogni volta che si vuole sapere quali pagamenti sono stati ricevuti nel lotto, scaricando sempre l’array completo.

3. Si effettua la chiamata “update_data” per modificare, annullare o rigenerare un link all’interno del lotto. Bisognerà inserire il JSON dei soli dati da modificare.

4. Si effettua la chiamata “get_data” con l’id univoco del lotto gestito nei precedenti passaggi per ottenere la lista con i link aggiornati nel passaggio 3

Caso d’uso 2 (crea lotto e scarica solo i pagamenti):

1. Si effettua la chiamata “set_data”, passando il JSON con i link da creare. Il sistema crea i link e restituisce l’id univoco del lotto, oltre al nome e alle date di apertura e chiusura. Tutti i link generati all’interno di questo lotto scadranno nella data di chiusura lotto. La data di chiusura lotto non è più modificabile.

2. Si effettua la chiamata “get_data” con l’id univoco del lotto ottenuto nella chiamata precedente per ottenere la lista completa dei pagamenti contenuti nel lotto, comprensiva di link generato e status pagamento. La chiamata “get_data” deve essere eseguita ogni volta che si vuole sapere quali pagamenti sono stati ricevuti nel lotto, scaricando sempre l’array completo.

3. (Ripetere sempre) Si effettua la chiamata “get_payments” con data dell’ultima volta che è stata effettuata la chiamata “get_payments”. Il sistemerà generà una lista di pagamenti ricevuti dalla data indicata. Ogni pagamneto comprenderà anche l’id del lotto contenitore