Tag: API di pagamento PrestaShop

Integrare un gateway di pagamento in PrestaShop può sembrare semplice sulla carta.

Il gateway fornisce la documentazione API, le credenziali di accesso alla sandbox, le chiavi di autenticazione, gli URL di callback e alcuni endpoint. Il modulo PrestaShop invia quindi la richiesta di pagamento, riceve la risposta, crea l’ordine e reindirizza il cliente alla pagina di conferma.

In un vero negozio PrestaShop, tuttavia, il gateway di pagamento raramente funziona da solo.

Nel momento in cui un negozio utilizza un modulo One Page Checkout (OPC) come SuperCheckout, più moduli di pagamento, flussi di pagamento personalizzati, iframe, metodi di pagamento basati su JavaScript e ulteriori personalizzazioni del checkout possono interagire tra loro.

È proprio qui che molte integrazioni di pagamento diventano complesse.

Durante i lavori di compatibilità con i gateway di pagamento, abbiamo riscontrato casi in cui un metodo di pagamento funzionava perfettamente con il checkout predefinito di PrestaShop, ma si comportava in modo diverso all’interno di OPC. Ad esempio, un fornitore di pagamento poteva essere visualizzato correttamente nel checkout standard, mentre opzioni come BLIK, selezione della banca o BNPL (Buy Now Pay Later) scomparivano all’interno di SuperCheckout.

La lezione più importante è stata che integrare un gateway di pagamento non significa solo far funzionare la chiamata API, ma far sì che l’intero ciclo di pagamento funzioni correttamente all’interno del checkout di PrestaShop.

1.0 Di cosa ha effettivamente bisogno un gateway di pagamento personalizzato?

A grandi linee, un’integrazione di pagamento per PrestaShop deve gestire cinque aspetti:

1. Visualizza il metodo di pagamento al momento del checkout.
2. Invia i dati del cliente o di pagamento al gateway.
3. Ricevere e convalidare la risposta del gateway.
4. Creare o aggiornare correttamente l’ordine PrestaShop.
5. Reindirizzare il cliente alla pagina di conferma o di errore appropriata.

Un tipico modulo di pagamento estende la classe base anziché la classe base.

Il modulo di pagamento funziona normalmente con hook come:

Il componente hook ha il compito di rendere disponibile il metodo di pagamento al momento del checkout.

Il hook gestisce ciò che il cliente vede dopo essere tornato dalla procedura di pagamento.

Per esempio:

public function hookPaymentOptions($params) { if (!$this->active || !$this->checkCurrency($params['cart'])) { return []; } $paymentOption = new PaymentOption(); $paymentOption ->setCallToActionText($this->l('Paga con carta')) ->setAction( $this->context->link->getModuleLink( $this->name, 'redirect', [], true ) ); return [$paymentOption]; }

Il punto fondamentale è che questo hook non deve dare per scontato che il metodo di pagamento sia sempre visibile.

Valuta, paese, corriere, stato del cliente, importo del carrello, configurazione del modulo e disponibilità del gateway possono influire sulla visualizzazione del metodo di pagamento.

2.0 La parte che cambia tutto: OPC

Il sistema di pagamento predefinito di PrestaShop e un modulo OPC non elaborano necessariamente i metodi di pagamento esattamente allo stesso modo.

Questa è stata una delle lezioni più importanti apprese lavorando con diversi moduli di pagamento.

Con la procedura di pagamento predefinita, un modulo di pagamento generalmente gestisce autonomamente la visualizzazione delle opzioni di pagamento e il flusso di pagamento.

Con un OPC, il modulo di checkout diventa un ulteriore livello tra il modulo di pagamento e il cliente. Ciò significa che possono interagire i seguenti elementi:

 
↓
OPC / SuperCheckout
↓
Opzioni di pagamento
↓
Modulo di pagamento
↓
API del gateway
↓
Risposta del gateway
↓
Modulo di pagamento
↓
OPC / PrestaShop
↓
Conferma dell'ordine

Un modulo di pagamento può quindi essere perfettamente corretto dal punto di vista dell’API e tuttavia non funzionare correttamente all’interno di un OPC.

Ecco perché i test di compatibilità dei pagamenti dovrebbero sempre includere entrambi:

• Checkout predefinito di PrestaShop
• L’OPC effettivamente utilizzato dal negozio

Testare solo la procedura di pagamento predefinita può dare la falsa impressione che l’integrazione sia completa.

3.0 Un esempio concreto: opzioni PayU mancanti all’interno di OPC

Uno dei problemi pratici che abbiamo riscontrato riguardava le opzioni di pagamento di PayU.

Nella pagina di pagamento standard di PrestaShop, PayU visualizzava correttamente i metodi di pagamento disponibili. Tuttavia, all’interno di SuperCheckout, alcune opzioni di pagamento risultavano mancanti.

Ad esempio, a seconda della configurazione e del carrello:

• BLIK non era sempre visibile.
• L’elenco di selezione delle banche non si è espanso correttamente.
• Mancavano alcune righe relative al pagamento/BNPL (Buy Now Pay Later).
• In alcuni casi, BLIK appariva e poi scompariva.

A prima vista, sembrava un problema dell’API di PayU. Non lo era.

La fase diagnostica fondamentale consisteva nel confrontare il flusso di pagamento tra la procedura di pagamento standard e SuperCheckout.

Quando lo stesso modulo di pagamento funziona nella procedura di pagamento predefinita ma non all’interno di OPC, l’indagine dovrebbe estendersi oltre l’API del gateway.

Dobbiamo verificare come l’OPC crea i metodi di pagamento e quali informazioni trasmette ai moduli di pagamento.

4.0 L’importo del pagamento può influire sulla visibilità del metodo di pagamento

Un aspetto particolarmente importante di questa indagine è stato l’importo del carrello. I gateway di pagamento spesso prevedono limiti minimi e massimi per le transazioni. Ad esempio:

Metodo di pagamento
↓
Verifica l'importo nel carrello
↓
Importo minimo? Importo massimo?
↓
Idoneo / Non idoneo

Durante l’indagine sulla compatibilità di PayU, abbiamo rintracciato la logica di filtraggio del metodo di pagamento fino all’importo del carrello che veniva elaborato dai controlli del metodo di pagamento.

Il flusso rilevante comprendeva il calcolo del carrello e il filtraggio del metodo di pagamento di PrestaShop, inclusa la logica relativa a:

Carrello::ENTRAMBI

e:

PayMethodsCache::checkMinMax

Questo è importante perché un’opzione di pagamento può scomparire dalla pagina di pagamento senza che l’API stessa restituisca un errore.

Il gateway potrebbe semplicemente essere considerato non idoneo per l’importo ricevuto dal modulo di pagamento. Questo ci fornisce un’importante regola di debug:

Se un’opzione di pagamento scompare da un OPC, non dare subito per scontato che l’API di pagamento sia guasta. Verifica prima l’importo del carrello, la valuta, i limiti minimi/massimi e i valori che raggiungono i controlli di idoneità del metodo di pagamento.

Questo aspetto diventa ancora più importante quando sono coinvolti sconti, costi di spedizione, tasse, buoni o calcoli personalizzati al momento del pagamento.

5.0 Perché i metodi di pagamento funzionano nel checkout predefinito ma non in SuperCheckout

Un metodo utile per analizzare questi problemi consiste nel confrontare i due ambienti di pagamento.

5.1 Checkout predefinito di PrestaShop

Carrello
↓
Ricerca opzioni di pagamento
↓
hook paymentOptions
↓
Moduli di pagamento
↓
Opzioni di pagamento

5.2 Verifica OPC

Carrello
↓
SuperCheckout
↓
Metodi di pagamento
↓
Moduli di pagamento
↓
Elaborazione OPC aggiuntiva
↓
Interfaccia utente di pagamento visualizzata

Il secondo flusso presenta parti mobili aggiuntive.

Pertanto, quando si esegue il debug di un problema di pagamento, non ci limitiamo a verificare: “Il modulo di pagamento funziona?”

Controlliamo: “Il modulo di pagamento funziona correttamente quando il suo output viene elaborato e visualizzato da questa specifica implementazione del sistema di pagamento?”

Tale distinzione ha permesso di risparmiare una notevole quantità di tempo nella fase di debug.

6.0 L’opzione di pagamento è solo una parte dell’integrazione

A partire da PrestaShop 1.7, i moduli di pagamento utilizzano generalmente l’output HTML per i pagamenti tramite il vecchio approccio basato sugli hook di pagamento.

Un’opzione di pagamento può contenere informazioni quali:

Opzione di pagamento
->setCallToActionText(...)
->setAction(...)
->setInputs(...)
->impostaInformazioniAggiuntive(...)

oggetti invece di direttamente

Gateway diversi richiedono combinazioni diverse.

6.1 Gateway basato sul reindirizzamento

Il cliente clicca sul metodo di pagamento e viene reindirizzato al gateway.

Concludi ordine
↓
Opzione di pagamento
↓
Controller del modulo
↓
Gateway

6.2 Modulo di pagamento incorporato

I campi di pagamento vengono visualizzati direttamente nella pagina di checkout.

Concludi ordine
↓
Opzione di pagamento
↓
Modulo di carta/pagamento
↓
API del gateway

6.3 Pagamento basato su iframe

L’interfaccia del gateway è integrata nella procedura di pagamento.

Concludi ordine
↓
Opzione di pagamento
↓
Iframe
↓
Gateway

Gli ultimi due approcci richiedono maggiore attenzione perché JavaScript, la manipolazione del DOM, il caricamento degli iframe e gli aggiornamenti OPC possono influire sull’interfaccia di pagamento.

7.0 JavaScript diventa fondamentale con OPC

Questo è un aspetto che le guide generiche all’integrazione dei sistemi di pagamento spesso trascurano.

Un OPC può aggiornare dinamicamente alcune parti del processo di checkout quando il cliente apporta delle modifiche:

• indirizzo di consegna
• nazione
• vettore
• metodo di pagamento
• Informazioni di fatturazione
• metodo di spedizione

In tal caso, il codice HTML relativo ai pagamenti può essere sostituito.

Un evento JavaScript che funzionava correttamente durante il caricamento iniziale della pagina potrebbe quindi smettere di funzionare dopo un aggiornamento AJAX.

Per esempio:

Carico di checkout iniziale
↓
Inizializzazione del codice JavaScript di pagamento
↓
Il cliente modifica le informazioni di pagamento/spedizione
↓
L'OPC aggiorna la sezione pagamenti
↓
DOM originale sostituito
↓
Il codice JavaScript di pagamento non è più allegato.

Ciò può produrre sintomi fuorvianti.

Il metodo di pagamento potrebbe apparire inizialmente, ma cliccandoci sopra non succede nulla. Un iframe potrebbe scomparire.

L’elenco delle banche potrebbe smettere di espandersi.

Un’opzione di pagamento potrebbe apparire e scomparire in seguito alla modifica di un altro campo durante la procedura di pagamento.

Pertanto, gli interventi di compatibilità spesso richiedono modifiche non solo al codice PHP, ma anche al codice JavaScript del modulo di pagamento.

8.0 Un esempio concreto: SimplyLease + SuperCheckout

Un altro esempio riguardava l’integrazione di SimplyLease con SuperCheckout. Il problema non si limitava all’API del gateway.

Alcune informazioni di SimplyLease e alcuni elementi del calcolatore erano inclusi nella presentazione di pagamento e dovevano funzionare correttamente all’interno del flusso SuperCheckout.

Le modifiche di compatibilità hanno interessato sia i modelli dei moduli che l’integrazione JavaScript lato SuperCheckout. I file coinvolti includono:

modules/simplylease/views/templates/hook/payment_info.tpl modules/simplylease/views/templates/hook/product_calculator.tpl

modules/supercheckout/controllers/front/SupercheckoutCore.php modules/supercheckout/views/js/front/supercheckout.js
modules/supercheckout/views/js/front/simplylease_supercheckout.js

Questo è un buon esempio del perché la compatibilità dei pagamenti a volte richiede modifiche al di fuori del modulo del gateway di pagamento stesso.

Il fornitore di servizi di pagamento può esporre i dati corretti, ma il checkout deve comunque:

1. Esegui il rendering.
2. Conservalo durante gli aggiornamenti della pagina di pagamento.
3. Inizializza il codice JavaScript necessario.
4. Mantieni sincronizzate le informazioni di pagamento con il carrello corrente.

9.0 Un altro problema comune: il metodo di pagamento non viene visualizzato

Abbiamo inoltre riscontrato casi in cui un metodo di pagamento come Comfino non compariva in SuperCheckout, nonostante il modulo di pagamento fosse installato e configurato correttamente.

Questo tipo di problema dovrebbe essere indagato in modo sistematico.

Dai un’occhiata:

9.1 Il modulo è attivo?

$this->active

9.2 La valuta è supportata?

$this->checkCurrency($params['cart'])

9.3 Il Paese è sostenuto?

Alcuni gateway limitano i metodi di pagamento in base al paese del cliente.

9.4 L’importo totale del carrello rientra nei limiti previsti dal gateway di pagamento?

I valori minimi e massimi delle transazioni possono impedire la visualizzazione di un metodo.

9.5 Il vettore è supportato?

Alcuni moduli di pagamento limitano i metodi di pagamento in base all’operatore telefonico.

9.6 Il filtraggio OPC è il metodo?

Il modulo di pagamento può restituire metodi validi che vengono raccolti, filtrati o visualizzati. Ma l’OPC può ancora modificare le modalità di pagamento

9.7 JavaScript sta nascondendo o sostituendo l’elemento?

Un metodo di pagamento può essere tecnicamente restituito da PHP, ma non essere comunque visibile nella pagina di pagamento finale.

Ecco perché gli strumenti per sviluppatori del browser sono importanti quanto i log PHP durante il debug delle integrazioni di pagamento.

10.0 Agganci a cui dobbiamo assolutamente prestare attenzione

Un’integrazione di pagamento personalizzata non dovrebbe essere considerata come un’implementazione a singolo hook.

I punti di aggancio specifici dipendono dall’architettura del gateway e del processo di pagamento, ma alcuni sono particolarmente importanti.

10.1 Opzioni di pagamento

Questo è il principale elemento che permette di visualizzare il metodo di pagamento al momento del checkout.

È responsabile del ritorno opzioni di pagamento oggetti.

I controlli tipici includono:

se (!$this->active) { restituisci [];
}
se (!$this->checkCurrency($params['cart'])) { restituisci [];
}

Successivamente, possono essere applicate ulteriori restrizioni specifiche per ciascun gateway.

10.2 Resi di pagamento

Viene utilizzato dopo che il cliente ha completato o è tornato dal flusso di pagamento. Può visualizzare:

• riferimento dell’ordine
• stato del pagamento
• istruzioni di pagamento aggiuntive
• informazioni specifiche del gateway

10.3 actionPresentPaymentOptions

Questo aggancio diventa particolarmente interessante quando sono coinvolti più moduli di pagamento e un OPC.

Funziona sulle opzioni di pagamento raccolte e può essere utile quando il sistema di pagamento deve esaminare o modificare l’intera raccolta di opzioni di pagamento.

Questo è diverso dall’implementazione delle opzioni di pagamento di un singolo gateway gancio.

La distinzione è importante:

Opzioni di pagamento
↓
Ogni modulo di pagamento contribuisce con la sua opzione
azionePresentPaymentOptions
↓
Le opzioni di pagamento assemblate possono essere elaborate

Durante il debug della compatibilità OPC, comprendere dove vengono raccolte le opzioni di pagamento e dove vengono infine presentate può fare la differenza tra individuare rapidamente il problema e impiegare ore all’interno del modulo gateway.

11.0 Creazione dell’ordine: non fidarti mai del browser

Una volta che il pagamento raggiunge il gateway, il passaggio successivo cruciale è la creazione dell’ordine. Il metodo PrestaShop più importante in questo caso è:

validateOrder()

Un esempio semplificato è il seguente:

$this->module->validateOrder(
$cart->id, Configurazione::get('PS_OS_PAYMENT'),
$importoPagato,
Metodo di pagamento,
$messaggio, [],
nullo, falso,
$customer->chiave_sicura
);

Ci sono tre valori che meritano particolare attenzione:

11.1 ID carrello

Il carrello deve appartenere al cliente/sessione previsto e deve essere valido.

11.2 Importo del pagamento

Non utilizzare alla cieca:

$cart->getOrderTotal()

come prova che il gateway ha ricevuto tale importo.

L’importo deve essere verificato confrontandolo con la risposta del gateway.

11.3 Chiave sicura

La cliente deve essere correttamente associato al flusso del carrello/ordine.

12.0 I webhook devono essere idempotenti

Un gateway di pagamento può inviare lo stesso webhook più di una volta. Ad esempio:

Gateway
↓
webhook
↓
Il tuo server
↓
200 risposta

Se la risposta non viene ricevuta:

Gateway
↓
webhook
↓
Il tuo server
↓
Scelta persa
↓
Tentativi di accesso al gateway

Se l’integrazione crea un ordine ogni volta che riceve un webhook, si possono verificare ordini duplicati. Pertanto, la funzione di callback dovrebbe verificare se il carrello contiene già un ordine prima di crearne un altro. Concettualmente:

se ($cart->OrderExists()) {
// Già elaborato
// Restituisce una risposta positiva
}

Il gestore del webhook deve essere progettato per elaborare in modo sicuro le notifiche ripetute.

13.0 Pagamento sincrono vs asincrono

Non tutti i gateway di pagamento confermano il pagamento immediatamente.

13.1 Sincrono

Il gateway conferma immediatamente la transazione.

 
↓
Gateway
↓
Pagamento approvato
↓
validateOrder()
↓
PS_OS_PAYMENT
↓
Conferma dati

13.2 Asincrono

Il cliente può effettuare il reso prima della ricezione della conferma di pagamento finale.

 
↓
Gateway
↓
Ritorna al negozio
↓
Ordine in attesa
↓
webhook
↓
Verifica il pagamento
↓
Stato dell'ordine di modifica
↓
Pagamento accettato

Per i gateway asincroni, utilizzare uno stato di ordine in sospeso dedicato è spesso più sicuro che contrassegnare immediatamente l’ordine come pagato.

Una volta che il webhook conferma il pagamento:

$history = nuovo OrderHistory();
$history->id_order = (int) $order->id;
$history->changeIdOrderState( Configuration::get('PS_OS_PAYMENT'),
$ordine
);
$history->addWithemail(true);

Ciò garantisce che la transizione di stato dell’ordine avvenga tramite il meccanismo di cronologia degli ordini di PrestaShop, anziché limitarsi a modificare il valore nel database.

14.0 Una delle tecniche di debug più utili: confrontare i flussi di checkout

Quando un metodo di pagamento funziona nella procedura di pagamento predefinita ma non in OPC, consigliamo di confrontare l’intero flusso.

Passaggio 1: Verifica PHP

È hookPaymentOptions() eseguito?

Passaggio 2: Esamina le opzioni restituite

Il modulo di pagamento restituisce effettivamente un opzione di pagamento?

Passaggio 3: Controlla il carrello

Confronta:

• totale
• valuta
• cliente
• nazione
• vettore
• sconti
• le tasse
• spedizione

Passaggio 4: Controlla il browser

Cercare:

• Errori JavaScript
• elementi DOM mancanti
• richieste AJAX
• richieste fallite
• errori iframe

Passaggio 5: Controllare l’OPC

Determina se SuperCheckout è:

• filtraggio dell’opzione di pagamento
• sostituendo il suo HTML
• aggiornamento della sezione pagamenti
• modifica del carrello prima dell’esecuzione del modulo di pagamento

Passaggio 6: Controllare il gateway

Solo dopo aver confermato il flusso di cassa locale, l’indagine dovrebbe approfondire i seguenti aspetti:

• Autenticazione API
• payload della richiesta
• firma
• risposta
• webhook
• registri del gateway

Questo approccio a livelli è molto più veloce rispetto all’avvio ogni volta tramite l’API del gateway.

15.0 Problemi comuni di integrazione dei pagamenti che abbiamo riscontrato

Il lavoro di compatibilità nel mondo reale solitamente mette in luce problemi che non sono evidenti dalla documentazione del gateway.

15.1 L’opzione di pagamento scompare

Cause possibili:

• valuta non supportata
• restrizione per paese
• importo del carrello al di fuori dei limiti del gateway
• restrizione del vettore
• Filtro OPC
• configurazione del modulo di pagamento
• JavaScript nasconde il metodo

15.2 BLIK o un’altra opzione di pagamento appare e scompare

Cause possibili:

• aggiornamento AJAX
• ri-rendering dell’opzione di pagamento
• Inizializzazione JavaScript
• Totale carrello in modifica
• Ricalcolo dei requisiti di ammissibilità al gateway

15.3 L’elenco delle banche non si espande

Spesso si indaga su:

• Errori JavaScript
• elementi DOM sostituiti dinamicamente
• gestori di eventi collegati prima dell’aggiornamento OPC
• Inizializzazione JavaScript del fornitore di servizi di pagamento

15.4 L’iframe scompare

Indaga:

• aggiornamento del checkout
• Inizializzazione dell’iframe
• sostituzione DOM
• Esecuzione di JavaScript dopo gli aggiornamenti AJAX
  

15.5 Il pagamento è andato a buon fine, ma l’ordine rimane in sospeso

Dai un’occhiata:

• URL del webhook
• consegna webhook
• Verifica della firma
• ricerca carrello/ordine
• transizione di stato dell’ordine
• autenticazione tramite callback

15.6 Il metodo di pagamento funziona nel checkout predefinito ma non in OPC

Questo è un forte indizio che il problema potrebbe risiedere nell’interazione tra il modulo di pagamento e l’OPC, piuttosto che nell’API del gateway stesso.

16.0 Requisiti di sicurezza per un modulo di pagamento

I moduli di pagamento gestiscono operazioni sensibili, quindi la sicurezza non può essere considerata un miglioramento opzionale. Come minimo:

• Convalida le firme delle callback.
• Convalidare il rapporto carrello/cliente.
• Usa HTTPS.
• Convalidare i certificati TLS.
• Non fidarti mai dello stato del pagamento fornito esclusivamente dal browser.
• Non memorizzare mai i dati grezzi delle carte di credito a meno che l’architettura e i requisiti di conformità non lo prevedano esplicitamente.
• Non registrare informazioni di pagamento sensibili.
  

• Evitare serialize() e unserialize() / per dati esterni non attendibili.

• Convalida ed effettua il casting dei valori in ingresso.
• Proteggi gli endpoint AJAX e di callback personalizzati.
• Utilizzare token sicuri ove opportuno.
• Rendere idempotente l’elaborazione dei webhook.

Una pagina di conferma del pagamento non costituisce prova dell’avvenuto pagamento.

La risposta verificata dal server del gateway è ciò che dovrebbe determinare se l’ordine è considerato pagato.

17.0 Cosa cambia quando si supportano più moduli di pagamento?

Un’altra lezione appresa dal lavoro sulla compatibilità OPC è che l’aggiunta di un secondo o terzo modulo di pagamento può far emergere problemi che non erano visibili quando esisteva un solo metodo di pagamento.

Per esempio:

PayPal Payu
Comfino
SimplyLease
Bonifico bancario

possono tutti contribuire con opzioni di pagamento allo stesso checkout. Il checkout deve quindi gestire diverse:

• strutture HTML
• JavaScript
• Requisiti dell’iframe
• redirect
• Flussi API
• regole di ammissibilità
• importi minimi/massimi
• callback asincroni

Una modifica apportata a un metodo di pagamento può accidentalmente influire su un altro. Per questo motivo, le correzioni di compatibilità dei metodi di pagamento dovrebbero essere circoscritte.

Ad esempio, invece di modificare globalmente l’intera logica di elaborazione delle opzioni di pagamento, è possibile identificare il metodo di pagamento specifico e applicare la gestione della compatibilità solo dove necessario.

18.0 I test dovrebbero includere scenari di carrello reali

Testare un gateway di pagamento con un semplice prodotto da 10 € non è sufficiente. Una matrice di test adeguata dovrebbe includere:

Scenario	Cosa verificare
Singolo prodotto	Viene visualizzata l’opzione di pagamento
Più prodotti	L’importo corretto raggiunge il gateway
Codice Sconto	L’importo finale da pagare è corretto
Spese di spedizione	Il gateway riceve il totale corretto
IVA	L’importo del gateway corrisponde all’ordine
Importo minimo del gateway	Il metodo appare/scompare correttamente
Importo massimo del gateway	Il metodo appare/scompare correttamente
Valuta non supportata	Il metodo è nascosto
Paese non supportato	Il metodo è nascosto
Pagamento predefinito	Il pagamento funziona
OPC	Il pagamento funziona
Cassa mobile	L’interfaccia utente funziona
Pagamento non riuscito	Stato dell’ordine/pagamento corretto
Pagamento riuscito	L’ordine è stato creato correttamente
Tentativo di riconnessione webhook	Nessun ordine duplicato
abbandono del cliente	Nessun ordine pagato in modo errato
Timeout del gateway	Gestione corretta degli errori/in sospeso

Per le integrazioni OPC, testa anche gli aggiornamenti del checkout. Modifica:

• indirizzo
• vettore
• nazione
• metodo di pagamento
• quantità
• sconto

e verificare che le opzioni di pagamento rimangano corrette dopo ogni aggiornamento.

19.0 Un approccio pratico allo sviluppo

In base ai problemi che si presentano comunemente nelle integrazioni reali, un ordine di sviluppo più sicuro è il seguente:

19.1 Rendere il gateway compatibile con il checkout predefinito di PrestaShop

Innanzitutto, stabilisci che:

Opzione di pagamento
↓
Richiesta del gateway
↓
Risposta del gateway
↓
validateOrder()
↓
Conferma dati

funziona correttamente.

19.2 Aggiungere l’elaborazione di callback/webhook

Non rimandare la conferma asincrona alla fine.

19.3 Aggiungere una corretta gestione dello stato dell’ordine

Test:

• il successo
• fallimento
• in attesa di
• timeout

19.4 Test con carrelli realistici

Utilizza sconti, spese di spedizione, tasse, valute diverse e totali diversi.

19.5 Integrazione con OPC

Solo dopo che il flusso di base del gateway si sarà stabilizzato, si dovrebbe valutare la compatibilità con SuperCheckout.

19.6 Testare JavaScript e gli aggiornamenti dinamici

Ciò è particolarmente importante per i moduli di pagamento incorporati, gli iframe, le interfacce BLIK/di selezione bancaria e altri componenti di pagamento interattivi.

19.7 Testa tutti i metodi di pagamento contemporaneamente

Un sistema di pagamento che supporta cinque metodi di pagamento deve essere testato come un sistema unitario, non come cinque moduli isolati.

20.0 È meglio creare un gateway personalizzato o utilizzare un modulo esistente?

Non tutti i gateway giustificano un’integrazione personalizzata. Un modulo personalizzato ha senso quando:

• il gateway è regionale o di nicchia
• non esiste un modulo PrestaShop mantenuto
• il gateway richiede una logica aziendale personalizzata
• è necessario un flusso di lavoro di abbonamento o di regolamento specifico
• Hai bisogno di funzionalità che i moduli esistenti non possono fornire

Ma creare un’integrazione di pagamento significa anche assumersi la responsabilità della manutenzione. PrestaShop cambia.

PHP cambia. Le API del gateway cambiano.

I requisiti di sicurezza cambiano. I moduli di checkout cambiano.

E alla fine il fornitore di servizi di pagamento apporta una modifica che compromette un’integrazione altrimenti stabile.

Per i gateway di pagamento più diffusi, un modulo consolidato e ben mantenuto può quindi risultare significativamente più economico rispetto al mantenimento di un codice di pagamento personalizzato per diversi anni.

21.0 La lezione più importante dall’integrazione dei pagamenti di PrestaShop

La lezione più importante che ho imparato lavorando con i gateway di pagamento è che l’API spesso non è la parte più difficile. Invio:

Richiesta API → Risposta API

Di solito è semplice.

La parte difficile è tutto ciò che la circonda:

┌── Regole valutarie
├── Regole del Paese
├── Importo del carrello
├── Restrizioni del vettore
├── OPC
├── JavaScript
├── iframe
├── Aggiornamenti AJAX
├── Webhooks
├── Stati ordinati
└── Notifiche duplicate
↓
  → Concludi ordine → Modulo di pagamento → Gateway
↓
Creazione dell'ordine
↓
Conferma dell'ordine

Un’integrazione di pagamento ha successo solo quando l’intera catena si comporta in modo coerente.

Questo è anche il motivo per cui un problema come “BLIK non è presente” o “l’elenco delle banche non si apre” non dovrebbe essere immediatamente considerato un problema dell’API del gateway.

La causa effettiva potrebbe essere il calcolo del totale del carrello, la verifica dell’idoneità del metodo di pagamento, il rendering OPC, l’inizializzazione JavaScript o un aggiornamento AJAX che sostituisce l’interfaccia di pagamento.

22.0 Lista di controllo finale per un gateway di pagamento PrestaShop personalizzato

Prima di considerare l’integrazione completata, verificare:

• Il modulo di pagamento si estende Modulo di pagamento.
• opzioni di pagamento è implementato correttamente.
• pagamentoRestituzione viene implementato laddove necessario.
• Le opzioni di pagamento utilizzano Opzioni di pagamento.
• Vengono verificate le restrizioni valutarie.
• Vengono verificate le restrizioni relative al Paese e all’operatore telefonico, ove applicabili.
• I totali del carrello sono stati convalidati.
• Le risposte del gateway vengono verificate.
• Le firme delle callback vengono validate.
  
• ValidateOrder() La chiamata viene effettuata solo dopo la corretta verifica del pagamento.
• L’importo utilizzato per l’ordine viene convalidato in base alla risposta del gateway.
• I webhook sono idempotenti.
• Le notifiche duplicate non creano ordini duplicati.
• Vengono utilizzati gli stati di ordine corretti.
• I pagamenti non andati a buon fine e quelli in sospeso vengono gestiti separatamente.
• I dati di pagamento sensibili non vengono mai registrati o memorizzati inutilmente.
• L’utilizzo di HTTPS è obbligatorio.
• Il processo di checkout predefinito di PrestaShop è stato testato.
• L’OPC è stato testato separatamente.
• JavaScript è stato testato dopo l’aggiornamento della pagina di pagamento tramite AJAX.
• Sono stati testati gli iframe e gli elementi di pagamento interattivi.
• Sono stati testati insieme diversi moduli di pagamento.
• Sono stati testati carrelli realistici con sconti e spedizione.

Conclusione

Un gateway di pagamento personalizzato in PrestaShop è molto più di una semplice integrazione API.

L’API è solo una parte dell’implementazione. La vera sfida ingegneristica inizia quando il modulo di pagamento deve coesistere con il checkout di PrestaShop, un OPC come SuperCheckout, altri moduli di pagamento, JavaScript dinamico, ricalcoli del carrello e callback asincroni del gateway.

La nostra esperienza con i problemi di compatibilità dei pagamenti ha rafforzato un approccio importante: individuare sempre il punto in cui si verifica l’errore prima di modificare il codice.

Se il metodo di pagamento non viene restituito da PHP, esaminare il modulo di pagamento e le relative regole di idoneità. Se PHP lo restituisce ma il cliente non lo visualizza, esaminare OPC e il rendering frontend. Se l’interfaccia utente viene visualizzata ma non risponde, esaminare gli aggiornamenti JavaScript e AJAX. Se il pagamento va a buon fine ma l’ordine rimane in sospeso, esaminare il flusso di callback e lo stato dell’ordine.

Questo approccio è molto più affidabile rispetto al presupporre che ogni problema di pagamento sia un problema dell’API.

Per gli sviluppatori che lavorano sull’integrazione dei pagamenti in PrestaShop, l’obiettivo non dovrebbe essere semplicemente quello di far sì che un gateway accetti una transazione. L’obiettivo è rendere affidabile l’intero ciclo di vita del pagamento, dalla prima visualizzazione del checkout fino allo stato finale di ordine verificato, anche quando sono coinvolti più metodi di pagamento e un OPC personalizzato.