Come creare la tua pagina di pagamento personalizzata
La pagina iFrame di Axerve permette agli esercenti di processare le transazioni online con carta di credito con una pagina di pagamento nascosta attraverso un iFrame nella pagina di checkout.
L’adozione della pagina di pagamento iFrame di Axerve offre al merchant la possibilità di personalizzare il layout della pagina di checkout e, allo stesso tempo, i dati di carta vengono spediti dal form di checkout ad una pagina nascosta (residente sui server di Axerve) via javascript.
La soluzione richiede di validare la conformità PCI annualmente, compilando e restituendo all’acquirer il questionario SAQ A-EP.
Tokenization e iFrame sono disponibili per i clienti Professional ed Enterprise
Step 0: iscrizione ad Axerve Ecommerce Solutions
….probabilmente ti sei già registrato, oppure no? È possibile registrarsi e configurare il backoffice leggendo la guida veloce di Axerve Ecommerce Solutions.
Adesso possiamo iniziare davvero.
Step 1: crittografare la richiesta
Funziona più o meno come con le SOAP.
In pratica, è necessario crittografare le informazioni della transazione con lo shopLogin
, uicCode
(il codice valuta), amount
, e uno shopTransactionId
(un identificativo della transazione a scelta dell’esercente).
Axerve Ecommerce Solutions risponde con almeno due parametri:
TransactionResult
- OK se la crittografia è andata a buon fineCryptDecryptString
– una stringa criptata con tutte le informazioni richieste che viene usata per lo step successivo.
Ecco un esempio. I server dell’esercente comunicano le informazioni della transazione, impostando i valori del metodoWSCryptDecrypt
’s Encrypt
in questo modo:
<Encrypt>
<shopLogin>9000001</shopLogin>
<uicCode>242</uicCode>
<amount>1245.6</amount>
<shopTransactionId>34az85ord19</shopTransactionId>
</Encrypt>
Axerve Ecommerce Solutions autentica il server chiamante e valida le informazioni che contraddistinguono la transazione. Se si superano i controlli, viene restituita una stringa criptata ad Axerve Ecommerce Solutions:
<EncryptResult>
<GestPayCryptDecryptxmlns="">
<TransactionType>ENCRYPT</TransactionType>
<TransactionResult>OK</TransactionResult>
<CryptDecryptString>30715CA8...</CryptDecryptString>
<ErrorCode>0</ErrorCode>
<ErrorDescription/>
</GestPayCryptDecrypt>
</EncryptResult>
Step 2: configurare javascript e HTML
Dopo aver ottenuto la stringa di dati criptati (come descritto nel capitolo precedente), il browser del compratore viene indirizzato alla pagina di checkout dell’esercente che include un file javascript ricevuto dai server di Axerve:
<script src="https://ecomm.sella.it/pagam/JavaScript/js\_GestPay.js" type="text/javascript"></script>
Lo script effettua automaticamente una verifica di compatibilità del browser per accertarsi che la funzione HTML postmessage, che viene usata per lo scambio di dati, sia supportato.
Il risultato della verifica è il valore booleano della variabile BrowserEnabled
:
if(BrowserEnabled){
// The Browser is supported!
// Proceed to create the payment page
}else{
// the browser is NOT supported
// Place here error handler code
}
Per caricare la pagina nascosta iFrame, la pagina di checkout deve chiamare la funzione Javascript passando il Merchant code , la stringa criptata e un oggetto callback necessario per leggere i risultati della verifica di sicurezza.
if(BrowserEnabled){
// The Browser is supported!
GestPay.CreatePaymentPage(
MerchantCode,
EncryptedString,
paymentPageLoadedCallback);
}else{
// the browser is NOT supported
}
La funzione crea un iFrame nascosto nel corpo dell’elemento e carica la pagina di pagamento passando il merchant code e la stringa criptata nella fase precedente.
<iframe
src="https://ecomm.sella.it/Pagam/HiddeniFrame.aspx?a=MerchantCode&b=EncryptedString"
heigth="0"
width="0"
style="position:absolute;top:0;left:0;width:0;height:0;visibility:hidden">
</iframe>
Quando viene chiamata la pagina di pagamento, vengono eseguiti i controlli di sicurezza necessari e viene riportato il risultato nell’oggetto result
.
varpaymentPageLoadedCallback=function(result){
if(Result.ErrorCode!=10){// 10 means no security errors
//An error has occurred
//result.ErrorCode will return the Error occurred
//Result.ErrorDescription will return the Error Description
//.... place here error handle code...
}else{
//the iFrame is correctly created and the payment page is loaded;
// the user can proceed to insert the credit card data.
}
}
Se il controllo di compatibilità del browser fallisce, l’iFrame non viene creato e la pagina di pagamento non viene caricata.
È possibile verificare i browser supportati nella sezione Requisiti software.
Step 3: inviare i dati di carta
Per inviare i dati di carta all’iFrame nascosto, la pagina di checkout assegna una funzione all’evento OnSubmit
del form della carta di credito. Questa funzionalità recupera i dati di carta e chiama la funzione GestPay.SendPayment
, fornendo un array con il numero di carta (CC), il mese e l’anno di scadenza (EXPMM e EXPYY), il CVV (CVV2) se attivo, a una funzione di callBack.
- Il campo della carta di credito contiene valori tra 13 e 19 cifre.
- Il mese e l’anno di scadenza sono composti, rispettivamente, da 2 cifre.
- Il campo CVV2 contiene 3 o 4 cifre.
Ecco un esempio:
<form name="myCCForm" action="" method="post" OnSubmit="return checkCC();">
<fieldset>
<legend>Insert Credit Card Data</legend>
<label for="CC">Credit Card Number</label>
<input type="text" name="CC" value="" autocomplete="off" id="CC"/>
<label for="ExpMM">Expiry Month</label>
<input type="text"name="ExpMM"id="ExpMM"value=""/>
<label for="ExpYY">Expiry Year</label>
<input type="text"name="ExpYY" id="ExpYY" value=""/>
<label for="CVV2">CVV2 / 4DBC</label>
<input type="text" name="CVV2" id="CVV2" value=""/>
<label for="BuyerName">Buyer's name</label>
<input type="text" name="BuyerName" id="BuyerName" value=""/>
<label for="BuyerEmail">Buyer's email</label>
<input type="text"name=" BuyerEmail" id="BuyerEmail" value=""/>
</fieldset>
<fieldset>
<input type="submit" name="submit" value="Send Payment" id="submit"/>
</fieldset>
</form>
E la funzione javascript checkCC
:
function CheckCC(){
document.getElementById('submit').disabled=true;
GestPay.SendPayment({
CC:document.getElementById('CC').value,
EXPMM:document.getElementById('ExpMM').value,
EXPYY:document.getElementById('ExpYY').value,
CVV2:document.getElementById('CVV2').value,
BuyerName:document.getElementById('BuyerName').value,
BuyerEmail:document.getElementById('BuyerEmail').value
},paymentCompletedCallback);
returnfalse;
}
Per sollevare il sito Ecommerce dalla necessità di richiedere certificazioni PCI-DDS onerose ed eccessivamente elevate, l’evento
OnSubmit
deve evitare di passare i dati di carta alla pagina di checkout del merchant.
Step 4: risultati della transazione
Axerve Ecommerce Solutions invia il risultato della transazione come oggetto javascript e come notifica che viene inoltrata con una chiamata server-to-server alla pagina impostata sul server del merchant (la pagina di notifica può essere impostata sulla funzione Response URL Server to Server
presente nella sezione del backoffice Configurazione > Ambiente.
Come gestire transazioni 3D (Verified by Visa, Mastercard SecureCode, ecc.)**
Le transazioni fatte con carte 3D richiedono l’autenticazione del titolare di carta. L’acquirente, reindirizzato verso l’Issuer, si deve autenticare secondo il sistema scelto dall’Issuer stesso. Avvenuta l’autenticazione, la transazione riceve un esito positivo o negativo dalla società che ha emesso la carta (Issuer).
Se la carta viene riconosciuta come 3D, il risultato della richiesta autorizzativa è un errore specifico (8006
) che si può leggere alla proprietà ErrorCode
dell’oggetto Result
. La descrizione dell’errore (verified by Visa) si evince grazie alla proprietà ErrorDescription dell’oggetto Result.
In questa fase vengono mostrate informazioni addizionali che sono necessarie al processo di pagamento e specifiche delle transazioni 3D. In particolare, è necessario acquisire il transaction id attraverso la proprietà TransKey
dell’oggetto Result
e una stringa cifrata, visibile grazie alla proprietà VbVRisp
dell’oggetto Result, che viene usata nella fase seguente.
var paymentCompletedCallback = function(Result){
if(Result.ErrorCode!=0){
if(Result.ErrorCode==8006){
//3D Transaction - Card holder authorization required
//Get the TransKey
//NOTE: you have to store this value somewhere for further use
// after the redirect, you'll need this.
varTransKey=Result.TransKey;
//Get the VBVRisp; we will need it soon !
varVBVRisp=Result.VBVRisp;
...
//place here the code to redirect the card holder to the authentication website
...
} else {
//Call failed for other errors
//.... place here error handle code...
}
} else {
//Call OK, proceed to decrypt the Result.EncryptedResponse property
}
}
Autenticazione del titolare di carta
Se la carta di credito risulta abilitata ai protocolli 3D, il compratore deve autenticarsi; il suo browser viene indirizzato ad una pagina di Axerve Ecommerce Solutions che funziona come interfaccia per l’autenticazione che il buyer che viene reindirizzato sul sito dell’Issuer. Questo step di autenticazione viene generalmente chiamato 3D-Secure.
La pagina da chiamare è:
https://ecomm.sella.it/pagam/pagam3d.aspx
(produzione)https://sandbox.gestpay.net/pagam/pagam3d.aspx
(ambiente di test)
La pagina deve essere chiamata con questi parametri:
Parametro | Descrizione |
---|---|
a |
shop_login |
b |
una stringa cifrata acquisita nella fase precedente attraverso la proprietà Result.VbVRisp dell’oggetto Result |
c |
URL del merchant verso il quale l’acquirente viene reindirizzato dopo l’autenticazione |
Alla fine del processo di autenticazione, il buyer viene reindirizzato sulla URL che l’esercente ha specificato nel parametro c
.
Dopodiché la pagina del merchant richiama la funzione Gestpay.SendPayment()
con due parametri:
TransKey
, ottenuto nello step precedentePaRes
, parametro derivato dall’autenticazione del buyer
PaRes
è una stringa cifrata contenente il risultato dell’autenticazione che deve essere acquisito dal merchant e inoltrato ad Axerve Ecommerce Solutions nella fase successiva.
È bene assicurarsi che
PaRes
non contenga caratteri a capo, come il carattere ASCII10
(a capo) o13
(ritorno a capo). Alcuni acquirer potrebbero inviare stringhe con a capo; questo può causare un troncamento nelle stringhe javascript e di conseguenza Axerve Ecommerce Solutions non accetterebbe la richiesta.
Conclusione della transazione
Una volta che il buyer ritorna sul sito del merchant dopo l’autenticazione, ci sono tutte le informazioni per concludere la transazione inviando una nuova richiesta autorizzativa tramite il metodo GestPay.SendPayment
.
Prima però è necessario includere il javascript di Axerve e chiamare la funzione javascript GestPay.CreatePaymentPage
passando il Merchant code e la stringa criptata creata antecedentemente alla prima chiamata autorizzativa.
Una volta creato l’iFrame nascosto è possibile inviare la nuova richiesta auth attraverso il metodo GestPay.SendPayment
, passando un comando contenente il valore TransKey (TransKey
), il valore PARes (PARes
) e l’oggetto Callback per gestire la risposta asincrona e recuperare la stringa criptata con i risultati della transazione.
GestPay.SendPayment({
'TransKey':'//PLACE HERE THE TRANSKEY VALUE',
'PARes':'//PLACE HERE THE PARES VALUE'
},
LocalObj.CallBack);
LocalObj.CallBack=function(Result){
if(Result.ErrorCode!=0){
//Call failed an error has occurred
//.... place here error handle code...
} else {
//Call went good
//place here the code to retreive the encrypted string
varresponseString=Result.EncryptedResponse;
}
}
La risposta verso l’esercente
Una notifica viene inoltrata attraverso una chiamata server-to-server alla pagina configurata sul server del merchant (la URL della pagina di notifica è un’informazione configurabile all’interno del backoffice merchant). La sintassi della call è la seguente:
http://<url server to server>?a=<ShopLogin>&b=<encrypted string>
La chiamata verso la pagina viene effettuata passando due parametri:
a
il codice che identifica il merchant (Shop Login)b
la stringa criptata che contiene il risultato del pagamento
La pagina sul server del merchant deve contenere <HTML></HTML>
nell’html del codice sorgente.
Se Axerve Ecommerce Solutions non riceve una risposta con un codice status 200
dal sito del merchant, riprova due volte nelle 24 ore successive, alle 6:00 e alle 18:00.
L’esercente riceve anche una notifica del risultato della transazione via email all’indirizzo configurato nel profilo.
Inoltre la transazione è consultabile dal backoffice di Axerve Ecommerce Solutions (dashboard myCommerce) all’interno della sezione Active Report.
Fallback alla pagina di pagamento di default
Axerve Ecommerce Solutions permette allo store online di indirizzare il titolare di carta alla pagina di pagamento di default come alternativa all’iFrame nel caso in cui il browser non la supporti.
La pagina risiede sui server di Axerve e dà la possibilità di inserire i dati di carta senza che il merchant possa vederli né archiviarli.
Dopo aver ottenuto la stringa criptata (come descritto nella pagina guida veloce), il browser dell’acquirente viene reindirizzato alla pagina di pagamento sui server di Axerve:
https://ecomm.sella.it/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string> (produzione)
https://sandbox.gestpay.net/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string> (test)
La call viene effettuata passando due parametri:
a
il codice che identifica il merchant (Shop Login)b
la stringa criptata che identifica la transazione
La pagina di pagamento acquisisce i parametri e verifica i controlli di identità (deve esserci un riferimento ad un merchant conosciuto) e i dati di sicurezza (il parametro b deve corrispondere alla stringa criptata comunicata dall’esercente durante la fase precedente).
Se i controlli hanno buon esito, la pagina di pagamento viene mostrata all’acquirente che può inserire i dati necessari a completare il pagamento.
Se i controlli falliscono, la pagina di pagamento non viene mostrata e il processo passa ad un’altra fase per comunicare l’esito negativo.
Comunicazione del risultato della transazione
Axerve Ecommerce Solutions notifica il risultato della transazione attraverso una stringa criptata (il parametro b
della call alla url specificata dal merchant o la proprietà EncryptedResponse
dell’oggetto javascript Result
). La stringa, una volta decodificata, permette di aggiornare lo stat della transazione registrata del sistema informativo dell’esercente.
La pagina scelta dal merchant per ricevere il risultato della transazione (sia nel caso di comunicazione server-to-server sia attraverso l’oggetto javascript Result
) deve chiamare i server di Axerve per richiedere il servizio di decodifica e ottenere il risultato della transazione nella forma decodificata.
La richiesta di decodifica della stringa ricevuta può essere fatta attraverso di webservice. Non richiede nessuna installazione sul server ma semplicemente un call al webservice usando il protocollo https. La risposta avviene nel formato XML.
Autenticazione server-to-server
L’autenticazione del merchant richiedendo i servizi di crittazione o decodfica viene fatta verificando:
- Validità Shop Login validity : il parametro ShopLogin deve corrispondere ad un codice registrato nei dettagli dei clienti di Axerve
- Indirizzo IP : l’indirizzo IP del chiamante deve corrisponder a quelli configurati nel profilo del merchant su backoffice.
- Stato dello Shop Login : lo stato del merchant deve essere attivo (viene gestito da Axerve e non dal merchant)
Se i controlli dell’autenticazione non hanno esito positivo viene restituito un errore specifico per identificarne le cause.