Integrazione Cloud API

Con una integrazione cloud, il tuo software POS e il terminale di pagamento comunicano tra loro tramite internet – non è necessario alcun cavo fisico o connessione locale.

Come funziona (alto livello):

1. Il software POS invia una richiesta di pagamento alla piattaforma Market Pay.

2. La piattaforma Market Pay inoltra questa richiesta al terminale di pagamento.

3. Il terminale gestisce l'interazione con il cliente ed elabora il pagamento.

4. Il risultato viene inviato indietro tramite la piattaforma.

5. Il tuo software POS riceve lo stato finale della transazione.

Questo approccio rende la configurazione più semplice, flessibile e facilmente scalabile su più dispositivi.

Configurazione della comunicazione sicura

Prima che il tuo ECR possa scambiare messaggi con il terminale di pagamento, deve essere presente un certificato sicuro:

1. Crei una Certificate Signing Request (CSR) e la invii a Market Pay (al tuo implementation manager)

2. Il team Market Pay AppOps emette il certificato e te lo restituisce.

3. Installi il certificato sul tuo sistema.

👉 Leggi la guida passo-passo per la configurazione del certificato

Configura la tua rete

Assicurati che la tua rete e il firewall consentano il traffico HTTPS in uscita verso i servizi Market Pay e gli endpoint dei partner. Metti in whitelist gli IP e le porte TCP di seguito affinché le app POS e i terminali possano raggiungere i servizi necessari.

• NTMS – Terminal Management System: Gestisce impostazioni e aggiornamenti.

• MPG – Market Pay Gateway: Elabora e instrada tutte le transazioni.

• RKI – Remote Key Injection: Gestisce le chiavi di crittografia da remoto.

👉 Consulta l'elenco completo dei requisiti di configurazione di rete

Comunicazione POS ↔ Terminale

Il tuo ECR comunica con il terminale utilizzando i seguenti endpoint API:

Qui troverete le specifiche dettagliate: api-hub.market-pay.com

1. POST /process-transaction

• Cosa fa: Avvia un nuovo pagamento e mostra la schermata di pagamento sul terminale.

• Come funziona: Gli aggiornamenti di stato (carta inserita, PIN inserito, pagamento autorizzato) vengono inviati all'URL di notifica configurato.

• Quando usarlo: Ogni volta che un cassiere avvia un pagamento.

👉 Consulta la documentazione dettagliata per /process-transaction

2. GET /last-transaction

• Cosa fa: Recupera il risultato della transazione più recente.

• Come funziona: Aiuta a recuperare i risultati se il POS ha perso la connessione. Controlla sempre il transactionId per assicurarti di associare la richiesta corretta.

• Quando usarlo: Se il tuo POS non ha ricevuto un risultato e devi confermare cosa è successo.

👉 Consulta la documentazione dettagliata per /last-transaction

3. POST /cancel-transaction/{terminal-id}

Cosa fa:
Annulla un pagamento precedentemente eseguito con successo effettuando una revoca della transazione.

Come funziona:
Il terminale invia una richiesta di revoca all'acquirer. Gli aggiornamenti di stato (avviato, in corso, completato) vengono inviati al tuo URL di notifica.

Quando usarlo:
Usalo quando un pagamento è stato effettuato per errore o deve essere annullato prima della chiusura.

👉 Consulta la documentazione dettagliata per /cancel-transaction

4. POST /update-terminal

• Cosa fa: Richiede al terminale di aggiornare il proprio software o la configurazione.

• Quando usarlo: Durante i rollout, la manutenzione o prima di introdurre nuove funzionalità.

👉 Consulta la documentazione dettagliata per /update-terminal

5. POST /abort-transaction

• Cosa fa: Annulla una transazione in corso.

• Come funziona: Se la richiesta arriva in tempo, la transazione viene interrotta. Se arriva troppo tardi, il terminale potrebbe comunque completarla; in tal caso, il POS deve inviare un Rimborso.

• Quando usarlo: Se un cliente o un cassiere decide di annullare prima del completamento.

👉 Consulta la documentazione dettagliata per /abort-transaction

6. GET /terminals

• Cosa fa: Elenca tutti i terminali collegati per un determinato codice negozio.

• Come funziona: Restituisce una risposta vuota se non ci sono sessioni attive.

• Quando usarlo: All'avvio del POS, per controllare quali terminali sono disponibili.

👉 Consulta la documentazione dettagliata per /get-terminals

7. Come generare la tua CSR (Certificate Signing Request)

Per ottenere il tuo certificato, devi generare una CSR (Certificate Signing Request) e una chiave privata utilizzando OpenSSL.

1. Genera la CSR e la chiave privata

Utilizza il seguente comando a seconda dell'ambiente:

Per pre-produzione:

openssl req -nodes -newkey rsa:2048 -keyout POS_MerchantName_PREPROD_PRIVATEKEY.key -out POS_MerchantName_PREPROD_CSR.csr

Per produzione:

openssl req -nodes -newkey rsa:2048 -keyout POS_MerchantName_PROD_PRIVATEKEY.key -out POS_MerchantName_PROD_CSR.csr

Sostituisci MerchantName con il tuo identificativo merchant effettivo (es. POS_MyShop_PREPROD_PRIVATEKEY.key).

2. Compila le informazioni richieste

Quando richiesto dal comando OpenSSL, compila i seguenti campi:

⚠️ Assicurati che il campo Organizational Unit (OU) indichi chiaramente l'uso del certificato — questa informazione è obbligatoria.

Gli altri campi possono essere lasciati vuoti.

3. Invia il file CSR

Una volta generata la CSR, invia il file .csr al tuo referente Market Pay.
Non inviare il file .key — conservalo in modo sicuro.

4. Facoltativo (solo test)

Puoi anche generare una CSR utilizzando uno strumento online (non raccomandato per la produzione):
👉 Online CSR and Key Generator – SSL.com