Growish Web Payments (GWP) è il gateway di pagamento offerto da Growish.
GWP può essere utilizzato per accettare pagamenti con carta di credito e con eWallets, su siti ecommerce convenzionati con una rete partner di Growish. Inoltre, le reti partner che utilizzano GWP, possono configurare promozioni di tipo instant cashback, programmi di raccolta punti, come sistemi di loyalty, e concorsi. Le logiche di business necessarie per questi flussi, sono gestite, in modo autonomo, da Growish, spostando i costi di sviluppo e manutenzione dal merchant a Growish.
GWP è un Hosted Payment Gateway, come Paypal, quindi il cliente viene reindirizzato dalla pagina di checkout dell'ecommerce, alla pagina del gateway di pagemento, ospitato sui server di Growish. Una volta completato il pagamento, il cliente viene rimandato sull'ecommerce, per completare l'ordine.
La creazione di una sessione di pagamento, avviene semplicemente reindirizzando il proprio cliente su https://webpayments.growish.com/session
(ambiente di produzione) con una lista di parametri (in POST application/x-www-form-urlencoded
o GET), che identificano l'ecommerce, il carrello o l'ordine, la quantità da pagare, una URL di ritorno, i dati anagrafici del cliente e una firma digitale
La URL di ritorno, responseUrl
, è una pagina dell'ecommerce, a cui il cliente viene reindirizzato dopo il pagamento, con il parametro query string transactionId
. Usando il valore di tale parametro, l'ecommerce può interrogare le api di GWP, per avere informazioni sulla transazione, cosi da poter decidere immediatamente se considerare l'ordine come pagato o no e presentare al proprio utente un messaggio di conferma o rifiuto della operazione.
<form method="POST" action="https://webpayments.growish.com/session">
<input type="hidden" name="merchant" value="5aafe595ff98222d628b4568"/>
<input type="hidden" name="amount" value="5000"/>
<input type="hidden" name="transaction" value="ABC123"/>
<input type="hidden" name="responseUrl" value="http://iltuoecommerce.com/process-pay/"/>
<input type="hidden" name="debitedUserName" value="Luca"/>
<input type="hidden" name="debitedUserLastName" value="Lupo"/>
<input type="hidden" name="debitedUserBirthday" value="1985-01-25"/>
<input type="hidden" name="debitedUserEmail" value="email@fake.com"/>
<input type="hidden" name="webhookUrl" value="http://iltuoecommerce.com/webhook"/>
<input type="submit" value="PAGA">
</form>
Insieme ai parametri prima elencati, si può aggiungere il campo sign. Può venire configurato come obbligatorio dal Merchant ed è fortemente consigliata la sua implementazione nel codice.
La sua funzione è quella di garantire l'integrità dei parametri di sessione. Per generarlo, basta creare un hash SHA256 con il corpo della richiesta serializzata [*], come JSON, concatenata alla secretKey (secretKey è un valore privato, conosciuto solo da GWP e dal merchant).
<?php
$secret = "7x5ERIkzsRZmnbT3pgzTM1rgjvPoI5E1";
$formData = [
'merchant'=> '5aafe595ff98222d628b4568',
'amount'=> 5000,
'transaction' => '123ABC',
'debitedUserName' => 'Luca',
'debitedUserLastName' => 'Lupo',
'debitedUserEmail' => 'email@fake.com',
'debitedUserBirthday' => '1985-01-25',
'responseUrl' => 'http://iltuoecommerce.com/process-pay'
];
$serial = json_encode($formData);
$sign = hash('sha256', $serial . $secret);
?>
<form method="POST" action="https://webpayments.growish.com/session">
<input type="hidden" name="merchant" value="<?=$formData['merchant']?>"/>
<input type="hidden" name="amount" value="<?=$formData['amount']?>"/>
<input type="hidden" name="transaction" value="<?=$formData['transaction']?>"/>
<input type="hidden" name="debitedUserName" value="<?=$formData['debitedUserName']?>"/>
<input type="hidden" name="debitedUserLastName" value="<?=$formData['debitedUserLastName']?>"/>
<input type="hidden" name="debitedUserEmail" value="<?=$formData['debitedUserEmail']?>"/>
<input type="hidden" name="debitedUserBirthday" value="<?=$formData['debitedUserBirthday']?>"/>
<input type="hidden" name="responseUrl" value="<?=$formData['responseUrl']?>"/>
<input type="hidden" name="sign" value="<?=$sign?>"/>
<input type="submit" value="PAGA">
</form>
[*] Fare particolare attenzione al processo di serializzazione, alcuni linguaggi di programmazione non rispettano l'ordine delle key del oggetto serializzato, se l'ordine delle key serializzate non coincide con l'ordine delle key inoltrate nella richiesta HTTP, la verifica della firma lato GWP fallirà.
GWP espone una API RESTful con un singolo metodo RPC al backend dei merchant, per controllare se una transazione è andatata a buon fine o meno, attraverso la restituzione di un documento JSON.
Basta fare una GET a https://webpayments.growish.com/api/v1/transaction/:id
{
"code": 200,
"message": "The transaction has been completed",
"sign": "f0e85dab90797d7d32a91b4e1eed9d2d9bbdf0b6bb87fcf310524a4b98325d81",
"transaction": {
"id": "5aafe595ff98222d62823568",
"status": "completed",
"amount": 5000,
"merchantTransaction": "123ABC"
}
}
<?php
$secret = "7x5ERIkzsRZmnbT3pgzTM1rgjvPoI5E1";
$id = $_GET['transactionId'];
if(!$id)
throw new Exception('Missing transaction ID');
$rawResponse = file_get_contents("http://webpaymentsdev.growish.com/api/v1/transaction/" . $id);
try {
$response = json_decode($rawResponse);
}
catch(Exception $e) {
throw new Exception('Malformed response');
}
$sign = hash("sha256", json_encode($response->transaction) . $secret);
if($sign !== $response->sign)
throw new Exception('Invalid sign');
if($response->transaction->status === "completed") {
//Check if $response->amount is correct
//Send the user to the confirmation page
echo "OK";
}
else {
//Send the user to the fail page
echo "KO";
}
?>
[*] E responsabilità del merchant verificare che il numero d'ordine sia valido è in attesa di pagamento, così come che l'importo pagato coincida con quello dell'ordine.
Nei parametri del form si può specificare una URL (webhookUrl) ospitata dal merchant nella quale GWP notificherà la creazione di una nuova sessione di pagamento ed eventuali aggiornamenti di successo o fallimento della sessione. Il webhook è una chiamata HTTP POST con content-type application/json.
{
"transaction": "5e612123d4a197a42cd0c1ad",
"merchantTransaction": "123ABC",
"amount": 7500,
"creationDate": "2020-03-05T15:56:19.420Z",
"expirationDate": "2020-03-05T16:22:59.412Z",
"status": "pending",
"sign": "f0e85dab90797d7d32a91b4e1eed9d2d9bbdf0b6bb87fcf310524a4b98325d81"
}
https://webpayments.growish.com/session
https://webpaymentsdev.growish.com/session
Il campo merchant
e secret
vengono forniti da Growish in fase di attivazione e sono diversi tra l'ambiente di produzione e sviluppo.