Avvio rapido: il tuo primo pagamento

Questo avvio rapido ti guida da un terminale connesso a un pagamento con carta completato tramite l'API Cloud. Il tuo POS invia una richiesta REST alla piattaforma Market Pay tramite internet, e la piattaforma la inoltra al terminale.

URL base:

• Produzione — https://eci.market-pay.com
• Pre-produzione — https://eci-stg.market-pay.com

Strumento demo: per permetterti di testare la nostra implementazione (accesso log)

https://cloud-api-pos-demo.onrender.com/

1. Verifica che il terminale sia online

GET /terminals elenca i terminali attualmente connessi per il codice del tuo negozio. Se il tuo terminale non è nella lista, non è raggiungibile — consulta la sezione Risoluzione dei problemi prima di procedere.

2. Effettua un pagamento

POST /process-transaction/{terminal-id}. Gli importi sono in unità minori (1000 = €10,00) e la valuta è un codice numerico ISO 4217 (978 = EUR):

POST https://eci.market-pay.com/process-transaction/PAX:1760019815?waitTime=20

{
  "transactionType": "PURCHASE",
  "amount": 1000,
  "currency": 978,
  "ecrTransactionId": "ticket-0001",
  "ecrParams": {
    "ecrId": "POS-01",
    "notificationUrl": "https://mypos.example.com/notifications",
    "printerAvailable": true,
    "operatorLanguage": "EN"
  }
}

3. Ricevi il risultato

Ci sono due modi in cui il risultato viene restituito, controllati dal parametro di query waitTime (in secondi):

• Sincrono — se la transazione termina entro waitTime, la chiamata restituisce 201 con il TransactionResult.
• Asincrono — se impiega più tempo, la chiamata restituisce 202 Accepted e il risultato viene inviato al tuo notificationUrl. Aggiornamenti di stato (WAITING_FOR_CARD, PIN_REQUIRED, BANK_AUTHORIZATION, COMPLETED) vengono inviati lì durante tutto il processo. Vedi Notifiche e il modello asincrono.

status: OK e responseCode: "000" significano che il pagamento è stato approvato. Conserva terminalTransactionId — ti serve per annullare il pagamento o completare una pre-autorizzazione.

Regole che prevengono fallimenti silenziosi

• L’ID terminale è case-sensitive — il prefisso del produttore deve essere MAIUSCOLO (PAX:…, non pax:…), altrimenti la chiamata restituisce 404.
• currency deve corrispondere alla valuta configurata nel terminale — una discrepanza viene rifiutata con 404.
• ecrTransactionId può contenere al massimo 35 caratteri — valori più lunghi vengono respinti.
• Gli importi sono in unità minori — 1000 corrisponde a €10,00, non €1000.