Introduzione

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, gli URL di ritorno, dopo l'avvenuto pagamento, e una firma digitale (facoltativa).

La verifica dell'avvenuto pagamento può essere fatta dal merchant, in modo asincrono osincrono. In modo asincrono (l'implementazione più semplice), gli URL di ritorno sono specificati in coppia successUrl e failUrl; queste sono pagine statiche dell'ecommerce, che mostrano un messaggio di conferma o di rifiuto del pagamento. Quest'implementazione è chiamata asincrona, perchè richiede l'intervento manuale di un addetto dell'ecommerce, che controlli il corretto avvenimento o fallimento dell'operazione (GWP invia una notifica via email all'amministratore dell'ecommerce), in modo simile a come vengono gestiti i pagamenti con bonifico convenzionale.

Nell'implementazione sincrona (consigliata), viene specificata invece una responseUrl; questa è 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.

Asincrono

Esempio

                
<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="successUrl" value="http://iltuoecommerce.com/success.html"/>
    <input type="hidden" name="failUrl" value="http://iltuoecommerce.com/fail.html"/>
    <input type="submit" value="PAGA">
</form>
                
            

• merchant: Id che identifica il merchant come affiliato a GWP.
• amount: Totale carrello in centesimi di Euro.
• transaction: Codice che identifica il carrello o l'ordine (riferimento per il merchant) .
• successUrl: URL (protocollo compresso) ospitato dal merchant, a cui va reindirizzato il cliente, dopo avvenuto pagamento.
• failUrl: URL (protocollo compresso) ospitato dal merchant a cui va reindirizzato il cliente, dopo un pagamento fallito.

Flusso

Sincrono

Esempio

                
<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="submit" value="PAGA">
</form>
                
            

• merchant: Id che identifica il merchant.
• amount: Totale carrello in centesimi di Euro.
• transaction: Codice che identifica il carrello o l'ordine (facoltativo) .
• responseUrl: URL (protocollo compresso) ospitato dal merchant, a cui va reindirizzato il cliente, dopo il pagamento, insieme all'ID della sessione di pagamento, in query string.

Flusso

Firma digitale

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).

Esempio (PHP)

                
<?php

$secret = "7x5ERIkzsRZmnbT3pgzTM1rgjvPoI5E1";

$formData = [
    'merchant'=> '5aafe595ff98222d628b4568',
    'amount'=> 5000,
    'transaction' => '123ABC',
    '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="responseUrl" value="<?=$formData['responseUrl']?>"/>
    <input type="hidden" name="sign" value="<?=$sign?>"/>
    <input type="submit" value="PAGA">
</form>
                
            

GWP API

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

Esempio risposta

                
{
    "code": 200,
    "message": "The transaction has been completed",
    "sign": "21df1222d398552d62ca45bb",
    "transaction": {
        "id": "5aafe595ff98222d62823568",
        "status": "completed",
        "amount": 5000
    }
}
                
            

• code: Indica il codice della risposta HTTP.
• message: Risposta human friendly.
• sign: Firma digitale composta come SHA256 del contenuto di transaction serializzato JSON, concatenato alla secretKey. Serve per garantire l'integrità della risposta. (diversa da transaction.sign)
• transaction: Oggetto con l'informazione della transazione.
• transaction.id: Id della transazione.
• transaction.status: Stato della transazione.
  • completed: Pagamento andato a buon fine.
  • failed: Pagamento NON andato a buon fine.
  • pending: Pagamento in attesa.
• transaction.amount: Importo della transazione.

Esempio (PHP)

                
<?php

    $secret = "7x5ERIkzsRZmnbT3pgzTM1rgjvPoI5E1";
    $id = $_GET['transactionId'];

    if(!$id)
        throw new Exception('Missing transaction ID');

    $rawResponse = file_get_contents("http://127.0.0.1:4415/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";
    }

?>
                
            

Esempio di implementazione

Pagina di Esempio

Note

Ambiente di produzione

Ambiente di sviluppo

Il campo merchant e secret vengono forniti da Growish in fase di attivazione e sono diversi tra l'ambiente di produzione e sviluppo.