RICHIEDI ORA
Area sviluppatori 2017-12-18T14:23:55+00:00

Integrazione API & Web Services

Integrazione API & Web Services

INFORMAZIONI SULL’ ASSISTENZA

La guida per l’integrazione di e–POSitivityche 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 BNL POSitivity 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 BNL POSitivity. Per alcune categorie merceologiche è possibile che vi siano delle restrizioni nell’accettazione delle carte MasterCard e Maestro: in tali casi BNL POSitivity fornisce un avviso preventivo in fase di definizione del contratto
  • L’iscrizione a Verified By Visae 3D Secure Code è a carico di BNL POSitivity (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 BNL POSitivity o il Servizio Esercenti. BNL POSitivityb 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 BNL POSitivity.
  • Per l’attivazione di Masterpass rivolgersialla rete di vendita di BNL POSitivity o al servizio di assistenza e-commerce.
  • Per l’attivazione di MyBank rivolgersialla rete di vendita di BNL POSitivityo 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
    • BNL POSitivity provvede ad abilitare PayPal sul POS virtuale e-POSitivity.

L’esercente può inviare richieste di autorizzazione verso e-POSitivitycon 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 a BNL POSitivity 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:

ParametriValori
url di testhttps://testbnl.netsw.it/BNL_CG_BO_WEB
usernamemhtest2
passwordMhtest2016

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

Pan CartaCircuitoScadenzaCVVIscrizione 3DSEsito 3DS
4557773333333335VisaSIOK
4557772222222229VisaSIOK
4111111111111111Visa10/2023NO
4555000000000001VisaNO
4111111112225555VisaNO
4011514444441116Visa ElectronNO
4011519992222222Visa ElectronNO
4005000000000007Visa Debit10/2023NO
4005004455555556Visa DebitNO
5430132222222226MastercardNO
5893535544444429MastercardNO
5790640100000005MastercardNO
5430131234567891MastercardSIKO
5548535889622125MastercardSIOK
5401172222222227MastercardSIOK
5430132222222226MastercardNOOK
5548536000000126MastercardSIOK
5264921111111115Mastercard Debit555NO
5545910000000019Mastercard DebitSIKO
5020639451965933MaestroSIOK
5893535596092423MaestroSIKO

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 CARTAIMPORTO (EUR)ESITO IGFSDESCRIZIONE
4557773333333335
5401172222222227
4557772222222229
5548536000000126
5020639451965933
101,00IGFS_008Autorizzazione negata
102,00IGFS_021Codice merchant errato
103,00IGFS_020Carta invalida
104,00IGFS_119Operazione non permessa al titolare
105,00IGFS_123Superato limite frequenza
106,00IGFS_209Carta rubata
107,00IGFS_005Errore di formato
108,00IGFS_107Contattare issuer
109,00IGFS_102Sospetta frode
5430132222222226
4111111111111111
4011519992222222
4005000000000007
5264921111111115
103,00IGFS_030Fondi insufficienti
104,00IGFS_119Operazione non permessa al titolare
105,00IGFS_123Superato limite frequenza
5401172222222227
5264921111111115
> 200IGFS_030Fondi 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

Integrazione Modulo HTML

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 BNL POSitivity. Per alcune categorie merceologiche è possibile che vi siano delle restrizioni nell’accettazione delle carte MasterCard e Maestro: in tali casi BNL POSitivity fornisce un avviso preventivo in fase di definizione del contratto
  • L’iscrizione a Verified By Visae 3D Secure Code è a carico di BNL POSitivity (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 BNL POSitivity o il Servizio Esercenti. BNL POSitivityb 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 BNL POSitivity.
  • 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
    • BNL POSitivity 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 BNLPOSitivity.
  • Per l’attivazione di Masterpass rivolgersi alla rete di vendita di BNL POSitivity o al servizio di assistenza e-commerce.

Questo servizio consiste nell’utilizzo di una pagina di pagamento fornita da BNL POSitivity residente sui nostri server. Con questa soluzione, il titolare di carta viene indirizzato, al momento del pagamento, sulla pagina di BNLPOSitivity 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 BNLPOSitivity.

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 CARTACIRCUITOSCADENZACVVISCRIZIONE 3DSESITO 3DS
4557773333333335VisaSIOK
4557772222222229VisaSIOK
4111111111111111Visa10/2023NO
4555000000000001VisaNO
4111111112225555VisaNO
4011514444441116Visa ElectronNO
4011519992222222Visa ElectronNO
4005000000000007Visa Debit10/2023NO
4005004455555556Visa DebitNO
5430132222222226MastercardNO
5893535544444429MastercardNO
5790640100000005MastercardNO
5430131234567891MastercardSIKO
5548535889622125MastercardSIOK
5401172222222227MastercardSIOK
5430132222222226MastercardNOOK
5548536000000126MastercardSIOK
5264921111111115Mastercard Debit555NO
5545910000000019Mastercard DebitSIKO
5020639451965933MaestroSIOK
5893535596092423MaestroSIKO

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 CARTAIMPORTO (EUR)ESITO IGFSDESCRIZIONE
4557773333333335

5401172222222227

4557772222222229

5548536000000126

5020639451965933

101,00IGFS_008Autorizzazione negata
102,00IGFS_021Codice merchant errato
103,00IGFS_020Carta invalida
104,00IGFS_119Operazione non permessa al titolare
105,00IGFS_123Superato limite frequenza
106,00IGFS_209Carta rubata
107,00IGFS_005Errore di formato
108,00IGFS_107Contattare issuer
109,00IGFS_102Sospetta frode
5430132222222226

4111111111111111

4011519992222222

4005000000000007

5264921111111115

103,00IGFS_030Fondi insufficienti
104,00IGFS_119Operazione non permessa al titolare
105,00IGFS_123Superato limite frequenza
5401172222222227

5264921111111115

> 200IGFS_030Fondi 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:

PARAMETRIVALORI
url di testhttps://testbnl.netsw.it/BNL_CG_BO_WEB
usernamemhtest2
passwordMhtest2016