Panoramica Ordini Scalapay ed Errori

Errori

L'API di Scalapay utilizza i codici di stato HTTP standard per indicare il risultato delle richieste. In caso di errore, viene restituita una risposta in formato JSON con informazioni dettagliate.

Codici di Stato HTTP

Codice	Descrizione
2XX	La richiesta è andata a buon fine.
4XX	La richiesta non è valida (es. parametri obbligatori mancanti o dati non corretti).
5XX	Errore imprevisto lato server Scalapay.

Struttura della Risposta di Errore

Le risposte di errore contengono informazioni utili per diagnosticare i problemi. Anche se il messaggio in formato leggibile può cambiare nel tempo, è consigliato basarsi sul codice errore e sul codice di stato HTTP per la gestione degli errori.

Attributo	Tipo	Descrizione
`errorCode`	string	Codice identificativo dell’errore (es. `order_amount_exceeds_maximum_limit`).
`errorId`	string	Identificatore univoco dell'errore.
`message`	string	Descrizione leggibile dell’errore. Potrebbe essere aggiornata, non usarla per logica applicativa.
`httpStatusCode`	integer	Codice di stato HTTP associato all’errore.

Test del Flusso Ordine

Come effettuare un ordine di test con Scalapay

Scegli un prodotto con un importo inferiore al massimo consentito.
Compila i dati del carrello con informazioni fittizie.
Seleziona Scalapay come metodo di pagamento al checkout.
Accedi a Scalapay con un utente di test (lo stesso usato nel portale clienti, oppure creane uno nuovo).
Inserisci i dati della carta di test (vedi sotto) per completare l’ordine.
Verifica di essere stato reindirizzato correttamente alla pagina di conferma del tuo sito.

Carte di Test

Carte per Test con Esito Positivo

5200 8282 8282 8210
5555 5555 5555 4444
4242 4242 4242 4242

Carte per Test con Esito Negativo

4000 0000 0000 0341
4000 0000 0000 0002
4000 0000 0000 9995

Per tutte:

CVV: qualsiasi codice (es. 123)
Data di scadenza: qualsiasi data futura
CAP: qualsiasi CAP valido

Le carte indicate sono tutte funzionanti, si possono provare in modo alternato.

Stato dell'Ordine

Ogni ordine ha due tipologie di stato: Order Status e Capture Status.

Order Status

Stato	Descrizione
`pending`	L’ordine è stato creato ma non ancora autorizzato dal cliente. Rimane in questo stato per 40 minuti se non viene completato.
`expired`	L’ordine è scaduto senza autorizzazione da parte del cliente.
`refunded_not_charged`	L’ordine è scaduto ma era stato autorizzato. Non è stato effettuato il capture.
`charged`	L’ordine è stato catturato correttamente.
`partially_refunded`	L’ordine è stato rimborsato parzialmente.
`refunded`	L’intero importo dell’ordine è stato rimborsato.

Capture Status

Stato	Descrizione
`pending`	L’ordine non è stato ancora catturato.
`captured`	L’ordine è stato catturato correttamente.
`delayed`	Il capture è stato ritardato (default: 5 giorni).
`voided`	L’ordine è stato annullato prima del capture.

Puoi scaricare un file con la combinazione degli status da questo link: [Order Status and Capture Status.pdf].

Visualizzazione degli Ordini nel Portale Venditore

Nella sezione Ordini del portale venditore, gli ordini vengono visualizzati con i seguenti status:

Paid (charged) – Ordine finalizzato con successo
Authorized – Visibile solo temporaneamente; se completato passa a "Paid", altrimenti scade e non appare più
Refunded / Partially Refunded – Ordini rimborsati, con dettagli dell’importo

Nota Bene: gli ordini in stato refunded_not_charged e expired non vengono mostrati nel backend.

Gli ordini Expired non indicano errori tecnici, ma semplicemente ordini abbandonati o rifiutati dalla banca del cliente. Per motivi di privacy, Scalapay non può fornire le ragioni del rifiuto.

Gli ordini Refunded_not_Charged sono invece dovuti a problemi tecnici.

Verifiche in caso di Refunded_not_Charged

Integrazione Custom:
- Verifica che il flusso implementato sia corretto.
- Consulta la documentazione ufficiale a questo link: [Link alla documentazione].
- Controlla che la chiamata di Cattura dell’Ordine sia presente e venga eseguita al momento giusto: quando l’ordine è in stato authorized (verificabile con GET ORDER o via Webhook).
- Se usi la chiamata di Delay, verifica che il campo authorizationExpiryMilliseconds sia stilato come segue:

{ "authorizationExpiryMilliseconds": 
432000000 }

Integrazione tramite Plugin:
- Verifica che la versione del plugin sia aggiornata: [Link Changelog].
- Controlla che nel plugin il campo Order Status: Payment Complete sia impostato correttamente come da documentazione. Se modificato, il flusso potrebbe non completarsi.
- Scegli la tua piattaforma a questo link: [Documentazione] per controllare gli screen e i valori corretti.

Integrazione tramite Shopify:
- Consulta questo link alla documentazione: [Shopify Documentation] per verificare le impostazioni o configurare correttamente la cattura ritardata.