Area sviluppatori 2018-10-30T16:59:41+02:00

Integrazione API & Web Services

Consulta documentazione

Integrazione API & Web Services

Consulta documentazione

INFORMAZIONI SULL’ ASSISTENZA

La guida per l’integrazione di e-POSitivity che state leggendo, si rivelerà essere il riferimento per l’integrazione della vostra applicazione con i nostri sistemi autorizzativi.
Se dopo aver letto la documentazione non avete trovato una risposta alle vostre domande, contattate il Servizio Esercenti Axepta scrivendo all’indirizzo e-mail ecommercesupport@bnlpositivity.it oppure chiamando il Numero Verde 800 955 954 e selezionando l’opzione 4.

INTRODUZIONE

Nel presente documento vengono illustrate le specifiche tecniche dei web services e delle API, necessari per l’integrazione del proprio portale di e-commerce, con il sistema di pagamento elettronico e-POSitivity. I portali web, che offrono servizi di e-commerce prevedono un carrello con il riepilogo dei prodotti acquistati e un pulsante per azionare una richiesta di pagamento.

Ultimata la fase di selezione dei prodotti, il cliente viene veicolato su una pagina di conferma dell’acquisto. In questa pagina, dopo aver selezionato lo strumento da utilizzare per il pagamento, viene invitato a premere il pulsante relativo alla funzione di “acquisto/compra” o di uguale significato. Ricevuta la conferma di acquisto, l’esercente invia al gateway e-POSitivity la richiesta di pagamento.

e–POSitivity consente di accettare una vasta gamma di circuiti eseguendo una sola integrazione:

  • L’accettazione delle carte Visa, Visa Electron, MasterCard e Maestro è compresa nel contratto di convenzionamento stipulato con Axepta. Per alcune categorie merceologiche è possibile che vi siano delle restrizioni nell’accettazione delle carte MasterCard e Maestro: in tali casi Axepta fornisce un avviso preventivo in fase di definizione del contratto
  • L’iscrizione a Verified By Visae 3D Secure Code è a carico di Axepta (avviene durante il censimento della pratica)
  • Per i circuiti American Express e Diners è necessario sottoscrivere gli appositi moduli diconvenzione con i rispettivi circuiti; la modulistica è disponibile contattando la propria AgenziaBNL, il proprio Agente Axepta o il Servizio Esercenti. Axepta provvederà ad inoltrare il contratto e ad attivare il circuito automaticamente al momento dellaricezione del codice di convenzione assegnato.
  • Laddove il cliente desiderasse anche l’attivazione del circuito Findomestic al fine di accettare transazioni con carte Aura e Nova, sarà necessario che sottoscriva il contratto; il modulo potrà essere richiesto direttamente a Findomestic o mediante la rete di vendita di Axepta.
  • Per l’attivazione di Masterpass rivolgersialla rete di vendita di Axepta o al servizio di assistenza e-commerce.
  • Per l’attivazione di MyBank rivolgersialla rete di vendita di Axepta al servizio di assistenza e-commerce.
  • L’esercente che vuole attivare PayPal sul POS virtuale e–POSitivity deve:
    • attivare un conto PayPal Business dal sito dal sito www.paypal.it e, in caso di necessità di assistenza, chiedere ad un operatore di PayPal chiamando il numero verde 800 976359 del Gruppo Attivazione Commercianti;
    • richiedere le abilitazioni necessarie alle API PayPal per consentire l’esecuzione di transazioni da e–POSitivity;
    • L’esercente, ricevuta l’abilitazione da PayPal, segnala a ecommercesupport@bnlpositivity.it l’esito fornendo:
      • API Username
      • API Password
      • Signature
    • Axepta provvede ad abilitare PayPal sul POS virtuale e-POSitivity.

L’esercente può inviare richieste di autorizzazione verso e-POSitivity con due modalità diverse:

  1. Pagamenti on line (BUY NOW)
  2. Pagamenti diretti

Le tecnologie di integrazione con le richieste di autorizzazione elencate sono:

  • API
  • WEB SERVICES

I messaggi scambiati tra l’applicazione che effettua le richieste (Customer Buy Now) e e-POSitivity sono conformi alle specifiche SOAP 1.1. Il protocollo utilizzato è l’HTTP 1.1 (RFC 2616), l’integrità dei dati e la cifratura delle informazioni vengono garantite attraverso il protocollo TLS 1.0 (rfc2246.txt).

I servizi online offerti dal prodotto sono descritti dal file WSDL fornito.

Il protocollo 3D Secure prevede l’invio delle richieste di Verifica Iscrizione Carta (VEREQ) su connessione cifrata (HTTPS).

In particolare per MasterCard è prevista una mutua autenticazione, Visa, invece, fornisce delle credenziali da inserire nel messaggio applicativo.

Periniziare l’integrazione è fondamentale richiedere ad Axepta l’accesso ai servizi. Dopo l’abilitazione verranno forniti i seguenti parametri da valorizzare durante le inizializzazioni per le richieste di autorizzazione.

Parametri necessari per l’utilizzo della tecnologia Web Services:

  • Terminal Id
  • Wsdl url (url del servizio web)
  • File wsdl

Parametri necessari per l’utilizzo della tecnologia API:

  • Terminal Id
  • Ksig
  • Server url
  • Riferimenti da aggiungere al progetto (dll, jar, classi php)

Accesso Back Office, per il monitoraggio e la gestione delle transazioni effettuate:

Parametri Valori
url di test https://testbnl.netsw.it/BNL_CG_BO_WEB
username mhtest2
password Mhtest2016

Nell’ambiente di test è possibile effettuare delle transazioni utilizzando queste carte di credito:

Pan Carta Circuito Scadenza CVV Iscrizione 3DS Esito 3DS
4557773333333335 Visa SI OK
4557772222222229 Visa SI OK
4111111111111111 Visa 10/2023 NO
4555000000000001 Visa NO
4111111112225555 Visa NO
4011514444441116 Visa Electron NO
4011519992222222 Visa Electron NO
4005000000000007 Visa Debit 10/2023 NO
4005004455555556 Visa Debit NO
5430132222222226 Mastercard NO
5893535544444429 Mastercard NO
5790640100000005 Mastercard NO
5430131234567891 Mastercard SI KO
5548535889622125 Mastercard SI OK
5401172222222227 Mastercard SI OK
5430132222222226 Mastercard NO OK
5548536000000126 Mastercard SI OK
5264921111111115 Mastercard Debit 555 NO
5545910000000019 Mastercard Debit SI KO
5020639451965933 Maestro SI OK
5893535596092423 Maestro SI KO

ATTENZIONE: laddove specificato, è importante rispettare la giusta data di scadenza e/o il codice CVV. In caso contrario la transazione sarà rifiutata.

Sono in vigore i alcuni test cases in ambiente di test, attraverso i quali è possibile simulare il comportamento del gateway al verificarsi di alcune condizioni che invaliderebbero la transazione. Questi rispondono alle seguenti combinazioni PAN – IMPORTO:

PAN CARTA IMPORTO (EUR) ESITO IGFS DESCRIZIONE
4557773333333335
5401172222222227
4557772222222229
5548536000000126
5020639451965933
101,00 IGFS_008 Autorizzazione negata
102,00 IGFS_021 Codice merchant errato
103,00 IGFS_020 Carta invalida
104,00 IGFS_119 Operazione non permessa al titolare
105,00 IGFS_123 Superato limite frequenza
106,00 IGFS_209 Carta rubata
107,00 IGFS_005 Errore di formato
108,00 IGFS_107 Contattare issuer
109,00 IGFS_102 Sospetta frode
5430132222222226
4111111111111111
4011519992222222
4005000000000007
5264921111111115
103,00 IGFS_030 Fondi insufficienti
104,00 IGFS_119 Operazione non permessa al titolare
105,00 IGFS_123 Superato limite frequenza
5401172222222227
5264921111111115
> 200 IGFS_030 Fondi insufficienti

Di seguito i parametri ed i link per integrarsi con il nostro ambiente di test, utilizzando un terminale generico:

Questa sezione propone un semplice esempio per integrare il vostro sito Web con e–POSitivity. Le pagine di esempio sono proposte utilizzando i seguenti linguaggi di programmazione:

  • vb.net
  • c#
  • php
  • java

Si presuppone che lo sviluppatore abbia una conoscenza di base del linguaggio scelto.

Integrazione Modulo HTML

Consulta documentazione

Integrazione Modulo HTML

Consulta documentazione

Nel presente documento vengono illustrate le specifiche tecniche, per l’integrazione del proprio portale di
e-commerce, con il sistema di pagamento elettronico e-POSitivity. I portali web, che offrono servizi di e-commerce prevedono un carrello con il riepilogo dei prodotti acquistati e un pulsante per azionare una richiesta di pagamento.

Ultimata la fase di selezione dei prodotti, il cliente viene trasferito su una pagina di conferma dell’acquisto. In questa pagina, dopo aver selezionato lo strumento da utilizzare per il pagamento, viene invitato a premere il pulsante relativo alla funzione di “acquisto/compra” o di uguale significato. Ricevuta la conferma di acquisto, l’esercente invia al gateway e-POSitivity la richiesta di pagamento.

e–POSitivity consente di accettare una vasta gamma di circuiti eseguendo una sola integrazione:

  • L’accettazione delle carte Visa, Visa Electron, MasterCard e Maestro è compresa nel contratto di convenzionamento stipulato con Axepta. Per alcune categorie merceologiche è possibile che vi siano delle restrizioni nell’accettazione delle carte MasterCard e Maestro: in tali casi Axepta fornisce un avviso preventivo in fase di definizione del contratto
  • L’iscrizione a Verified By Visae 3D Secure Code è a carico di Axepta (avviene durante il censimento della pratica)
  • Per i circuiti American Express e Diners è necessario sottoscrivere gli appositi moduli diconvenzione con i rispettivi circuiti; la modulistica è disponibile contattando la propria AgenziaBNL, il proprio Agente Axepta o il Servizio Esercenti. Axepta provvederà ad inoltrare il contratto e ad attivare il circuito automaticamente al momento dellaricezione del codice di convenzione assegnato.
  • Qualora l’esercente intenda attivare il circuito Findomestic al fine di accettare transazioni con le carte Aura e Nova, dovrà sottoscrivere l’apposito modulo di convenzionamento facendone richiesta direttamente a Findomestic o mediante la rete di vendita di Axepta.
  • L’esercente che vuole attivare PayPal sul POS virtuale e–POSitivity deve:
    • attivare un conto PayPal Business dal sito dal sito www.paypal.it e, in caso di necessità di assistenza, chiedere ad un operatore di PayPal chiamando il numero verde 800 976359 del Gruppo Attivazione Commercianti;
    • richiedere le abilitazioni necessarie alle API PayPal per consentire l’esecuzione di transazioni da e–POSitivity;
    • L’esercente, ricevuta l’abilitazione da PayPal, segnala a ecommercesupport@bnlpositivity.it l’esito fornendo:
      • API Username
      • API Password
      • Signature
    • Axepta provvede ad abilitare PayPal sul POS virtuale e-POSitivity.
  • MyBank consente al merchant di ricevere pagamenti e-commerce mediante bonifici, visualizzando in tempo reale lo stato della transazione. Per l’attivazione del servizio rivolgersi alla rete di vendita di Axepta.
  • Per l’attivazione di Masterpass rivolgersi alla rete di vendita di Axepta o al servizio di assistenza e-commerce.

Questo servizio consiste nell’utilizzo di una pagina di pagamento fornita da Axepta residente sui nostri server. Con questa soluzione, il titolare di carta viene indirizzato, al momento del pagamento, sulla pagina di Axepta protetta con certificato SSL, dove potrà inserire direttamente i dati della carta di credito. Completato il pagamento, il cliente titolare di carta verrà reindirizzato nuovamente al sito Web dell’esercente, a cui verranno trasmessi i dettagli relativi all’esito del pagamento.

Le fasi del processo di richiesta di autorizzazione utilizzando BuyNow, possono essere descritte in questi step:Il Cliente (titolare di carta) visita il web store e riempie il carrello; al termine della scelta degli articoli di acquisto, il web store ridirige il cliente al form BuyNow: nessuna informazione relativa alla carta di credito verrà conservata lato esercente;

  • Il web server di BuyNow mostra il form per il pagamento, raccoglie i dati (PAN, scadenza carta, CCV2) immessi attraverso una connessione SSL;
  • e-POSitivity provvede all’interrogazione della DirectoryServer per la verifica dell’iscrizione al servizio di 3DSecure;
  • Nel caso di risposta positiva, il MerchantPlugIn (MPI) passa il controllo all’AccessControl Server (ACS) dell’emittente carta (issuer) che permette al cliente (titolare di carta) di inserire la password (in caso di transazione con Verified By Visa o MasterCard Securecode);
  • Verificata l’iscrizione al servizio 3D Secure si procede all’invio della richiesta di autorizzazione versoi circuiti.

La risposta con l’esito dell’operazione verrà inviata sia all’esercente sia al titolare di carta. Il titolare di carta, oltre a visualizzarla sul suo browser, riceve anche un’e-mail di conferma.

Questa è la pagina di pagamento (Fig. 3) di e-POSitivity; il layout della stessa potrà in parte essere personalizzato inoltrando una richiesta a Axepta.

E’ possibile personalizzare:il logo esercente (immagine d’intestazione)

  • l’immagine a piè di pagina
  • il colore dello sfondo
  • il font, la dimensione, lo stile (corsivo, grassetto…) e il colore dei testi
  • il colore dei pulsanti

Per poter customizzare la pagina di pagamento, bisogna formattare i seguenti file:

  • screen.css
  • footer.html
  • header.html

Con il file css è possibile formattare il testo e la dimensione delle componenti della pagina di pagamento, invece utilizzando i file html è possibile caricare le url di eventuali loghi. Il logo deve risedere sul server dell’esercente.

NOTA BENE: Al momento dell’upload, i file personalizzati non dovranno contenere commenti. File contenenti linee di commento verranno scartati.

Per iniziare l’integrazione è fondamentale richiedere a BNLPOSitivity l’accesso ai servizi. Dopo l’abilitazione verranno forniti i seguenti parametri da valorizzare durante le inizializzazioni per le richieste di autorizzazione.

Parametri necessari:

  • Terminal id (storename)
  • Ksig
  • Serverurl

Questa sezione propone un semplice esempio per integrare il vostro sito Web con e-POSitivity. Le pagine di esempio sono proposte utilizzando i seguenti linguaggi di programmazione:

  • ASP.NET
  • php
  • java

si presuppone che lo sviluppatore abbia una conoscenza di base del linguaggio scelto.

Nell’ambiente di test è possibile effettuare delle transazioni utilizzando queste carte di credito:

PAN CARTA CIRCUITO SCADENZA CVV ISCRIZIONE 3DS ESITO 3DS
4557773333333335 Visa SI OK
4557772222222229 Visa SI OK
4111111111111111 Visa 10/2023 NO
4555000000000001 Visa NO
4111111112225555 Visa NO
4011514444441116 Visa Electron NO
4011519992222222 Visa Electron NO
4005000000000007 Visa Debit 10/2023 NO
4005004455555556 Visa Debit NO
5430132222222226 Mastercard NO
5893535544444429 Mastercard NO
5790640100000005 Mastercard NO
5430131234567891 Mastercard SI KO
5548535889622125 Mastercard SI OK
5401172222222227 Mastercard SI OK
5430132222222226 Mastercard NO OK
5548536000000126 Mastercard SI OK
5264921111111115 Mastercard Debit 555 NO
5545910000000019 Mastercard Debit SI KO
5020639451965933 Maestro SI OK
5893535596092423 Maestro SI KO

ATTENZIONE: laddove specificato, è importante rispettare la giusta data di scadenza e/o il codice CVV. In caso contrario la transazione sarà rifiutata.

Sono in vigore i alcuni test cases in ambiente di test, attraverso i quali è possibile simulare il comportamento del gateway al verificarsi di alcune condizioni che invaliderebbero la transazione. Questi rispondono alle seguenti combinazioni PAN – IMPORTO:

PAN CARTA IMPORTO (EUR) ESITO IGFS DESCRIZIONE
4557773333333335

5401172222222227

4557772222222229

5548536000000126

5020639451965933

101,00 IGFS_008 Autorizzazione negata
102,00 IGFS_021 Codice merchant errato
103,00 IGFS_020 Carta invalida
104,00 IGFS_119 Operazione non permessa al titolare
105,00 IGFS_123 Superato limite frequenza
106,00 IGFS_209 Carta rubata
107,00 IGFS_005 Errore di formato
108,00 IGFS_107 Contattare issuer
109,00 IGFS_102 Sospetta frode
5430132222222226

4111111111111111

4011519992222222

4005000000000007

5264921111111115

103,00 IGFS_030 Fondi insufficienti
104,00 IGFS_119 Operazione non permessa al titolare
105,00 IGFS_123 Superato limite frequenza
5401172222222227

5264921111111115

> 200 IGFS_030 Fondi insufficienti

Di seguito i parametri ed i link per integrarsi con il nostro ambiente di test, utilizzando un terminale generico:

 Parametri  Valori
 url di test  https://pftest.bnlpositivity.it/service/
 ksig  xHosiSb08fs8BQmt9Yhq3Ub99E8=
 TerminalId  08000001_S

Accesso Back Office, per il monitoraggio e la gestione delle transazioni effettuate:

PARAMETRI VALORI
url di test https://testbnl.netsw.it/BNL_CG_BO_WEB
username mhtest2
password Mhtest2016