Gateway di pagamento online Autopay - DocumentazionePobierz

Autopay Online Payments è una soluzione completa per l'accettazione dei pagamenti da parte dei clienti dei negozi online, che supporta diversi metodi di pagamento disponibili sul mercato, come bonifici, Pay by link, BLIK, Google Pay, Apple Pay.
In questa documentazione troverete tutto ciò che vi serve per implementare rapidamente il gateway di pagamento nel vostro negozio online.
La documentazione sui pagamenti online Autopay comprende sezioni come Gestione delle transazioni e dei regolamenti, Estensioni aggiuntive.

Definizioni

Applicazione - L'applicazione mobile del partner, che comunica con la Sistema di pagamento online Autopay SDK per registrare le transazioni.

AP - Autopay S.A. Società con sede a Sopot, in Powstańców Warszawy 6, registrata presso il Tribunale distrettuale di Danzica-Nord a Danzica, Divisione commerciale VIII del Registro nazionale dei tribunali con il numero KRS 0000320590, con codice fiscale (NIP) 585-13-51-185, REGON 191781561, con capitale sociale di 2 205 500 PLN (interamente versato), sottoposta a vigilanza da parte della Commissione di vigilanza finanziaria e registrata come istituto di pagamento nazionale ai sensi dell'IP17/2013, proprietaria del Sistema.

BalancePoint (punto di regolamento) - un'entità all'interno del Sistema di pagamento che rappresenta un Negozio integrato con la Piattaforma Marketplace e che si è registrata nel Sistema di pagamento utilizzando un modulo fornito da AP al Partner.

ClientHash - un parametro nei messaggi; consente di assegnare uno strumento di pagamento (ad esempio, una carta) a un cliente in modo anonimo. Su questa base, il Partner può avviare gli addebiti successivi nel modello di pagamento automatico.

Modello di Commissione - un modello di commissione stabilito con l'integratore. Descrive i valori delle commissioni per le transazioni trasferite all'AP e all'integratore.

Giorno lavorativo - al giorno dal lunedì al venerdì, esclusi i giorni festivi polacchi.

Modulo di integrazione - una pagina web in cui è disponibile un modulo che consente al Cliente di registrarsi, modificare o aggiungere un nuovo Servizio.

Strumento di pagamento (Canale di pagamento) - un insieme di procedure o un dispositivo personalizzato concordato dal Cliente e dal suo fornitore, utilizzato dal Cliente per avviare un ordine di pagamento, ad esempio Carta, PBL.

Strumento di trasferimento elettronico - una serie di procedure o un dispositivo personalizzato concordato dal Partner e dall'AP, utilizzato dal Partner per avviare un ordine di pagamento che consente il prelievo di fondi dal saldo sul conto bancario del Partner o del Cliente e da un altro strumento di pagamento di proprietà del Partner o del Cliente. La disponibilità della funzionalità dipende da accordi individuali tra il Partner e l'AP.

Integratore - Gli integratori sono i cosiddetti partner che hanno implementato Autopay Online Payments nei loro sistemi e ne consentono l'attivazione dalle loro soluzioni. Tra gli integratori figurano entità come Shoper, Sky-Shop, Gymsteer, Selly verifications, FaniMani, AtomStore, Ebexo, Selly Azymut, PayNow, Comarch.

IPN (Notifica immediata del prodotto) - notifica immediata inviata dal Sistema di pagamento online al Servizio partner che comunica una modifica dello stato del prodotto. La struttura dell'IPN è simile a quella dell'ITN (ampliata solo dal nodo prodotto).

ITN (Notifica di transazione istantanea)- notifica immediata inviata dal Sistema di pagamento online al Servizio partner che trasmette una modifica dello stato della transazione.

ISTN (Notifica istantanea di transazione di regolamento) - notifica immediata della modifica dello stato di un'operazione di regolamento. Il sistema trasmette immediatamente le notifiche relative all'ordine di un'operazione di regolamento (eventuali ritiri/restituzioni) e alla modifica del suo stato.

ICN (Notifica di configurazione istantanea) - notifica immediata della configurazione di un negozio appena registrato, comunicazione di informazioni sulla modifica dello stato della carta del negozio (ad esempio, in caso di attivazione della carta). I messaggi ICN possono essere inviati anche in caso di modifica della configurazione del negozio, di variazione dei dati AML, di abilitazione/disabilitazione di un canale di pagamento. La fornitura di funzionalità è soggetta ad accordi individuali tra il Partner e l'AP.

Scheda - Una carta di pagamento emessa nell'ambito dei sistemi VISA e Mastercard, autorizzata dai regolamenti di tali sistemi a eseguire transazioni senza la sua presenza fisica.

Cliente (pagatore) - una persona che effettua un pagamento sul Sito web per servizi o prodotti di un Partner utilizzando il Sistema.

Cestino prodotti - Si tratta delle informazioni sulle componenti del pagamento, trasferite (nel link di pagamento) al Sistema per la successiva elaborazione. Ogni prodotto del carrello è descritto da due campi obbligatori: l'importo costituente e un campo che consente il trasferimento di parametri specifici del prodotto.

Link per il pagamento - richiesta che abilita l'inizio di una Transazione di Ingresso (descritta nella parte Inizio della transazione). Può essere utilizzato direttamente sul sito web (metodo POST), mentre nelle e-mail ai clienti deve essere utilizzato Pre-transazione per ottenere un breve link al pagamento (metodo GET).

Link di verifica - URL che indirizza al Trasferimento di verifica.

Mercato - una soluzione di pagamento che opera nell'ambito del Sistema di pagamento online Autopay. Consente al Partner di gestire una piattaforma di vendita in cui i prodotti o i servizi sono offerti ai clienti dagli Appaltatori del Partner. I modelli di regolamento avanzati per le Transazioni e le Transazioni di regolamento consentono di effettuare pagamenti direttamente dal Cliente al Contraente Partner, tenendo conto del Paniere dei prodotti. La fornitura della funzionalità è soggetta ad accordi individuali tra il Partner e AP.

Modello di pagamento - un modello in cui la commissione per la transazione effettuata viene pagata dal cliente all'AP (costo aggiunto all'importo della transazione). In questo caso, il cliente accetta anche i termini e le condizioni di AP durante il pagamento.

Modello del commerciante - un modello in cui la commissione viene regolata tra Autopay e il partner e non viene aggiunta all'importo della transazione pagato dal cliente.

Partner - l'entità destinataria dei fondi derivanti dalla vendita di prodotti o servizi distribuiti dall'Affiliato sul Sito.
Un partner, nel caso del modello Marketplace, è un'entità, che non è un consumatore, interessata a gestire l'accettazione da parte di AP dei pagamenti dovuti al partner per i prodotti o i servizi distribuiti dal partner.

Pay By Link (PBL) - uno strumento per effettuare pagamenti tramite bonifico interbancario dal conto del cliente al conto dell'AP. Dopo aver effettuato l'accesso all'online banking, i dati necessari per l'esecuzione del bonifico (dati del destinatario, numero del suo conto corrente, importo e data di esecuzione del bonifico) vengono inseriti automaticamente grazie al sistema di scambio di dati tra banca e AP.

Agente tecnico - l'entità con il diritto di accedere al Conto di pagamento del Partner, che autorizza tale accesso (consenso o accordo). Nel sistema, la procura è rappresentata dalla configurazione dell'opzione ID plenipotenziarioUn'entità può avere più deleghe per diversi Partner.

Piattaforma di mercato - piattaforma su cui è disponibile l'opzione di registrazione dei Punti di regolamento.

Pagamento automatico - pagamento effettuato senza dover inserire ogni volta i dati della Carta o i dati per autorizzare il trasferimento.

Pagamento con un solo clic - è un pagamento automatico ordinato dal cliente.

Pagamento ciclico - è un pagamento automatico ordinato senza l'intervento del cliente (da parte del Servizio partner).

Pre-transazione - collegamento specifico (eseguito in background) per il pagamento dell'ordine.

Trasferimento di verifica - La parte del processo relativa alla registrazione e alla modifica dei Servizi del Partner nel Sistema. Consiste nell'esecuzione di un trasferimento di fondi da parte del Partner per verificare i dati e il conto bancario per l'erogazione dei fondi al Partner. La verifica dei dati è un obbligo dell'AP derivante, tra l'altro, dalla legge del 16/11/2000 sulla prevenzione del riciclaggio di denaro e del finanziamento del terrorismo. Ogni trasferimento di verifica deve ricevere lo stato di verifica finale (positivo o negativo) entro 30 giorni dal pagamento della transazione. Se lo stato di verifica finale non viene fornito entro i termini sopra indicati, il sistema attribuirà automaticamente uno stato negativo. Questo processo si applica alle verifiche in cui Autopay invia una richiesta di completamento dei dati al cliente e non riceve le informazioni di ritorno necessarie per effettuare tale verifica.

Conto di pagamento (saldo) - conto di pagamento gestito da AP per il Partner, sul quale vengono raccolti i fondi depositati dai Clienti. La fornitura della funzionalità è soggetta ad accordi individuali tra il Partner e AP.

RPAN (Notifica di attivazione del pagamento ricorrente) - messaggio di attivazione del servizio di pagamento automatico.

RPDN (Notifica di disattivazione dei pagamenti ricorrenti) - messaggio di disattivazione del servizio di pagamento automatico.

Servizio - il sito web del Partner o i siti web integrati con il Sistema, dove il Cliente può acquistare prodotti o servizi dal Partner (o dalla Controparte del Partner nel caso del Marketplace).
Nel caso di un Marketplace, un oggetto nel Sistema di pagamento che rappresenta il Marketplace del Partner. Tutte le transazioni avviate da tale Marketplace sono collegate ad esso.

Specifiche - documentazione che descrive la comunicazione tra il Servizio e il Sistema.

Sistema di pagamento online AP (sistema) - una soluzione informatica e funzionale in base alla quale l'AP fornisce al Partner un'applicazione per elaborare i pagamenti dei clienti effettuati con l'uso di Strumenti di Pagamento, nonché per verificare lo stato dei pagamenti e ricevere i pagamenti.

Trasferimento veloce - esecuzione di pagamenti tramite bonifico intrabancario dal conto del Cliente al conto dell'AP. Il pagamento effettuato tramite PBL si differenzia dai pagamenti effettuati tramite PBL in quanto il Cliente deve compilare personalmente tutti i dati necessari per effettuare il trasferimento.

Transazione - indica un'operazione di pagamento ai sensi della Legge polacca del 19 agosto 2011 sui servizi di pagamento.

Transazione di ingresso - parte del processo di gestione dei pagamenti relativi al pagamento effettuato dal cliente ad AP.

Transazione di regolamento - parte del processo di elaborazione del pagamento, relativo al trasferimento effettuato da AP sul conto del Partner. Affinché venga creata una Transazione di regolamento, la Transazione di input deve essere pagata dal Cliente. Una Transazione di regolamento può riguardare una singola Transazione di ingresso (pagamento) o aggregarne diverse.

Atto - Legge polacca del 19 agosto 2011 sui servizi di pagamento.

Validità del link - parametro che specifica il momento oltre il quale il Collegamento di pagamento cessa di essere attivo. Deve essere impostato dall'utente LinkValidityTime nel Link di pagamento.

Validità delle transazioni - parametro che specifica il momento oltre il quale il Collegamento di pagamento cessa di essere attivo. Deve essere impostato dal parametro LinkValidityTime del Collegamento di pagamento.

Widget per l'autopagamento - un meccanismo che consente il pagamento con Carta per i prodotti/servizi offerti dal Partner, in cui i dati della Carta vengono inseriti dal Cliente nel meccanismo incorporato direttamente nel sito Web del Partner. L'attivazione del formato widget della Carta richiede l'implementazione di codice JavaScript utilizzando una libreria AP dedicata.

Widget di onboarding - una soluzione che consente all'Integratore di incorporare il Modulo Integratore (preparato da Autopay) direttamente sul sito web dell'Integratore, in modo che il Partner non venga reindirizzato al dominio Autopay quando registra il proprio negozio - l'intero processo viene eseguito sul sito web del Partner.

Etichetta bianca - modello di integrazione, in cui il cliente già presente sul Servizio seleziona il canale di pagamento e ne accetta le norme e i regolamenti (a condizione che la necessità di accettarli derivi da accordi individuali tra il Partner e l'AP), e l'inizio della transazione include un'operazione completata GatewayID (e in alcuni casi DefaultRegulationAcceptanceID o RecurringAcceptanceID).

Avvio di un ordine di pagamento - il momento in cui l'utente del gateway di pagamento seleziona un canale di pagamento e viene reindirizzato alla pagina corrispondente al canale di pagamento selezionato oppure (per i pagamenti automatici, i portafogli elettronici o BLIK) viene effettuato un tentativo di addebito sulla carta o sul conto presso il fornitore del canale di pagamento.

Indirizzi ambientali

TEST

• gate_host: https://testpay.autopay.eu

• cards_gate_host: https://testcards.autopay.eu

PRODUZIONE

• gate_host: https://pay.autopay.eu

• cards_gate_host: https://cards.autopay.eu

Elaborazione di transazioni e regolamenti

Diagramma di flusso del servizio di transazione e compensazione

Sul Sito del Partner, dopo aver completato l'ordine, al Cliente viene presentata la possibilità di effettuare un pagamento tramite il Sistema. Facendo clic sul link appropriato si avvia la transazione e si apre una nuova finestra:

a) una pagina dedicata del Sistema predisposta da AP, in cui al Cliente viene presentato l'elenco dei Canali di pagamento disponibili e il riepilogo dell'operazione registrata oppure

b) direttamente da un canale di pagamento (banca, BLIK o per il pagamento con carta).

Dal lato del sistema, i parametri trasmessi vengono convalidati e la transazione viene salvata con un periodo di validità prestabilito. Se, al momento della convalida, il periodo di validità del collegamento è già superato, il Cliente riceverà un messaggio appropriato (la verifica della validità della transazione avviene anche quando viene modificato lo stato di pagamento). Dopo la verifica positiva dei parametri della transazione (e dopo la selezione del Canale di pagamento), il Cliente autorizza la transazione. Nel suo titolo, oltre agli identificativi assegnati dal Sistema, può essere presente anche una descrizione fissa, concordata in anticipo tra l'AP e il Partner, oppure un valore dinamico fornito dal Partner all'inizio della transazione.

Il modello di integrazione consigliato è quello di trasmettere un messaggio per avviare una transazione in background, cioè senza reindirizzare l'utente al sistema (vedi Pre-transazione). In questo modello è possibile utilizzare forme avanzate di autorizzazione delle transazioni (WhiteLabel, pagamenti automatici, SDK mobile), diagnosi della correttezza dei parametri trasmessi e molte altre estensioni.

Una volta autorizzata la transazione (nella pagina del Canale di pagamento), il Cliente torna da questa al Sistema, dove viene automaticamente reindirizzato al Servizio del partner.

CONSIGLIO: Una descrizione dettagliata della struttura del link di ritorno si trova nella parte del file Reindirizzamento al sito del partner.

Lo stato di autorizzazione (pagamento) ricevuto dal Canale di pagamento viene trasmesso dal Sistema al Servizio partner tramite un messaggio ITN. Il Sistema continuerà a inviare messaggi fino a quando la ricezione non sarà confermata dal Servizio partner o fino alla scadenza del periodo di validità della notifica. Le transazioni pagate dopo la scadenza del periodo di validità della transazione - saranno restituite al Cliente (mittente del bonifico).

Facoltativamente, il sistema può notificare l'emissione di una transazione di regolamento
. A tal fine viene utilizzato un messaggio ISTN opportunamente modificato.

Fasi di integrazione della gestione di transazioni e regolamenti

Dati necessari per l'integrazione dell'elaborazione delle transazioni e dei regolamenti

I dati richiesti scambiati durante l'integrazione differiscono per gli ambienti di test e di produzione. Di seguito è riportato un elenco dei parametri passati da AP a Partner e nella direzione inversa.

Vengono inoltre fornite informazioni generali, ad esempio i canali di pagamento attivi con grafica (come risultato dell'interrogazione dell'elenco dei canali di pagamento disponibili).

Facoltativamente, il Partner può trasmettere ulteriori dati all'AP, ad esempio: informazioni sul contenuto richiesto del carrello e sul modo in cui viene elaborato (nei report, nella fatturazione, nel pannello di amministrazione), requisiti aggiuntivi (per la ricarica del saldo prepagato). Per
pagamenti automatici BLIK anche la durata di vita predefinita dei pagamenti automatici attivati e l'etichetta predefinita dei pagamenti automatici attivati.

Dati scambiati nell'ambiente di test

Dati forniti dal Partner all'AP:

• Indirizzo per i messaggi ITN
• Indirizzo per i messaggi RPAN (può essere lo stesso dei messaggi ITN) [per i pagamenti automatici].
• Indirizzo per i messaggi RPDN (può essere lo stesso dei messaggi ITN) [per i pagamenti automatici].
• Indirizzo di pagamento (senza parametri)

Dati trasferiti dall'AP al Partner:

• Indirizzo del sistema di pagamento online
• ID servizio
• AcceptorID [per i portafogli nel modello WhiteLabel].
• Chiave condivisa
• Risultato dell'hashtag
• Indirizzo del modulo di prova
• Indirizzo IP da cui vengono inviati gli ITN
• Indirizzo del pannello di amministrazione
• Accesso
• Password

Dati trasferiti in un ambiente di produzione

Da Partner ad AP:

• Indirizzo per i messaggi ITN
• Indirizzo per i messaggi RPAN (può essere lo stesso dei messaggi ITN) [per i pagamenti automatici].
• Indirizzo per i messaggi RPDN (può essere lo stesso dei messaggi ITN) [per i pagamenti automatici].
• Indirizzo di pagamento (senza parametri)
• Indirizzi e-mail per i rapporti sulle transazioni
• Indirizzi e-mail per fatture e rapporti di fatturazione
• Indirizzi e-mail per i reclami (inviati nei messaggi ai pagatori)

Da AP a Partner:

• Indirizzo del sistema di pagamento online
• ID servizio
• AcceptorID [per i portafogli nel modello WhiteLabel].
• Chiave condivisa
• Risultato dell'hashtag
• Indirizzo del modulo di prova
• Indirizzo IP da cui vengono inviati gli ITN
• Indirizzo del pannello di amministrazione
• Accesso
• Password

Implementazione di interfacce e processi da parte del partner

Nella versione minima dell'integrazione, dovrebbe essere implementato il supporto per l'avvio di una transazione, il ritorno da essa e il supporto per la comunicazione ITN.

CONSIGLIO: Si consiglia di familiarizzare con lo schema di funzionamento. Se necessario, si consiglia di familiarizzare anche con parametri o servizi aggiuntivi.

Test di integrazione e migrazione all'ambiente di produzione

Durante il test, i campi bianchi del foglio devono essere completati e rinviati all'AP per confermare la corretta integrazione prima della migrazione all'ambiente di produzione.

CONSIGLIO: Prima della distribuzione in produzione, si consiglia di eseguire i test in conformità con le istruzioni per l'uso. scenari di prova nella versione base e, per le integrazioni più avanzate, anche in base a scenari aggiuntivi.

Inizio della transazione

Descrizione dell'inizio della transazione

Il servizio del Partner che avvia la transazione trasmette al Sistema di pagamento online i parametri necessari per completare la transazione e la successiva trasmissione dello stato di pagamento.

Tutti i parametri vengono passati tramite il metodo POST (Tipo di contenuto: application/x-www-form-urlencoded).

Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi che nei valori dei parametri. I valori dei parametri trasmessi devono essere codificati in UTF-8 (e il protocollo di trasporto - codifica prima dell'invio, a meno che lo strumento utilizzato per inviare il messaggio non lo faccia da solo, esempio di codifica: URLEncode).

Elenco dei parametri di avvio della transazione

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione
.

Metodo di avvio di una transazione

La transazione viene avviata inviando una chiamata HTTPS una combinazione dei parametri di cui sopra all'indirizzo del sistema di pagamento online stabilito durante la registrazione del servizio.

IMPORTANTE: Il numero di transazioni avviate dal Partner in un minuto può essere al massimo di 100, a meno che il Partner e l'AP non concordino un limite superiore nell'ambito dell'accordo stipulato.

Esempio di avvio di una transazione:

Indirizzo:

• https://{gate_host}/path

Parametri:

• ServiceID=2

• OrderID=100

• Importo=1,50

    Hash=2ab52e6918c6ad3b69a8228a2ab815f11ad58533eeed963dd990df8d8c3709d1
  

Invio di un messaggio senza tutti richiesto parametri (ServiceID, OrderID, Importo e Hash) o contenenti valori errati, causerà l'interruzione del processo di pagamento con un codice di errore della transazione e un breve messaggio di errore (senza ritorno alla pagina Partner Service).

IMPORTANTE! La coppia di parametri ID servizio e ID ordine identifica univocamente la transazione. Non è consentito che il valore dell'elemento ID ordine da ripetere per l'intero periodo di servizio fornito dal Sistema a un singolo Servizio partner (ID servizio).

Il parametro opzionale GatewayID viene utilizzato per specificare il Canale di pagamento attraverso il quale deve essere effettuato il pagamento. Ciò consente di trasferire al Servizio la schermata di selezione dei canali di pagamento. L'elenco attuale degli ID dei canali di pagamento, compresi i loghi, è disponibile tramite il pulsante gatewayList metodo.

Il messaggio di avvio della transazione può essere trasmesso in background, cioè senza reindirizzare l'utente al Sistema di pagamento online. In questo modello, anche la selezione del Canale di pagamento viene effettuata dal Cliente sul Servizio partner.

Reindirizzamento al sito del partner

Descrizione del reindirizzamento al sito del partner

Subito dopo il completamento dell'autorizzazione della transazione da parte del Cliente, quest'ultimo viene reindirizzato dal sito del Canale di Pagamento al sito online del Sistema di Pagamento, dove il Cliente viene automaticamente reindirizzato al Servizio del Partner. Il reindirizzamento avviene tramite l'invio di una richiesta HTTPS (con metodo GET) a un indirizzo di ritorno predeterminato sul Servizio del Partner. Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi che nei valori dei parametri.

Elenco dei parametri di reindirizzamento per il sito partner

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Esempio di messaggio che reindirizza il Cliente dal sistema di pagamento online al Sito del Partner

https://shop_name/return_page?ServiceID=123458&OrderID=123402816&Hash=5432d69a66d721b2f5f785432bf5a1fc1b913bdb3bba465856a5c228fe95c1f8

Notifiche istantanee (ITN)

Descrizione delle notifiche istantanee

Il Sistema trasmette le notifiche di variazione dello stato di una transazione non appena riceve tale informazione dal Canale di Pagamento e il messaggio si riferisce sempre a una singola transazione.

NOTA: Il dominio deve essere pubblico e accessibile tramite il sistema. Il dominio deve essere protetto da un certificato valido emesso da un'autorità di certificazione pubblica (Autorità di certificazione) Il server deve presentare una catena di certificati completa (Catena di fiducia) La comunicazione deve essere basata sul protocollo TLS versione 1.2 o 1.3 *Altre forme di sicurezza della connessione, ad esempio VPN, mTLS devono essere concordate individualmente con il responsabile dell'implementazione.

Esempio:

https://shop_name/status_receive

La notifica di una modifica dello stato di una transazione in ingresso consiste nell'invio da parte del Sistema di un documento XML contenente i nuovi stati della transazione.

Il documento viene inviato tramite HTTPS (porta predefinita 443) - utilizzando il metodo POST, come parametro HTTP con il nome transazioni. Questo parametro viene memorizzato utilizzando il meccanismo di crittografia di trasporto Base64.

Formato del documento (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
		<serviceID>ServiceID</serviceID>
		<transactions>
			<transaction>
				<orderID>OrderID</orderID>
				<remoteID>RemoteID</remoteID>
				<amount>999999.99</amount>
				<currency>PLN</currency>
				<gatewayID>GatewayID</gatewayID>
				<paymentDate>YYYYMMDDhhmmss</paymentDate>
				<paymentStatus>PaymentStatus</paymentStatus>
				<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
			</transaction>
		</transactions>
		<hash>Hash</hash>
	</transactionList>

NOTA: A transazioni può contenere solo un nodo transazione (quindi la notifica riguarda sempre una transazione). I valori degli elementi ID ordine e importo relativi a ciascuna transazione sono identici ai valori dei campi corrispondenti forniti dal Servizio partner all'inizio della rispettiva transazione. Fanno eccezione i modelli in cui la commissione viene aggiunta all'importo della transazione. In questi casi, il valore dell'importo nell'ITN viene aumentato di questa commissione. La convalida degli importi può quindi essere effettuata sulla base del campo opzionale ITN importo iniziale. Tuttavia, questo campo deve essere richiesto durante l'integrazione.

Elenco dei parametri restituiti per le notifiche istantanee

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

CONSIGLIO: Elemento hash (messaggio) viene utilizzato per autenticare
il documento. Per una descrizione di come viene calcolato l'hash, vedere la sezione Sicurezza delle transazioni.

Risposta alla notifica immediata

In risposta alla notifica, ci si aspetta uno stato HTTP di 200 (OK) e
un testo in formato XML (Base64 non codificato), restituito dal metodo
Servizio Partner nella stessa sessione HTTP, contenente una conferma di ricezione
dello stato della transazione.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<transactionsConfirmations>
			<transactionConfirmed>
				<orderID>OrderID</orderID>
				<confirmation>Confirmation</confirmation>
			</transactionConfirmed>
		</transactionsConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Descrizione dei campi di conferma per le notifiche immediate

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

In assenza di una risposta corretta alle notifiche inviate, il Sistema farà ulteriori tentativi per comunicare lo stato più recente della transazione dopo che è trascorso il tempo specificato. Il Servizio partner deve eseguire la propria logica di business (ad esempio, l'invio di un'e-mail di conferma) solo dopo il primo <messaggio relativo a un determinato stato di pagamento.

CONSIGLIO: Vale la pena di dare un'occhiata a Schema di ritrasmissione dei messaggi ITN/ISTN/IPN/RPAN/RPDN.

Descrizione dettagliata del comportamento e della modifica degli stati di pagamento (paymentStatus)

Il metodo di pagamento scelto dal cliente invierà uno stato di IN ATTESA ogni volta. Nel successivo messaggio ITN, il sistema fornirà lo stato SUCCESSO o FALLIMENTO.

NOTA Il IN ATTESA lo stato non viene inviato se:

• il Cliente abbandona o ritorna dalla schermata dell'elenco dei metodi di pagamento senza selezionare un metodo specifico. In questo caso, il FALLIMENTO sarà inviato immediatamente. Lo stato PENDING non apparirà perché il cliente non ha avviato il processo di pagamento.
• Lo stato finale (SUCCESSO o FALLIMENTO) sarà consegnato prima dell'invio dell'ITN con lo stato IN ATTESA.

Per una singola transazione (con parametri unici ID ordine e ID remoto), non ci può essere un cambiamento di stato da SUCCESSO è IN ATTESA o SUCCESSO è FALLIMENTO.

In ogni caso, potrebbe verificarsi una modifica dello stato dei dettagli. pagamentoStatoDettagli (i messaggi successivi relativi a un cambiamento di stato dei dettagli sono solo a titolo informativo e non devono portare a ripetere l'invio del servizio/prodotto a pagamento, ecc.)

In casi particolari di utilizzo, può verificarsi un cambiamento di stato:

a) FALLIMENTO è SUCCESSO (ad esempio, dopo che un consulente AP ha approvato una transazione pagata con un importo errato. Questo comportamento richiede accordi commerciali speciali e non è abilitato per impostazione predefinita),

b) SUCCESSO è FALLIMENTO (ad esempio, dopo l'attivazione di più transazioni con la stessa ID ordine ma diverso ID remoto). Un caso del genere si verifica quando un Cliente avvia più pagamenti con lo stesso ID ordine (ad esempio, il Cliente cambia la sua decisione su quale Canale di Pagamento vuole pagare la transazione). Ciascuno dei pagamenti da lui avviati genera ITN e le singole transazioni devono essere distinte con il simbolo ID remoto parametro. Poiché l'ora di ricezione del FALLIMENTO Lo stato può variare notevolmente, può succedere che tale stato venga ricevuto dopo che SUCCESSO è stato ricevuto (ovviamente con un diverso ID remoto). In tal caso, il messaggio ITN deve essere confermato, ma non deve comportare la cancellazione dello stato della transazione nel sistema del partner.

Gestione degli stati delle transazioni da ITN - Modello semplificato

In un modello in cui non è necessario notificare al Cliente via email/sms gli stati di non successo, la quantità di informazioni
memorizzati nel database del servizio e il monitoraggio delle modifiche del RemoteID può essere ridotto.

Tutto ciò che serve è:

• per gli stati diversi da SUCCESSO, ogni volta confermate l'ITN con la struttura di risposta corretta, CONFERMATO e il corretto conteggio del valore del campo Hash,

• in caso di ricezione di Primo stato SUCCESSO, aggiungono anche l'aggiornamento dello stato, della sua ora e del RemoteID nel database del Servizio e l'esecuzione dei processi aziendali (notifiche al Cliente di cambiamenti di stato, esecuzione di servizi a pagamento/spedizione di prodotti, ecc,)

• nel caso di una successiva SUCCESSO stato, confermando ogni volta l'ITN con una struttura di risposta corretta, CONFERMATO stato e conteggiato correttamente il valore del campo Hash, senza aggiornare il database del Servizio e senza processi aziendali.

Gestione degli stati delle transazioni da ITN - modello completo

In un modello in cui l'intera storia dei cambiamenti di stato delle transazioni e/o la notifica al cliente di importanti cambiamenti di stato
di transazioni, si dovrebbe utilizzare una logica che si avvicina alla descrizione seguente.

Sicurezza delle transazioni

Descrizione della sicurezza della transazione

Il sistema di pagamento online utilizza diversi meccanismi per aumentare
la sicurezza delle transazioni effettuate con esso. La trasmissione tra tutte le parti coinvolte in una transazione avviene tramite una
connessione sicura basata sul protocollo TLS con una chiave a 2048 bit.

Inoltre, la comunicazione è protetta da una funzione di hash calcolata a partire dai valori dei campi del messaggio e dalla chiave condivisa (la chiave condivisa stessa è memorizzata nel sistema in forma criptata con l'algoritmo AES-ECB).

Come funzione di hash viene utilizzato l'algoritmo SHA256 o SHA512 (metodo determinato in fase di configurazione del rispettivo Servizio partner nel sistema di pagamento online). La funzione predefinita è SHA256.

Calcolo del valore di una funzione hash

Descrizione di come calcolare il valore della funzione hash ed esempi di calcolo per messaggi di base.

NOTA: Gli esempi non tengono conto di tutti i possibili campi opzionali; pertanto, se tali campi sono presenti in un determinato messaggio, devono essere inclusi nella funzione abbreviata in un ordine coerente con il numero accanto al campo.

Calcolo del valore della funzione hash - Campo hash

Il valore della funzione hash, utilizzato per autenticare il messaggio, è calcolato da una stringa contenente i campi concatenati del messaggio (concatenazione di campi). I valori dei campi sono concatenati, senza i nomi dei parametri, e un separatore (nella forma del carattere |) viene inserito tra
valori consecutivi (non vuoti). L'ordine in cui i campi sono incollati segue l'ordine in cui sono presenti nell'elenco dei parametri nella documentazione.

IMPORTANTE! Se non c'è alcun parametro opzionale nel messaggio o in caso di un valore di parametro vuoto, non utilizzare il separatore!

Alla stringa così creata viene aggiunta alla fine una chiave, condivisa tra il Servizio partner e il sistema di pagamento online. Dalla stringa così creata, si calcola il valore della funzione di hash che costituisce
il valore del campo Hash del messaggio.

Hash = function(field_value_1_message + "|" + field_value_2_message + "|" + ... + "|" + field_value_n_message + "|" + shared_key);

Esempio di calcolo del valore della funzione hash all'inizio di una transazione

Dati di servizio dei partner:
ServiceID = 2

chiave condivisa = 2test2

Indirizzo del gateway https://{gate_host}/pathway

a. Inizio della transazione

Chiamata POST senza cestino, con parametri:

ServiceID=2
OrderID=100
Importo=1,50

Hash=2ab52e6918c6ad3b69a8228a2ab815f11ad58533eeed963dd990df8d8c3709d1

dove

Hash=SHA256(“2|100|1.50|2test2”)

b. Inizio della transazione. Chiamata POST con il carrello.

CONSIGLIO: Opzione discussa in dettaglio nella sezione Cestino prodotti.

ServiceID = 2

OrderID = 100

Importo = 1,50

Prodotto (descritto di seguito)

chiave condivisa = 2test2

Carrello prodotti (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<productList>
	   <product>
		  <subAmount>1.00</subAmount>
		  <params>
			 <param name="productName" value="Nazwa produktu 1" />
		  </params>
	   </product>
	   <product>
		  <subAmount>0.50</subAmount>
		  <params>
			 <param name="productType" value="ABCD" />
			 <param name="ID" value="EFGH" />
		  </params>
	   </product>
	</productList>

Dopo la codifica con la funzione base64, otteniamo il valore del parametro Prodotto:

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cHJvZHVjdExpc3Q+PHByb2R1Y3Q+PHN1YkFtb3VudD4xLjAwPC9zdWJBbW91bnQ+PHBhcmFtcz48cGFyYW0gbmFtZT0icHJvZHVjdE5hbWUiIHZhbHVlPSJOYXp3YSBwcm9kdWt0dSAxIiAvPjwvcGFyYW1zPjwvcHJvZHVjdD48cHJvZHVjdD48c3ViQW1vdW50PjAuNTA8L3N1YkFtb3VudD48cGFyYW1zPjxwYXJhbSBuYW1lPSJwcm9kdWN0VHlwZSIgdmFsdWU9IkFCQ0QiIC8+PHBhcmFtIG5hbWU9IklEIiB2YWx1ZT0iRUZHSCIgLz48L3BhcmFtcz48L3Byb2R1Y3Q+PC9wcm9kdWN0TGlzdD4=

Il valore Hash viene calcolato come segue:

Hash=SHA256(“2|100|1.50|PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cHJvZHVjdExpc3Q+PHByb2R1Y3Q+PHN1YkFtb3VudD4xLjAwPC9zdWJBbW91bnQ+PHBhcmFtcz48cGFyYW0gbmFtZT0icHJvZHVjdE5hbWUiIHZhbHVlPSJOYXp3YSBwcm9kdWt0dSAxIiAvPjwvcGFyYW1zPjwvcHJvZHVjdD48cHJvZHVjdD48c3ViQW1vdW50PjAuNTA8L3N1YkFtb3VudD48cGFyYW1zPjxwYXJhbSBuYW1lPSJwcm9kdWN0VHlwZSIgdmFsdWU9IkFCQ0QiIC8+PHBhcmFtIG5hbWU9IklEIiB2YWx1ZT0iRUZHSCIgLz48L3BhcmFtcz48L3Byb2R1Y3Q+PC9wcm9kdWN0TGlzdD4=|2test2”)

Esempio di calcolo del valore di una funzione hash quando si restituisce un cliente al sito del partner

Dati di servizio dei partner:

ServiceID = 2

chiave condivisa = 2test2

<https://shop_name/strona_powrotu?ServiceID=2>&OrderID=100&Hash=254eac9980db56f425acf8a9df715cbd6f56de3c410b05f05016630f7d30a4ed

dove

Hash=SHA256("2|100|2test2")

Esempio di calcolo del valore di una funzione hash in un messaggio ITN

Dati di servizio dei partner:

serviceID = 1

chiave condivisa = 1test1

ITN (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
	   <serviceID>1</serviceID>
	   <transactions>
		  <transaction>
			 <orderID>11</orderID>
			 <remoteID>91</remoteID>
			 <amount>11.11</amount>
			 <currency>PLN</currency>
			 <gatewayID>1</gatewayID>
			 <paymentDate>20010101111111</paymentDate>
			 <paymentStatus>SUCCESS</paymentStatus>
			 <paymentStatusDetails>AUTHORIZED</paymentStatusDetails>
		  </transaction>
	   </transactions>
	   <hash>a103bfe581a938e9ad78238cfc674ffafdd6ec70cb6825e7ed5c41787671efe4</hash>
	</transactionList>

dove

Hash=SHA256(“1|11|91|11.11|PLN|1|20010101111111|SUCCESS|AUTHORIZED|1test1”)

Esempio di risposta (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
	   <serviceID>1</serviceID>
	   <transactionsConfirmations>
		  <transactionConfirmed>
			 <orderID>11</orderID>
			 <confirmation>CONFIRMED</confirmation>
		  </transactionConfirmed>
	   </transactionsConfirmations>
	   <hash>c1e9888b7d9fb988a4aae0dfbff6d8092fc9581e22e02f335367dd01058f9618</hash>
	</confirmationList>

dove il valore

Hash=SHA256("1|11|CONFIRMED|1test1");

Esempio di calcolo del valore della funzione hash nell'interrogazione dell'elenco dei canali di pagamento

Dati di servizio dei partner:

ServiceID = 100

MessageID = 11111111111111111111111111111111

Valute = PLN,EUR

Lingua = IT

chiave condivisa = 1test1

dove il valore

Hash=SHA256('100|11111111111111111111111111111111|PLN,EUR|PL|1test1')

La risposta alla chiamata di cui sopra può essere la seguente (nota: nessun campo hash nella risposta):

{
    "result": "OK",
    "errorStatus": null,
    "description": null,
    "gatewayGroups": [
        {
            "type": "PBL",
            "title": "Przelew internetowy",
            "shortDescription": "Select the bank from which you want to order the payment",
            "description": null,
            "order": 1,
            "iconUrl": null
        },
        {
            "type": "BNPL",
            "title": "Buy now, pay later",
            "shortDescription": "Buy now, pay later",
            "description": null,
            "order": 2,
            "iconUrl": null
        }
    ],
    "serviceID": "10000",
    "messageID": "2ca19ceb5258ce0aa3bc815e80240000",
    "gatewayList": [
        {
            "gatewayID": 106,
            "name": "PBL test payment",
            "groupType": "PBL",
            "bankName": "NONE",
            "iconURL": "https://testimages.autopay.eu/pomoc/grafika/106.gif",
            "state": "OK",
            "stateDate": "2023-10-03 14:35:01",
            "description": "Test payment",
            "shortDescription": null,
            "descriptionUrl": null,
            "availableFor": "BOTH",
            "requiredParams": ["Nip"],
            "mcc": {
                "allowed": [1234, 9876],
                "disallowed": [1111]
            },
            "inBalanceAllowed": true,
            "minValidityTime": null,
            "order": 1,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 0.01,
                    "maxAmount": 5000.00
                }
            ],
            "buttonTitle": "Pay"
        },
		{
            "gatewayID": 701,
            "name": "Pay later with Payka",
            "groupType": "BNPL",
            "bankName": "NONE",
            "iconUrl": "https://testimages.autopay.eu/pomoc/grafika/701.png",
            "state": "OK",
            "stateDate": "2023-10-03 14:37:10",
            "description": "<div class=\"payway_desc\"><h1>Cost details</h1><p>Pay later - one-off up to 45 days (...). Offer details at: <a href="?r="https://payka.pl\" target=\"_blank\">Payka.pl</a></p></div>",
            "shortDescription": "Pay later - in one go up to 45 days or in several equal instalments",
            "descriptionUrl": null,
            "availableFor": "B2C",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": false,
            "minValidityTime": 60,
            "order": 2,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 49.99,
                    "maxAmount": 7000.00
                }
            ],
            "buttonTitle": "Pay"
        }
    ]
}

Estensioni aggiuntive

Modelli alternativi di avvio delle transazioni

Preautorizzazione della carta

Descrizione generale del funzionamento del servizio di preautorizzazione delle carte di credito

Il supporto per la preautorizzazione della carta fornisce la funzionalità di bloccare i fondi sulla carta del cliente per un certo periodo di tempo (ad esempio, predeterminato durante la creazione del blocco) e poi effettuare un addebito. Un caso particolare è quello in cui il blocco viene rimosso senza che venga detratto alcun importo (ad esempio, il servizio al cliente non è stato eseguito).

Tutte queste operazioni (blocco dei fondi, addebito, ritiro del blocco) devono essere ordinate tramite l'API del Sistema di pagamento Autopay. Se non c'è un ordine di addebito sulla carta durante il periodo di validità della transazione che ha creato il blocco, il sistema rilascerà i fondi, notificandovi con un messaggio standard di Transaction Status Change (ITN).

Anche altre operazioni (addebito riuscito, blocco della carta e successivo addebito) comportano l'invio di un messaggio ITN. Questo messaggio è l'unica informazione vincolante sulla modifica dello stato di una transazione e (utilizzato insieme al servizio Stato della transazione; si veda la sezione Richiesta di informazioni sullo stato di una transazione), aiuta a gestire la transazione senza interrompere la sessione con l'utente (anche in caso di vari problemi di rete). Riconoscimento delle operazioni sincrone (nodo confermaservono solo a presentare informazioni preliminari sull'ordine).

Fasi di una transazione di pre-autorizzazione della carta

Blocco su richiesta del Partner

È possibile distinguere tra 3 modi fondamentali di posizionare un lucchetto su una carta:

a) Stabilire un blocco durante l'autorizzazione di un pagamento una tantum (cfr. Schema A per la preautorizzazione). Il cliente compila il formato della carta, dopo l'avvio della transazione, che il Partner indica nei parametri di avvio:

- canale di pagamento con carta (GatewayID=1500) e

- il desiderio di assicurarsi i fondi piuttosto che di impegnarli (Mantenere=vero)

b) Assunzione di un blocco al momento dell'avvio di un pagamento automatico (registrazione della carta nel Servizio o nell'Applicazione mobile) (cfr. Schema B per la preautorizzazione)).

CONSIGLIO: l'intero ciclo e tutti gli eventi di pagamento automatico secondo la documentazione, modificati dal momento in cui la carta viene effettivamente addebitata e il pagamento automatico viene impostato - nel modello di pre-autorizzazione, è il transazioneCancellare che provoca questi eventi.

Il cliente compila il formato della carta, una volta avviata la transazione, che il Partner indica nei parametri di avvio:

- canale di pagamento con carta (GatewayID=1503),

- il fatto di accettare le regole del servizio di pagamento automatico
fornito da AP (RecurringAcceptanceState=ACCEPTEDo dopo il o dopo gli accordi commerciali PROMEMORIA/FORZA)

- la scelta di inizializzare un pagamento automatico con un potenziale addebito sulla carta (RecurringAction=INIT_WITH_PAYMENT)

- il desiderio di assicurarsi i fondi piuttosto che di impegnarli (Mantenere=vero)

c) Stabilire un blocco utilizzando una scheda salvata in precedenza (cfr. Schema C per la preautorizzazione).

CONSIGLIO: L'intero ciclo e tutti gli eventi di pagamento automatico secondo la documentazione, modificati dal momento in cui la carta viene effettivamente addebitata e il pagamento automatico viene impostato - nel modello di pre-autorizzazione, è il momento in cui la carta viene addebitata e il pagamento automatico viene impostato. transazioneCancellare che provoca questi eventi.

Il cliente non compila il modulo della carta, ma ha luogo una pre-transazione backend (senza reindirizzamento) in cui il partner indica i parametri di partenza:

- canale di pagamento con carta (GatewayID=1503)

- indicazione di una scheda precedentemente aggiunta (ClientHash da RPAN)

- scelta del metodo di pagamento automatico (RecurringAction=MANUAL)

- il desiderio di assicurarsi i fondi piuttosto che di impegnarli (Mantenere=vero)

Ognuno di questi metodi per stabilire un blocco dà luogo a un messaggio ITN, il cui stato indica il risultato dell'autorizzazione della transazione. Oltre al messaggio standard
in caso di blocco dei fondi, il Sistema può fornire nello stato dell'ITN paymentStatus=ON_HOLDche conferma la creazione di un blocco di fondi sulla carta del cliente. Inoltre, l'ITN, come standard,
contengono un identificatore di transazione globale (ID remoto), che sarà necessario per il successivo caricamento del blocco stabilito.

Addebito su carta su richiesta del Partner

Descrizione dell'addebito della carta su richiesta del partner

Una volta effettuato il blocco, il Partner può effettuare un ordine di addebito.
su una carta autorizzata in precedenza (vedere Schema D per la preautorizzazione).Per
a questo scopo, è necessario richiamare il servizio dedicato: transazioneCancellare (https://{gate_host}/webapi/transactionClear) con i parametri corrispondenti. Tutti i parametri vengono passati tramite il metodo POST (Tipo di contenuto: application/x-www-form-urlencoded). Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi dei parametri che nei valori. Il
i valori dei parametri passati devono essere codificati in UTF-8.

Descrizione dei parametri disponibili per l'addebito su carta su richiesta del Partner

Conferma della transazione per l'addebito su carta su richiesta del Partner

Per una corretta interrogazione, deve essere definita un'intestazione HTTP con un contenuto appropriato.
inviato insieme ai parametri passati. L'allegato
L'intestazione deve essere denominata "BmHeader" e avere le seguenti caratteristiche
valore "pay-bm", nella sua interezza dovrebbe avere il seguente aspetto "BmHeader: pay-bm". In caso di messaggio valido, viene restituito un testo in formato XML (nella stessa sessione HTTP), contenente la conferma dell'operazione o una descrizione dell'errore.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
	<serviceID>ServiceID</serviceID>
	<messageID>MessageID</messageID>
	<remoteOutID>RemoteOutID</remoteOutID>
	<hash>Hash</hash>
	</balancePayoff>

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
	<balancePointID>BalancePointID</balancePointID>
	<messageID>MessageID</messageID>
	<remoteOutID>RemoteOutID</remoteOutID>
	<hash>Hash</hash>
	</balancePayoff>

Descrizione dei parametri da restituire per l'addebito della carta su richiesta del partner

Rilascio del blocco su richiesta del Partner

Una volta stabilito il blocco, il Partner può ordinare di rilasciarlo senza alcuna detrazione di fondi (cfr. Schema E per la preautorizzazione)). Per questa operazione, utilizzare il servizio releaseHold (Vedi Annullamento di una transazione non pagata). Quando viene avviata con successo l'apertura di un blocco (risposta corretta a un annullamento
), il sistema fornirà in modo asincrono un ITN con la transazione paymentStatus=FAILURE e paymentStatusDetails=CANCELLATO.

Sblocco del blocco dopo le transazioni in ritardo

In caso di inattività del Partner (dopo l'impostazione del blocco) per un periodo di tempo predeterminato
periodo di validità, la transazione viene rilasciata dal Sistema (senza
dedurre eventuali fondi) (Cfr. Schema F per la preautorizzazione). Il sistema annullerà la transazione, rimuoverà il blocco e fornirà all'ITN l'informazione paymentStatus=FAILURE e paymentStatusDetails=CANCELLATO.

Schemi di preautorizzazione

Schema A per la preautorizzazione: creazione di un blocco durante l'autorizzazione di un pagamento unico

Schema B per la preautorizzazione: assunzione di un blocco durante l'avvio di un pagamento automatico (iscrizione della carta)README.md

Schema C per la preautorizzazione: impostazione di un blocco utilizzando una carta precedentemente memorizzata

Schema D per la preautorizzazione: ordine del partner di addebitare una carta precedentemente autorizzata

Schema E per la preautorizzazione: ordine del socio di sbloccare la serratura (senza detrazione di fondi)

Schema F per la preautorizzazione: rilascio del blocco da parte dello Schema (senza detrazione di fondi)

Pre-transazione

Descrizione pre-transazione

La pre-transazione estende il modello standard di avvio della transazione gestendo esigenze specifiche:

• ordinare un link di pagamento sulla base dei parametri presentati

• addebito da parte del cliente (se non è necessaria un'ulteriore autorizzazione da parte del cliente)

• verificare la correttezza del link di pagamento prima che il Cliente venga reindirizzato al Sistema - la chiamata comporta la convalida dei parametri e della configurazione del Sistema

• accorciare il link per il pagamento - invece di diversi parametri, il link è ridotto a due identificatori

• nascondere i dati dei parametri sensibili del link alla transazione - la pre-transazione avviene nel backend e il link per continuare la transazione non contiene dati sensibili, ma solo gli identificatori della continuazione della transazione.

• utilizzo dell'SDK mobile in una variante mista - l'avvio della transazione viene eseguito dal backend dell'applicazione mobile, piuttosto che dall'SDK stesso che utilizza il token della transazione

I casi d'uso specifici della pre-transazione sono i carichi:

• BLIK 0Per utilizzare questo servizio, è necessario fornire GatewayID=509 e passare il codice di autorizzazione della transazione nel parametro Codice di autorizzazione.

• BLIK 0 Un clic

• Spese per "Pagamento automatico
  Per utilizzare questo servizio, è necessario fornire una delle seguenti informazioni GatewayID=509 i gatewayType="Pagamento automatico". e i parametri necessari.

• Autorizzazioni tramite portafoglio Visa
  Per poter usufruire di questo servizio, è necessario fornire GatewayID=1511 e passare il token codificato nel parametro Token di pagamento. In assenza di un token, l'autorizzazione avverrà sul sito web del sistema.

• Autorizzazioni attraverso i portafogli Google Pay

NOTA: Il servizio consente di addebitare la carta memorizzata nel portafoglio del cliente senza reindirizzarla al sistema. Spesso viene applicata un'autorizzazione aggiuntiva sotto forma di 3DS (comportamento predefinito dell'ambiente di prova, che può essere riconfigurato).

Nel Etichetta bianca modello, integrarlo come descritto e quindi fornire GatewayID=1512 e il token codificato nel campo Token di pagamento parametro. Se non c'è un token (o un modello diverso da Etichetta bianca), è sufficiente inserire GatewayID=1512 - l'autorizzazione avverrà sul sito web del sistema.

• Autorizzazioni attraverso i portafogli Apple Pay
  Per utilizzare questo servizio, è necessario inserire GatewayID=1513. L'autorizzazione avverrà sul sito web del sistema.

• Autorizzazione attraverso il formato nativo dell'SDK mobile

NOTA: Il servizio consente l'addebito della carta, i cui dettagli sono forniti nel formato della carta sicura dell'SDK, e l'avvio della transazione stessa è eseguito dal backend dell'applicazione mobile.

Oltre al GatewayID pertinente - 1500 per un pagamento unico o 1503 per l'attivazione di un pagamento automatico (e altri parametri) - il PaymentToken ottenuto dall'SDK e il parametro WalletType=SDK_NATIVE (descrizione nella sezione Avvio di una transazione con parametri aggiuntivi)

Chiamare una pre-transazione

Un elemento richiesto nel caso di una pre-transazione è l'invio al backend (utilizzando, ad esempio, cURL) del messaggio standard di avvio della transazione (vedere Inizio della transazione), con un "BmHeader" di valore: "pay-bm-continue-transaction-url":

Esempio di intestazione

BmHeader: pay-bm-continue-transaction-url'.)

Inoltre, si raccomanda che il parametro ClienteIP (a scopo di reclamo e di rendicontazione).

Esempio di avvio della pre-transazione (PHP)

	$data = array(
	 'ServiceID' => '100047',
	 'OrderID' => ‘20161017143213’,
	 'Amount' => '1.00',
	 'Description' => 'test bramki',
	 'GatewayID' => '0',
	 'Currency' => 'PLN',
	 'CustomerEmail' => 'test@bramka.pl',
	 'CustomerIP' => '127.0.0.0',
	 'Title' => 'Test title',
	'Hash' => 0c5ca136e8833e40efbf42a4da7c148c50bf99f8af26f5c9400681702bd72056
	);

	$fields = (is_array($data)) ? http_build_query($data) : $data;

	$curl = curl_init('https://{gate_host}/test_ecommerce');
	curl_setopt($curl, CURLOPT_HTTPHEADER, array('BmHeader: pay-bm-continue-transaction-url'));
	curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);
	curl_setopt($curl, CURLOPT_POST, 1);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
	$curlResponse = curl_exec($curl);
	$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
	$response = curl_getinfo($curl);
	curl_close($curl);

	echo htmlspecialchars_decode($curlResponse);

Risposta alla pre-transazione - link per il follow-up della transazione

In caso di convalida corretta dei parametri (e della configurazione) e di
la necessità per il cliente di eseguire un'azione aggiuntiva (selezione di una
canale di pagamento - se specificato GatewayID=0, esecuzione/trasferimento di conferma, inserimento del codice CVC/CVV, esecuzione del 3DS) - verrà restituito un XML con un link per continuare la transazione.

Esempio di file di collegamento di continuazione della transazione (XML)

	<?xml version="1.0" encoding="UTF-8"?>
		<transaction>
		<status>PENDING</status>
		<redirecturl>
		https://{gate_host}/payment/continue/96VSD39Z6E/L6CGP5BH
		</redirecturl>
		<orderID>20180824105435</orderID>
		<remoteID>96VSD39Z6E</remoteID>
		<hash>
		1c6eae2127f0c3f81fbed3b6372f128040729a4d4e562fb696c22e0db68dbbe1
		</hash>
	</transaction>

Oggetto pre-transazione

Il transazione rappresenta la ricezione o il prelievo di fondi da un AP, come un acquisto o un rimborso completato.

Attributi dell'oggetto transazione per la pre-transazione

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Risposta a Pre-transazione - nessuna continuazione della transazione

In caso di convalida non valida o di caricamento non riuscito, non viene generato alcun link di continuazione. Viene restituito un testo in formato XML (nella stessa sessione HTTP) che indica lo stato di elaborazione della richiesta.

Esempio di stato di elaborazione della richiesta (XML)

<?xml version="1.0" encoding="UTF-8"?>
<transaction>
	<orderID>OrderID</orderID>
	<remoteID>RemoteID</remoteID>
	<confirmation>ConfStatus</confirmation>
	<reason>Reason</reason>
	<blikAMList>
		<blikAM>
			<blikAMKey>Klucz1</blikAMKey>
			<blikAMLabel>Etykieta1</blikAMLabel>
		</blikAM>
		<blikAM>
			<blikAMKey>Klucz2</blikAMKey>
			<blikAMLabel>Etykieta2</blikAMLabel>
		</blikAM>
	</blikAMList>
	<paymentStatus>PaymentStatus</paymentStatus>
	<hash>Hash</hash>
</transaction>

Risultato pre-transazione

Parametri restituiti per il risultato della pre-transazione.

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

	<blikAM>
	<blikAMKey>Key1</blikAMKey>
	<blikAMLabel>Label1</blikAMLabel>
	</blikAM>
	…
	<blikAM>
	<blikAMKey>KeyN</blikAMKey>
	<blikAMLabel>LabelN</blikAMLabel>
	</blikAM>

Validazione corretta dei parametri

Se i parametri (e la configurazione) sono stati convalidati correttamente e non è necessario che il cliente esegua un'ulteriore azione, viene restituita una conferma dell'ordine di carico.

Questo è il caso in cui i dati sono sufficienti per effettuare un addebito per il canale di pagamento in questione, ad esempio: BLIK 0 senza
il codice BLIK richiesto (né l'indicazione dell'alias dell'app mobile della banca), pagamento ricorrente, pagamento con carta OneClick senza il CVC/CVV/3DS richiesto.

Risultato

conferma=CONFIRMED

Convalida dei parametri non corretta

In caso di convalida errata dei parametri (e della configurazione), viene restituito un errore.

Risultato

conferma=NOTCONFIRMED

Un errore può essere restituito anche in caso di risposta sincrona da parte del Canale di pagamento (ad esempio un errore specifico per il tentativo di inizializzare un pagamento automatico BLIK, ovvero reason= RECURRENCY_NOT_SUPPORTED).

NOTA: Un errore può essere restituito anche in caso di risposta sincrona da parte di un Canale di pagamento (ad esempio, un errore specifico per un tentativo di inizializzazione di un pagamento automatico BLIK, ovvero reason=RECURENCY_NOT_SUPPORTED). Un altro caso noto è l'errore di convalida dell'indirizzo fornito nel parametro iniziale CustomerEmail (INVALID_EMAIL).

Gestione delle risposte per le transazioni

Richiesta dei dettagli del trasferimento per una transazione Fast Transfer

Descrizione dell'ordine dei dati di trasferimento in una transazione di trasferimento veloce

Il Bonifico veloce è una forma di pagamento che richiede al Cliente di riscrivere autonomamente i dati di bonifico forniti dal Sistema. Il tipo di canale di pagamento viene indicato dal parametro GatewayType in risposta alla chiamata al servizio "Interrogazione dell'elenco dei canali di pagamento attualmente disponibili".
Canali di pagamento". I dati del trasferimento possono essere visualizzati dal cliente:

• sul sito web dell'AP (esecuzione della transazione in base al modello standard di avvio della transazione descritto nella parte Inizio della transazione)

• sul sito del Partner (l'elaborazione della transazione senza reindirizzare il cliente al sito dell'AP è descritta di seguito)

Chiamata

Per la corretta trasmissione del messaggio, è necessario inviare al backend un messaggio standard di avvio della transazione (ad es.
cURL), con un'intestazione 'BmHeader' di valore: 'pay-bm' (Nella sua interezza, l'intestazione dovrebbe apparire come segue BmHeader: pay-bm'.). Se l'intestazione è definita in modo errato o manca, il messaggio verrà letto male. Inoltre, si consiglia di passare il parametro CustomerIP come descritto in User IP (necessario per i processi di reclamo e segnalazione) e richiesto per passare un valore non nullo GatewayID (con gatewayType "Trasferimento veloce"`").

Implementazione dell'avvio delle transazioni in background (PHP)

	$data = array(
	 'ServiceID' => '100047',
	 'OrderID' => '20150723144517',
	 'Amount' => '1.00',
	 'Description' => 'test bramki',
	 'GatewayID' => '71',
	 'Currency' => 'PLN',
	 'CustomerEmail' => 'test@bramka.pl',
	 'CustomerIP' => '127.0.0.0',
	 'Title' => 'Test title',
	 'ValidityTime' => '2016-12-19 09:40:32',
	 'LinkValidityTime' => '2016-07-20 10:43:50',
	 'Hash' => 'e627d0b17a14d2faee669cad64e3ef11a6da77332cb022bb4b8e4a376076daaa'
	);

	$fields = (is_array($data)) ? http_build_query($data) : $data;

	$curl = curl_init('https://{gate_host}/test_ecommerce');
	curl_setopt($curl, CURLOPT_HTTPHEADER, array('BmHeader: pay-bm'));
	curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);
	curl_setopt($curl, CURLOPT_POST, 1);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
	$curlResponse = curl_exec($curl);
	$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
	$response = curl_getinfo($curl);
	curl_close($curl);

	echo htmlspecialchars_decode($curlResponse);

Risposta - Dettagli del trasferimento

Nel caso di pagamenti di questo tipo, il Sistema genera un insieme di dati
necessari per effettuare un trasferimento intra-bancario (e quindi veloce) al conto bancario dell'AP. Questi dati vengono inseriti nella risposta all'inizio della transazione, in un documento xml.

Risposta del sistema di pagamento all'avvio della transazione (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transaction>
		<receiverNRB>47 1050 1764 1000 0023 2741 0516</receiverNRB>
		<receiverName>Autopay</receiverName>
		<receiverAddress>81-718 Sopot, ul. Powstancow Warszawy 6</receiverAddress>
		<orderID>9IMYEH2AV3</orderID>
		<amount>1.00</amount>
		<currency>PLN</currency>
		<title>9IMYEH2AV3  - weryfikacja rachunku</title>
		<remoteID>9IMYEH2AV3</remoteID>
		<bankHref>https://ssl.bsk.com.pl/bskonl/login.html</bankHref>
		<hash> fe685d5e1ce904d059eb9b7532f9e06a64c34c1ea9fcf29b62afefdb7aad7b75 </hash>
	</transaction>

Elenco dei parametri restituiti per la risposta

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione
.

NOTA: Le informazioni di cui sopra devono essere utilizzate per visualizzare i dati di trasferimento e reindirizzare l'utente alla pagina di login della banca.

BLIK 0 Pagamento con un solo clic

Descrizione di BLIK 0 Pagamenti in un clic

Si tratta di una soluzione dedicata ai pagamenti BLIK, che consente di pagare senza inserire il codice BLIK (e senza dover lasciare il sito web). Il suo avvio con successo nel Sistema provoca l'attivazione/risveglio automatico dell'applicazione mobile della banca e la presentazione della transazione all'Utente per la conferma.

Potenziali benefici:

• rendere disponibile il primo metodo di pagamento comodo e sicuro nel mCommerce che non richiede un numero di carta apre questo segmento a nuovi clienti,

• una migliore esperienza d'acquisto per i clienti, che pagano più velocemente e più comodamente,

• frequenza di acquisto e valore del cliente nel tempo - i clienti sono più disposti a
  acquistare più spesso da quei negozi in cui il processo di acquisto è
  più conveniente,

• tasso di conversione - il servizio ha un maggiore controllo sul processo di acquisto e pagamento (il cliente non lo abbandona), il rischio di perdita del carrello,

• decisione rapida sulla transazione - in breve tempo la transazione è soggetta ad autorizzazione, rifiuto o annullamento,

• Il servizio ha la possibilità di analizzare la fase stessa del pagamento
  .

La condizione affinché il BLIK 0 OneClick sia reso disponibile al Cliente è di essere stato autorizzato sul Servizio (avere un account e avervi precedentemente effettuato l'accesso). Se, durante un pagamento BLIK precedentemente eseguito, insieme ad altre informazioni di pagamento, il Servizio ha inviato un UID Alias dedicato (descrizione dei parametri Chiave BlikUID e Etichetta BlikUID in un'altra parte del documento
), e il Cliente, mentre confermava il pagamento nell'applicazione mobile ha indicato che desiderava ricordare il negozio, ciò ha comportato un'associazione permanente (in genere per un periodo di 2 anni) del Cliente del servizio con la sua applicazione, ossia la registrazione Alias UID. Il suo successivo utilizzo comporterà l' autorizzazione della transazione senza l'inserimento del codice.

Chiamare i pagamenti BLIK 0 OneClick

Quando si seleziona un canale di pagamento BLIK, si consiglia di non forzare l'utente a inserire un codice BLIK. Si consiglia invece di visualizzare il collegamento ipertestuale "Voglio inserire il mio codice BLIK" sotto il pulsante "Acquista e paga" per consentire l'inserimento del codice al primo tentativo (nel caso in cui il Cliente desideri effettuare un pagamento BLIK da un'applicazione mobile diversa da quella in cui ha precedentemente salvato un determinato Servizio).

Il Servizio deve eseguire la Pre-Transazione, prestando particolare attenzione ai seguenti elementi:

• specificando il parametro GatewayID = 509 - che indica il canale di pagamento BLIK,

• fornendo Chiave BlikUID e Etichetta BlikUID parametri - che indicano BLIK 0 OneClick Alias UID (ID utente) richiesto da BLIK 0 OneClick. utente)

• fornire il Codice di autorizzazione parametro - se il cliente ha fornito il codice BLIK,

• fornendo BlikAMKey parametro - se il Cliente ha specificato un'etichetta del dell'applicazione mobile della banca dall'elenco presentato sul Sito web,

• gestione delle possibili risposte alla pre-transazione, compresa la gestione di 'Response - no continuation' ed errori specifici di BLIK 0 OneClick:

a) errore di molte applicazioni mobili della banca (conferma=NOTCONFIRMED e motivo=ALIAS_NONUNIQUE) - visualizzando l'elenco delle etichette restituite nell'elenco degli alias pre-transazione (coppie chiave + etichetta contenute nel file Elenco BlikAML per recuperare la chiave selezionata e fornirla nella struttura BlikAMKey del prossimo tentativo di pre-transazione

(b) errori di autorizzazione (conferma=NOTCONFIRMED e motivo con uno dei valori: ALIAS_DECLINATO, ALIAS_NON_TROVATO, BIGLIETTO_ERRATO, BIGLIETTO_SCADUTO, BIGLIETTO_USATO) - visualizzare il campo Blik Code, per poterlo recuperare e fornire nel campo Codice di autorizzazione del prossimo tentativo di pre-transazione

Google Pay

Descrizione

Google Pay è un sistema di pagamento istantaneo e intuitivo di Google.

Google Pay è un prodotto che permette di ottenere i dati criptati della carta di pagamento del cliente, consentendone l'addebito.

Per pagare tramite Google Pay, è necessario salvare la carta di pagamento sul proprio account Google, utilizzando una qualsiasi piattaforma di Google (ad esempio, l'acquisto di app su Google Play) o direttamente sul sito web di Google. Google Pay.

NOTA: Il servizio richiede la preventiva sottoscrizione di un contratto con l'operatore della carta. Per maggiori informazioni, contattare il reparto commerciale Autopay.

Schema di comunicazione

Dopo aver fatto clic su "Paga con Google Pay", sulla pagina del negozio appare un modulo Google Pay. In esso il cliente conferma il suo account Google e la carta con cui intende pagare (in questa fase può anche passare a un'altra carta o aggiungerne una nuova). Lo script trasmette in background i dati codificati della carta tramite il servizio messaggio poi il negozio deve accettarlo e codificarlo tramite la funzione base64 e infine inviarlo nel file Token di pagamento insieme agli altri parametri (dati della transazione).

Sul proprio sito web, il negozio deve richiamare lo script fornito da Google con i dati del processore di pagamento modificati.

CONSIGLIO: Dettagli in Documentazione per sviluppatori di Google.

Schema dettagliato di comunicazione e scambio di dati

Registrazione della transazione Google Pay

1. Il negozio sul proprio sito web deve inviare una richiesta al sistema di pagamento online AP per recuperare i dati necessari all'elaborazione di Google Pay (paybmApiResponse).

CONSIGLIO: Un esempio di come inviare una richiesta è disponibile all'indirizzo GitHub Autopay.

2. Il negozio deve quindi chiamare lo script fornito nel file parti dell'esercitazione della documentazione per sviluppatori di Google, contenente:

(a) I dati del processore di pagamento sono stati alterati:

const tokenizationSpecification = {
	type: 'PAYMENT_GATEWAY',
	parameters: {
		'gateway': 'bluemedia',
		'gatewayMerchantId': paybmApiResponse.acceptorId
	}
};

b) I dati restituiti dal sistema di pagamento online AP trasferiti nell'oggetto PaymentDataRequest.merchantInfo:

PaymentDataRequest.merchantInfo = {
	merchantId: paybmApiResponse.merchantId,
	merchantOrigin: paybmApiResponse.merchantOrigin,
	merchantName: paybmApiResponse.merchantName,
	authJwt: paybmApiResponse.authJwt,
};

3. Dopo aver fatto clic su "Paga con Google Pay" nella pagina del negozio, appare un modulo Google Pay sulla pagina del negozio. In esso il cliente conferma il proprio account Google e la carta con cui intende pagare (in questa fase può anche passare a un'altra carta o aggiungerne una nuova). Uno script in background trasmette i dati codificati della carta, che il negozio deve accettare e quindi codificare con la funzione Base64 e inviare nel file Token di pagamento insieme al resto dei parametri di avvio della transazione (cioè i dati della transazione del sistema di pagamento online AP - i dettagli sono descritti nella sezione Avvio di una transazione con parametri aggiuntivi).

CONSIGLIO: Un esempio completo di integrazione con Google Pay è disponibile su GitHub Autopay.

Informazioni aggiuntive

Per mantenere l'integrità estetica del design utilizzato sul sito web e sull'applicazione mobile, si prega di utilizzare le indicazioni fornite nel documento parti delle linee guida del marchio della documentazione di sviluppo Google per descrizioni di stile e pulsanti per le pagine web e per Parti Documentazione per sviluppatori tutorial Google, dove troverete le informazioni necessarie per lo sviluppo dell'applicazione mobile.

Apple Pay

Implementazione di Apple Pay sul sito web del negozio.

Richiesta di contatto con il prodotto dell'infrastruttura di pagamento - necessità di supporto informatico.

1. Creazione di un conto da parte del Partner e ottenimento di un certificato per l'elaborazione dei pagamenti in conformità con la normativa vigente. documento Configurare Apple Pay (iOS, watchOS)

- certificato di comunicazione - per la cosiddetta presentazione - identificativo del commerciante

- certificato di addebito - certificato di elaborazione dei pagamenti

2. Implementazione web in conformità con documento Apple Pay sul web

3. Preparazione di 2 endpoint sul lato del partner, su un dominio registrato presso Apple (utilizzando 2 certificati di Apple):

- per l'avvio della sessione

- per addebitare al cliente il costo del token di Apple.

SUGGERIMENTO: Safari (il browser del cliente) richiede la sessione all'endpoint (menzionato sopra) e poi va da noi - noi restituiamo la sessione.

4. Elaborazione di Apple Pay

• Come parte della registrazione del servizio con Apple, generare il proprio certificato identità del commerciante.
• Generare un elaborazione dei pagamenti basato sul certificato fornito dal CSR dell'AP.

NOTA: I certificati AP CSR per l'accettazione e per la produzione sono diversi).

• Dopo averlo utilizzato nel processo di registrazione Apple, fornire all'AP un certificato firmato da Apple e inviarlo via Modulo di pagamento automatico

  SUGGERIMENTO: Il cliente deve fornire il paese, la città, il dominio del sito web e l'e-mail della persona di contatto.

• Nell'ambito dell'elaborazione dei pagamenti sul sito del partner, avviare una sessione API Apple.

• Quindi restituire il token Autopay nel parametro PaymentToken start.

NOTA: La decodifica del token è responsabilità dell'AP.

Formato del token di pagamento: una fetta di un oggetto in formato json che l'API ApplePay restituisce:

  EncryptedPaymentData {
	  String version;
	  String data;
	  String signature;
	  Header header;
  }
  Header {
	  String ephemeralPublicKey;
	  String publicKeyHash;
	  String transactionId;
	  String applicationData;
  }
  

NOTA: Quando si invia una richiesta di pagamento ApplePayPaymentRequest, è necessario riempire il campo applicationData con il valore Base64-encoded orderId, come descritto nel documento documento applicationData.

Widget Autopay (modello WhiteLabel)

I partner che desiderano incorporare una parte delle transazioni direttamente sul loro sito / nel loro carrello (nel cosiddetto modello WhiteLabel) possono farlo integrando il Widget Autopay. Attualmente, il Widget Autopay supporta la raccolta dei dati della carta (all'interno del PaywayId 1500/1503) o Visa Mobile inizia (PaywayId PaywayId 1523)

IMPORTANTE! Il Partner non è autorizzato a memorizzare i dati della Carta (in particolare il numero di carta, il codice di sicurezza CVC, il CVV2), ad eccezione dei parametri trasferiti durante l'elaborazione dei pagamenti automatici da parte dell'AP, come descritto in questa sezione.

IMPORTANTE! Il sito web del partner in cui viene utilizzata la funzionalità del widget Autopay deve essere criptato e l'IFRAME HTML con il widget deve essere incorporato in un indirizzo HTTPS con l'uso di TLS.

IMPORTANTE! Il partner si impegna a presentare all'AP, in forma elettronica,
i seguenti documenti:
a) una tantum (prima della conclusione del Contratto): un questionario SAQ-A PCI compilato (Sezione 2); il documento sarà fornito da AP o è disponibile per il download sul sito web: https://www.pcisecuritystandards.org
b) Su base trimestrale: il risultato dell'audit PCI ASV trimestrale che include una scansione di indirizzi/reti/domini IP esterni (pubblici) - IPv4 e/o IPv6. Tale audit deve essere condotto da uno degli appaltatori autorizzati elencati in: https://www.pcisecuritystandards.org/assessors_and_solutions/approved_scanning_vendors

WidgetJS SDK Autopay

È necessario utilizzare l'Autopay WidgetJS SDK per incorporare e comunicare con il widget Autopay. In breve, si tratta di incorporare l'IFRAME HTML con il widget e di configurare l'SDK JS per gestire i messaggi (eventi) prodotti quando il titolare della carta interagisce con il widget. Il messaggio finale è un evento con uno stato di MODULO_INTERROTTO incluso paymentToken necessari per l'avvio delle transazioni backend sull'API del sistema di pagamento online AP.

Incorporare l'SDK

Di seguito sono riportati alcuni esempi di come incorporare e diffondere facilmente un widget, utilizzando l'Autopay WidgetJS SDK, sia per la carta che per i canali VisaMobile.

L'SDK Autopay WidgetJS è disponibile all'indirizzo widget-nuovo/widget-comunicazione.min.js una volta che è stato inserito nel <head>

<script src="?r=quot;https://testcards.autopay.eu/widget-new/widget-communication.min.js"></script>

Si accede all'oggetto WidgetConnection

var widgetConfigObject = { ... };
var widget = new WidgetConnection(widgetConfigObject)

che, se integrato con una configurazione sotto forma di oggetto JSON, consentirà una comunicazione completa con l'API Autopay e, di conseguenza, garantirà la ricezione di un evento con uno stato pari a MODULO_INTERROTTO da paymentToken.

Esempi di configurazioni

Esempio di configurazione per i dati della carta

Configurazione:

{ language: 'pl', amount: 1.23, currency: 'PLN', serviceId: 123456 }

PaymentToken restituito:

{status: 'FORM_SUCCESS', message: 'ey...9', id: 'OGFlZTYyYTMtN2U2OS00MTU1LTgyNDctNmMwMGI2NjE5ZDQy'}

Esempio di configurazione per i dati VisaMobile

Configurazione:

{ language: 'pl', amount: 1.23, currency: 'PLN', serviceId: 123456, merchantName: 'ShopName' }

PaymentToken restituito:

{status: 'FORM_SUCCESS', message: 'ey...9', prefix: '48', phoneNumber: '666666666', id: 'OGFlZTYyYTMtN2U2OS00MTU1LTgyNDctNmMwMGI2NjE5ZDQy'}

Discussione dettagliata della configurazione dell'oggetto WidgetConnection

Lingua

Determina la versione linguistica del widget in cui sarà presentato.

Nome del campo: lingua Formato stringa Valori: predefinito itAttualmente sono supportate le seguenti lingue: cs, de, el, it, es, fr, hr, hu, esso, it, ro, se, sk, sl, uk

Importo della transazione

Importo della transazione

Nome del campo: importo Formato galleggiante Valori: un importo scritto in formato float, ad es: "1,23 PLN" dovrebbe essere 1.23

importo: 1,23, valuta: 'PLN', serviceId: 123456, merchantName: 'ShopName'.

Valuta della transazione

Valuta della transazione

Nome del campo: valuta Formato stringa Valori: predefinito PLN, altre valute in un formato compatibile con la configurazione attuale del servizio

Numero di servizio

Numero di servizio ricevuto da Autopay (dipende dall'ambiente di sviluppo)

Nome del campo: serviceId Formato intero Valori: di solito sei cifre

Tipo di ricorrenza (solo per le carte)

Indicazione del tipo di avvio della ricorrenza (solo per il canale 1503 relativo all'avvio della ricorrenza)

Nome del campo: azione ricorrente Formato stringa Valori: 'INIT_WITH_REFUND', 'INIT_WITH_PAYMENT'.

Nome del negozio (solo per VisaMobile)

Nome visualizzato all'utente nella notifica VisaMobile nell'applicazione mobile della banca (solo per il canale 1523 di VisaMobile)

Nome del campo: nome del commerciante Formato stringa Valori: Nome del negozio

Card Widget - Esempio di implementazione sul sito web di un partner

IMPORTANTE! Il seguente esempio di codice HTML è stato creato a scopo illustrativo. Per poterlo eseguire effettivamente sul computer locale, il seguente file HTML deve essere collocato sotto un dominio locale (qualsiasi, può essere test.local).
Questo HTML non può essere sparato nel browser come file locale, perché gli eventi JS scambiati tra l'IFRAME e la pagina vengono verificati per verificare la coerenza del dominio (e quindi deve essere presente un dominio).

La pagina seguente ha lo scopo di imitare Front Merchant, mostrando quali elementi devono essere implementati per integrarsi con il Widget Autopay.

Nel browser, la seguente pagina di esempio è composta da tre sezioni:

• la sezione superiore contiene una selezione di canali di pagamento specifici
• la sezione centrale contiene il luogo in cui sarà incorporato l'IFRAME HTML, in cui sarà inserito l'indirizzo del widget (visamobile o scheda standard, se necessario)
• la sezione inferiore contiene un pulsante (inattivo per impostazione predefinita) PayButon in bundle con l'SDK JS per controllare l'avvio del processo nel widget (in questo esempio, il pulsante si attiva solo quando riceve il messaggio che la convalida è corretta e i dati necessari per avviare il processo sono completi)

Quando si seleziona un canale per la carta (payway: 1500 o 1503), viene caricata una vista dedicata al modulo della carta (basata su HTML IFRAME). Quando nel widget vengono inseriti i dati completi e validi della carta, (grazie agli eventi di convalida) si attiva il pulsante "Paga" sul front-end dell'esercente.

CONSIGLIO: Come si può vedere nell'esempio, è possibile supportare il canale VisaMobile anche nel modello WhiteLabel. L'implementazione/layout è analogo a quello del widget della carta, pertanto il codice sottostante contiene già entrambi i casi.

Convalida e completamento dei dati

L'Autopay Widget JS SDK riceve eventi dal widget quando inserisce i dati della carta STATO_DI_VALIDITÀ con valore valido: falso

Una volta ottenuti i dati completi della carta, l'ultimo evento sarà STATO_DI_VALIDITÀ con valore valido: vero

{status: 'VALIDITY_STATUS', message: null, valid: true, id: 'M2Zl...mU2'}

L'attivazione del pulsante può essere basata su questo evento Pulsante di pagamento

CONSIGLIO: Nell'ambiente di test, i pagamenti con carta si basano su un mock 3ds e un mock di autorizzazione. Ai diversi scenari corrispondono numeri di carta di prova dedicati. L'elenco completo dei casi di test è riportato in un'appendice separata.

Schermo DCC

Se lo scenario e la carta soddisfano le condizioni per ottenere un'offerta DCC, apparirà un'ulteriore schermata con una proposta di conversione di valuta per il titolare della carta.

Il titolare della carta può scegliere se utilizzare l'addebito della carta nella sua valuta nativa o se lasciare la valuta originale. In questa schermata avviene anche la convalida.

La scelta della valuta del Titolare della carta non influisce sull'Esercente e sull'importo originale della transazione stessa, ma influisce sull'importo che verrà addebitato alla carta. Se il Titolare non desidera usufruire dell'offerta di conversione di valuta DCC, seleziona la valuta originale (che in questo caso è il PLN).

Ottenere un token

Il pulsante deve essere collegato all'SDK Autopay Widget JS, in modo che il suo clic attivi una chiamata all'applicazione widget.sendForm(); nel metodo WidgetConnection che, in ultima analisi, si tradurrà in un oggetto MODULO_INTERROTTO cioè ottenere il valore del paymentToken (nell'evento messaggio campo).

{status: 'FORM_SUCCESS', message: 'eyJ...n19', id: 'M2Z...ZmU2'}

Widget della scheda - Schema dettagliato della comunicazione e dello scambio di dati

Di seguito è riportato un diagramma dettagliato della comunicazione tra esercente, titolare di carta e sistemi di pagamento Autopay nel caso della cosiddetta integrazione WhiteLabel (ovvero utilizzando un widget della carta).

Trasferimento sicuro dei dati della carta al sistema Autopay e flusso completo delle transazioni:

• (0) Trasferimento dei dati di configurazione che avviano l'incorporazione del widget nel frontend.
• (1) Visualizzazione del formato della carta del widget incorporato nel frontend dell'esercente (i dati della carta non sono forniti nel frontend dell'esercente ma nel frontend del widget Autopay).
• (2) Inizia con l'inserimento dei dati della carta da parte del titolare.
• (3) Trasmissione dei dati della carta utilizzando una connessione TLS protetta da un certificato Extended Validation al backend di CardsAutopay. ** Applicabile solo se è possibile offrire la DCC ** (3a) Restituzione dei dettagli della proposta di conversione DCC ** (3b) Il titolare della carta decide se utilizzare la DCC ** (3c) Trasmissione dei dati della carta precedentemente inseriti dal titolare della carta e segue la decisione DCC
• (4) WidgetJS riceve il valore `paymentToken' da CardsAutopay e lo invia al Merchant Front (via JS).
• (5) Il Merchant Front riceve il token di pagamento dal Widget tramite un evento JavaScript.
• (6) Il Merchant Front passa il token di pagamento al Merchant Backend.
• (7) C'è un inizio di backend di Pre-transazione con paymentToken ricevuto in precedenza dal frontend.
• (8) L'API Autopay restituisce il continua la transazione URL che verrà utilizzato per reindirizzare all'inizio della transazione con l'utente
• (9) Il backend del commerciante inoltra l'URL di reindirizzamento al frontend del commerciante.
• (10) Reindirizzamento del titolare della carta dal sito web dell'esercente a PayAutopay per l'autenticazione 3DS.
• Segue la verifica del 3DS (a seconda della decisione della banca, può trattarsi di una verifica completa o semplificata)
• (11) Quando il titolare della carta "ritorna" dal 3DS, il risultato dell'autenticazione viene completato/raccolto e autorizzato.
• (12) L'Autopay riceve il risultato dell'addebito.
• (13) Lo stato della transazione viene trasmesso al sistema di pagamento online (in background).
• (14) Reindirizzamento del titolare della carta dal sito web PayAutopay (dopo l'autenticazione 3DS). al sito web del commerciante si verifica.
• (15) In modo asincrono al backend dell'esercente arriva il messaggio ITN con lo stato della transazione ** ( nel caso di una transazione che avvia una ricorrenza, il Backend dell'Esercente riceverà anche un messaggio supplementare RPAN )

Notifica dell'avvio di un pagamento automatico (RPAN)

Di seguito è riportato un esempio di una semplice implementazione HTML/JS che utilizza il widget VisaMobile (e il widget della carta)

{ 'status': 'FORM_SUCCESS', 'message': 'eyJrZ...', ... }

Cruciale per questa integrazione è il punto del codice JS responsabile della ricezione degli eventi, in particolare dell'evento con stato MODULO_INTERROTTO, in quanto contiene nel messaggio il valore del paymentToken che l'esercente deve passare al proprio backend per completare i parametri dell'API Autopay e consentire l'avvio del pagamento in Autopay.

Pagina di esempio

Nel browser, la seguente pagina di esempio è composta da tre sezioni:

• la sezione superiore contiene icone/bottoni per canali di pagamento specifici (utilizzando le rappresentazioni grafiche di Autopay)
• la sezione centrale contiene il segnaposto per l'IFRAME HTML, nel quale verrà inserito, se necessario, l'indirizzo del widget (visamobile o scheda standard, a seconda delle esigenze)
• la sezione inferiore contiene la voce (inattiva per impostazione predefinita) PayButon pulsante, fornito con l'SDK JS, che controlla l'avvio del processo nel widget (in questo esempio, il pulsante diventa attivo solo quando riceve un messaggio di corretta convalida e ottiene tutti i dati necessari per avviare il processo)

Quando si seleziona un canale dedicato a VisaMobile, viene visualizzata una vista dedicata (basata su HTML IFRAME), dove l'inserimento del numero di telefono completo (grazie ai messaggi di convalida) porta all'attivazione del pulsante "Paga".

Convalida e completamento dei dati

Quando si inserisce un numero di telefono, l'SDK del Widget Autopay JS riceve un messaggio STATO_DI_VALIDITÀ dal widget con il valore valido: falso Una volta ottenuto il numero di telefono completo, l'ultimo evento sarà STATO_DI_VALIDITÀ con il valore valido: vero.

{status: 'VALIDITY_STATUS', message: null, valid: true, id: 'M2Zl...mU2'}

L'attivazione del pulsante può essere basata su questo evento Pulsante di pagamento

Ottenere un token

Il pulsante deve essere collegato all'SDK Autopay Widget JS, in modo che il suo clic attivi una chiamata all'applicazione widget.sendForm(); nel metodo WidgetConnection che, in ultima analisi, si tradurrà in un oggetto MODULO_INTERROTTO cioè l'ottenimento del valore del paymentToken.

{status: 'FORM_SUCCESS', message: 'eyJ...n19', prefix: '48', phoneNumber: '666666666', id: 'M2Z...ZmU2'}

Visa Mobile widget - Schema dettagliato di comunicazione e scambio dati

Iniziare la transazione:

• (1) Iniziate inserendo il vostro numero di telefono nel widget VisaMobile.
• (2) Avviare la transazione in VisaMobile
• (3) Ritorno da VisaMobile
• (4) Ritornare dal widget a Merchant (usando JS) il file generato paymentToken.
• (5) Il front-end dell'esercente passa il token di pagamento al back-end dell'esercente.
• (6) Avvio del backend Pre-transazione con paymentToken con paymentToken ricevuto in precedenza.
• (7) Il ritorno riceve subito una risposta XML PENDING (perché viene elaborato in background).
• (8) Il front-end Merchant presenta una schermata in attesa del risultato.

Possibile annullamento della transazione (dal paywall di PayAutopay):

• (9a) Se l'utente non riceve la notifica nell'app mobile o cambia idea, ha la possibilità di annullare la transazione dall'interno del paywall.
• (9b) Il sistema CardsAutopay invia una richiesta di cancellazione a Visa.
• (9c) Il sistema CardsAutopay riceve il risultato della cancellazione da Visa.
• (9d) Il risultato della cancellazione viene ricevuto dal sistema PayAutopay e presentato all'utente sul paywall PayAutopay.
• (9e) In parallelo, un ITN viene inviato (con stato negativo) a Merchant

Carica e restituisce il risultato:

• (10) Attesa dei dati del token di pagamento da Visa (se il cliente VisaMobile conferma nell'app mobile di voler pagare con una carta specifica per un determinato ordine)
• (11) Segue un ordine di addebito.
• (12) Viene ricevuto un risultato di addebito positivo o negativo.
• (13) Lo stato della transazione viene inviato al gateway PayAutopay.
• (14) Il gateway Autopay invia il risultato della transazione all'Esercente sotto forma di ITN

Descrizione del codice HTML JS di esempio (Card Widget e VisaMobile)

Il codice seguente è stato utilizzato per generare le integrazioni di esempio citate nelle sezioni con esempi di implementazione del Widget Carta e del Widget Visa Mobile

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Autopay Widget Integration Example</title>
    <script src="?r=quot;https://testcards.autopay.eu/widget-new/widget-communication.min.js"></script>
    <style>/* omitted from the example */</style>
</head>
<body>
<div>
  <form onsubmit="submitForm(event)" novalidate>
   <div class="form-group"><p>Transaction amount:</p><span>1,23 PLN</span></div>

    <!-- example implementation of a merchant-side payment channel selection mechanism -->
    <p>Choose payment method:</p>
    <ul>
      <li onclick="setPayway(event, 1500)">One time payment with card</li>
      <li onclick="setPayway(event, 1503)">Remember your card</li>
      <li onclick="setPayway(event, 1523)">Pay with VisaMobile</li>
    </ul>

    <!-- the place where the HTML IFRAME with the widget will be injected -->
    <div class="form-group" id="iframe-wrapper">
      <iframe id="iframe"></iframe>
    </div>

    <!-- call to action button in the widget -->
    <button type="submit" id="button" disabled="disabled">PayButton</button>
  </form>
</div>
<script type="text/javascript">
window.addEventListener("load', () => {
    // auxiliary variables (only for the purpose of the example)
    var currentPayway = null;
    var widget = null;

    // example configurations depending on the devlopers' environment (only for the purpose of the example)
	var AUTOPAY_CARDS_DOMAIN_ENV_PROD = 'https://cards.autopay.eu';
	var AUTOPAY_CARDS_DOMAIN_ENV_TEST = 'https://testcards.autopay.eu';

	var MERCHANTS_SERVICE_ID_ENV_PROD = 903555;
	var MERCHANTS_SERVICE_ID_ENV_TEST = 903555;

    // auxiliary method to support payment channel selection and widget embedding
    function setPayway (event, paywayId) {
        if (currentPayway === paywayId) {
            return;
        }
        currentPayway = paywayId
        removeWidget();
        disableSubmitButton();
        markActiveIcon(event);

        if (paywayId === 1500) {
            startWidget('/widget-new/partner'   , { language: 'en', amount: 1.23, currency: 'PLN', serviceId: MERCHANTS_SERVICE_ID_ENV_TEST });
            return
        }
        if (paywayId === 1503) {
            startWidget('/widget-new/partner'   , { language: 'en', amount: 1.23, currency: 'PLN', serviceId: MERCHANTS_SERVICE_ID_ENV_TEST, recurringAction: 'INIT_WITH_REFUND' });
            return
        }
        if (paywayId === 1523) {
            startWidget('/widget-new/visamobile', { language: 'en', amount: 1.23, currency: 'PLN', serviceId: MERCHANTS_SERVICE_ID_ENV_TEST,  merchantName: 'ShopName' });
			return
        }
    }

    // auxiliary method (only for the purpose of the example) setting the border on the selected payment channel
    function markActiveIcon (event) {
        var currentActive = document.querySelector('ul li.active');
        if (currentActive) {
            currentActive.classList.remove('active');
        }
        var newActive = event.target;
        if (newActive.nodeName.toLowerCase() === 'img') {
            newActive = newActive.parentNode;
        }
        newActive.classList.add('active');
    }

    // the main method responsible for embedding the IFRAME with the widget and setting up communication between it and its object representation WidgetConnection
    function startWidget (widgetVariantUrl, widgetConfig) {
        if (!widgetEvents || !WidgetConnection) {
            return;
        }
        var iframeEl = document.getElementById('iframe');
        iframeEl.src = AUTOPAY_CARDS_DOMAIN_ENV_TEST + widgetVariantUrl;
        widget = new WidgetConnection(widgetConfig)

        widget.startConnection(iframeEl).then(() => {

            // handling the main, final event containing the PaymentToken value
            widget.on(widgetEvents.formSuccess, function (message, eventData) {
                console.log('payment token event =>', eventData);
                console.log('payment token value:', message);
                // here should be a merchant API call to pass the paymentToken (message) to the merchant backend;    <<<<<<<<<<<<<<<<<
            })

            // handling validation events during user/cardholder input in the widget
            widget.on(widgetEvents.validityStatus, function (message, eventData) {
                console.log('form validation status =>', eventData);
                if (eventData.valid) {
                    enableSubmitButton();
                } else {
                    disableSubmitButton();
                }
            })

            // handling the validation event when the user/cardholder enters data in the widget
            widget.on(widgetEvents.validationResult, function (message, eventData) {
                console.log('form validation result =>', eventData);
                if (eventData.valid) {
                    enableSubmitButton();
                } else {
                    disableSubmitButton();
                }
            })

            // handling the showModal event
            widget.on(widgetEvents.showModal, function () {
                console.log('show modal');
            })
        })
    }

    // an auxiliary method (only for the purpose of the example) setting the removal of the widget for payment channels other than cards (in the example, there is a 106 PBL channel)
    function removeWidget () {
        if (!widget) {
            return;
        }
        widget.stopConnection();
    }

    // auxiliary method (only for the purpose of the example)
    function enableSubmitButton () {
        document.getElementById('button').removeAttribute('disabled');
    }

    // auxiliary method (only for the purpose of the example)
    function disableSubmitButton () {
        document.getElementById('button').setAttribute('disabled', 'disabled');
    }

    // an auxiliary method (for the purpose of the example only) that binds the call of the active pay button to the sendForm() call in the widget object
    function submitForm (event) {
        event.preventDefault();
        if (!widget || widget.invalid) {
            return;
        }
        disableSubmitButton();
        widget.sendForm();
    }

    window.setPayway = setPayway;
    window.submitForm = submitForm
});
</script>
</body>
</html>

Pagamento automatico

Descrizione del pagamento automatico

I pagamenti automatici sono un modo estremamente comodo e sicuro di effettuare transazioni ricorrenti. Comporta l'incasso automatico dei crediti da parte del cliente alle date di pagamento previste. Il servizio deve essere prima attivato. Nel caso delle carte, ciò avviene reindirizzando il cliente al modulo di attivazione del servizio. Nel caso di BLIK, accettando un pagamento automatico nell'applicazione mobile. Una volta autorizzata con successo tale transazione di attivazione, l'AP trasmette al Partner un messaggio standard sul cambiamento di stato della transazione (ITN) e un messaggio sull'attivazione del servizio di pagamento automatico (RPAN). Il messaggio RPAN contiene il campo clientHashcon cui il partner identificherà lo specifico pagamento automatico durante i successivi addebiti e la disattivazione del servizio.

NOTA: Prima di avviare transazioni ricorrenti, il Partner è tenuto a familiarizzare con i requisiti delle organizzazioni di pagamento VISA e Mastercard, nonché con gli standard Autopay. Questi requisiti mirano a ridurre il rischio di chargeback e a garantire la conformità alle normative del settore. Informazioni dettagliate sono disponibili nell'articolo: Requisiti per i pagamenti automatici.

Tutte le transazioni all'interno del ciclo di vita di un pagamento automatizzato
(attivazione e addebito) vengono eseguiti all'interno di un'area dedicata.
Canali di pagamento (BLIK - GatewayID=522, Carte di pagamento - GatewayID = 1503) i gatewayType="Pagamento automatico".. Nel caso di integrazione
Per i pagamenti automatici BLIK, è possibile specificare (nei dati forniti prima di
integrazione) la durata dei pagamenti automatici attivati
(illimitato per impostazione predefinita) o di specificarlo nella transazione di inizializzazione
(parametro Tempo di validità ricorrente).

Attivazione del pagamento automatico

L'attivazione del pagamento automatico consiste in una transazione di attivazione dell'autorizzazione, una comunicazione ITN e un RPAN. Una volta ricevuto l'RPAN, il Partner è pronto a eseguire gli addebiti ricorrenti (o un clic).

Si tratta di un caso di attivazione del servizio di pagamento automatico durante
pagamento di un servizio/bene (quindi RecurringAction=INIT_WITH_PAYMENT e il regolamento della transazione al Partner).

Processo di attivazione del servizio di pagamento automatico

Il messaggio ITN inviato dopo un pagamento automatico è simile a quelli ricevuti dopo i pagamenti una tantum (è solo prolungato dall'utente che ha effettuato il pagamento. Dati ricorrenti nodo, e - per i pagamenti con carta - Dati scheda). Gli altri due elementi del processo di attivazione del servizio sono l'avvio della transazione e la RPAN.

Messaggio di avvio della transazione automatica

Il processo di attivazione del servizio viene avviato dal sito del partner avviando la transazione con il parametro Azione ricorrente consente di controllare il comportamento del sistema:

(a) valore INIT_WITH_PAYMENT - corrisponde all'attivazione del servizio di pagamento automatico al momento del pagamento di un servizio/merce (la carta o il conto vengono addebitati con l'importo dovuto e i fondi del pagamento vengono trasferiti al Partner); nell'elenco dei canali di pagamento disponibili, il Sistema presenta solo i pagamenti automatici (a meno che non sia stato selezionato un canale di pagamento nel Servizio),

(b) valore INIT_WITH_REFUND - corrisponde all'attivazione del servizio di pagamento automatico al di fuori del processo di pagamento del servizio/merce (la carta o il conto vengono addebitati con l'importo di 1 PLN, seguito dal rimborso automatico dei fondi sul conto del Cliente); nell'elenco dei canali di pagamento disponibili, il Sistema presenta solo pagamenti automatici (a meno che non sia stato selezionato un canale di pagamento sul Sito),

c) nessun parametro (o vuoto) - a meno che non sia stato selezionato un canale di pagamento sul Sito, il Sistema visualizzerà tutti i canali di pagamento disponibili per il Sito (compresi quelli automatici) e lascerà al Cliente la possibilità di decidere: pagamento unico o avvio del pagamento automatico. Se il Cliente sceglie il pagamento automatico, la transazione verrà addebitata al Partner secondo le modalità standard (e il RecurringAction=INIT_WITH_PAYMENT restituirà il parametro in RPAN).

NOTA: Non è consentito avviare transazioni di attivazione con il canale di pagamento automatico selezionato ma senza la RecurringAction selezionata.

In alcuni casi (se risulta dalla risposta del metodo dati legali) è necessario specificare anche i parametri Stato di accettazione ricorrente (con il valore ACCETTATOche significa che il cliente ha letto e accettato i termini e le condizioni del pagamento automatico sul Servizio Partner) e RecurringAcceptanceID.

L'attivazione del servizio di carta di pagamento automatico avviene tramite i format forniti da AP. Il cliente deve inserire i dati della carta: nome, cognome, numero di carta, data di scadenza e codice CVV. In caso di pagamento automatico da un conto bancario (BLIK), l'autorizzazione viene effettuata senza inserire i dati della carta: ad esempio con il codice BLIK (trasportato nei parametri di avvio in AuthorisationCode), o tramite BLIK OneClick Alias (trasportato nei parametri di avvio in BlikUIDKey/BlikUIDLabel).

Una volta autorizzata la transazione, il Sistema AP trasmette al Servizio Partner un messaggio di modifica dello stato della transazione (ITN) e un messaggio di attivazione del servizio di pagamento automatico (RPAN). Il messaggio RPAN è dedicato agli eventi di attivazione del pagamento automatico e contiene il suo identificativo (ClientHash), che il Partner utilizzerà per i successivi addebiti e disattivazioni del servizio. Il RPAN contiene anche informazioni su un'azione del processo di pagamento automatico (RecurringAction, descritta sopra).

Notifica dell'avvio di un pagamento automatico (RPAN)

Al ricevimento di uno stato di pagamento positivo per l'attivazione del pagamento automatico, viene inviato al Servizio un messaggio dedicato. Questa notifica consiste nell'invio da parte del Sistema AP di un documento XML contenente i dati relativi al pagamento automatico attivato. Il documento viene inviato tramite protocollo HTTPS (porta 443 di default), utilizzando il metodo POST, come parametro HTTP denominato ricorrente. Questo parametro viene memorizzato utilizzando il meccanismo di crittografia di trasporto Base64.

Formato del documento (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<recurringActivation>
		<serviceID>ServiceID</serviceID>
		<transaction>
			<orderID>OrderID</orderID>
			<remoteID>RemoteID</remoteID>
			<amount>999999.99</amount>
			<currency>PLN</currency>
			<gatewayID>GatewayID</gatewayID>
			<paymentDate>YYYYMMDDhhmmss</paymentDate>
			<paymentStatus>PaymentStatus</paymentStatus>                 
			<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
			<startAmount>999998.99</startAmount>
			<invoiceNumber>InvoiceNumber</invoiceNumber>
			<customerNumber>CustomerNumber</customerNumber>
			<customerEmail>CustomerEmail</customerEmail>
			<customerPhone>CustomerPhone</customerPhone>
		</transaction>
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<expirationDate>YYYYMMDDhhmmss</expirationDate>
		</recurringData>
		<cardData>
			<index>Index</index>
			<validityYear>ValidityYear</validityYear>
			<validityMonth>ValidityMonth</validityMonth>
			<issuer>Issuer</issuer>
			<bin>BIN</bin>
			<mask>Mask</mask>
		</cardData>
		<hash>Hash</hash>
	</recurringActivation>

Valori degli elementi: ID ordine, ID servizio, importo relativi a ciascun pagamento automatico attivato sono identici ai valori dei campi corrispondenti forniti dal Servizio all'avvio del rispettivo pagamento di inizializzazione.

Descrizione dei parametri restituiti per l'attivazione del pagamento automatico

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

CONSIGLIO: Elemento hash (messaggio) viene utilizzato per autenticare
il documento. Per una descrizione di come viene calcolato l'hash, vedere la sezione Sicurezza delle transazioni.

Risposta alla notifica

In risposta alla notifica, ci si aspetta uno stato HTTP di 200 (OK) e un testo in formato XML (non codificato Base64), restituito dal Servizio partner nella stessa sessione HTTP, contenente una conferma di ricezione del messaggio.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Elemento di conferma del pagamento automatico

Il conferma è utilizzato per comunicare lo stato di verifica dell'autenticità della transazione da parte del Servizio partner. Il valore dell'elemento è determinato dalla verifica della correttezza del valore dell'elemento serviceID confrontando i valori del parametro ID ordine e importo nel messaggio di notifica e nel messaggio di avvio della transazione e verificando la coerenza dell'hash calcolato dai parametri del messaggio con il valore passato nel campo hash del messaggio.

Per l'elemento sono previsti due valori conferma:

a) CONFERMATO - i valori dei parametri in entrambi i messaggi e il parametro hash corrispondono - la transazione è autentica;

b) NON CONFERMATO - i valori nei due messaggi sono diversi o c'è una mancata corrispondenza dell'hash - la transazione non è autentica;

CONSIGLIO: Il hash (nella risposta al messaggio) è usato per autenticare la risposta ed è calcolato a partire dai valori dei parametri della risposta. Per una descrizione di come viene calcolato l'hash, vedere la sezione Sicurezza delle transazioni.

Se non c'è una risposta corretta alle notifiche inviate, il sistema di pagamento online farà un altro tentativo di trasmissione dopo che è trascorso un tempo specificato. Il servizio del partner deve eseguire la propria logica di business (ad esempio, lanciare un servizio di pagamento automatico, inviare una lettera, ecc. ClientHash.

Schema di ripetizione dei messaggi ITN/ISTN/IPN/RPAN/RPDN

Di seguito è riportato uno schema che descrive il rinnovo programmato dei messaggi (ci riserviamo, tuttavia, la possibilità di rinnovare uno qualsiasi di essi in qualsiasi momento).

NOTA: La ripetizione continua di un messaggio identico da parte del Sistema indica una risposta mancante o errata da parte del Servizio e richiede al Partner di diagnosticarne urgentemente la causa.

Addebito per il pagamento automatico

Ricezione corretta dell'identificativo del servizio (ClientHash), rende il Partner pronto ad addebitare automaticamente al Cliente i beni/servizi acquistati dal Servizio. Il processo consiste in transazioni e comunicazioni ITN.

Di seguito viene illustrato il processo di addebito automatico al cliente del servizio/bene (quindi RecurringAction=MANUAL/AUTO e il regolamento della transazione al Partner).

Il messaggio ITN inviato dopo un pagamento automatico è simile a quelli ricevuti dopo un pagamento unico. È esteso solo dal nodo RecurringData e (per i pagamenti con carta) CardData.

Messaggio di avvio della transazione di pagamento automatizzata

Per eseguire un addebito automatico, il servizio partner deve eseguire una pre-transazione con un valore di ClientHash parametro, coerente con il servizio di pagamento automatico precedentemente attivato (proveniente da RPAN), con una Stato di accettazione ricorrente parametro di NON APPLICABILE e il corrispondente valore del parametro Azione ricorrente parametro:

a) AUTO - pagamento ricorrente (addebito senza coinvolgimento del cliente),

b) MANUALE - pagamento con un solo clic (addebito ordinato da
il cliente, chiamato OneClick).

NOTA: La partecipazione del cliente all'opzione MANUALE, di solito, si limita alla chiamata di un messaggio (selezionando nel servizio l'opzione di pagamento con la carta memorizzata). Nella maggior parte dei casi, è necessaria un'autorizzazione aggiuntiva presso la banca (sotto forma di codice 3DS o CVC). Quindi, invece di un addebito (e dello stato dell'ordine in risposta alla pre-transazione), il sistema restituirà un link per continuare - questo è il comportamento predefinito del sistema nell'ambiente di test. Per testare lo scenario di carico senza la necessità di ulteriori autorizzazioni, è necessario dichiarare la necessità di modificare la configurazione del Sistema per la durata del test.

NOTA: Opzione non disponibile per i pagamenti automatici BLIK (BLIK
OneClick).

Disattivazione del servizio

Il partner può disattivare il servizio di pagamento automatico in qualsiasi momento. Il processo può consistere in un messaggio che ordina la disattivazione e in un messaggio RPDN (dedicato agli eventi di cancellazione del servizio di pagamento automatico).

Può anche accadere che la cancellazione del servizio venga avviata dal lato AP (ad esempio, su richiesta del cliente, della banca o dell'organizzazione della carta). In tal caso, il sistema fornirà anche un messaggio RPDN.

Messaggio di disattivazione del pagamento automatico

Il servizio può essere disattivato tramite un messaggio dedicato. Tutti i parametri sono trasmessi con il metodo POST (all'indirizzo https://{gate_host}/disattiva_ricorrenze). Il protocollo è sensibile alle maiuscole e alle minuscole sia nei nomi dei parametri che nei valori. I valori dei parametri passati devono essere codificati in UTF-8.

Elenco dei parametri per la disattivazione del pagamento automatico

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

NOTA: L'elemento Hash (messaggio) viene utilizzato per autenticare il documento. Il valore di questo elemento è calcolato come valore di una funzione hash da una stringa contenente i valori concatenati di tutti i campi del documento e la chiave condivisa allegata.

Risposta

In risposta alla notifica, nella stessa sessione HTTP viene restituito un testo in formato XML contenente una conferma di ricezione.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
				<reason>Reason</reason>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Conferma dell'elemento

Il conferma è utilizzato per comunicare lo stato di verifica dell'autenticità dell'operazione da parte del Servizio. Il valore dell'elemento è determinato dalla verifica della correttezza dei valori dell'elemento serviceID e clientHash con quelli forniti nel messaggio RPAN all'inizio di un determinato pagamento di attivazione, nonché verificare la coerenza dell'hash calcolato dai parametri del messaggio con il valore fornito nel campo Hash.

Per l'elemento sono previsti due valori conferma:

a) CONFERMATO - i valori dei parametri sono corretti e il parametro Hash è coerente - l'operazione è autentica;

b) NON CONFERMATO - i valori in entrambi i messaggi non sono corretti o l'hash non corrisponde - l'operazione non è autentica;

NOTA: L'elemento hash (nel messaggio di risposta) è usato per autenticare la risposta ed è calcolato a partire dal valore dei parametri della risposta. Il valore di questo elemento è calcolato come valore di una funzione hash da una stringa contenente i valori concatenati di tutti i campi del documento (senza tag) e la chiave condivisa allegata. Per una descrizione dell'elemento Sicurezza delle transazioni.

Notifica di disattivazione del pagamento automatico (RPDN)

Quando il pagamento automatico viene disattivato per un dato ClientHashL'invio di un messaggio dedicato sotto forma di documento XML avviene tramite protocollo HTTPS (porta predefinita 443), utilizzando il metodo POST, con un parametro denominato ricorrente. Questo parametro viene memorizzato utilizzando il meccanismo di codifica di trasporto Base64.

Formato del documento (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<recurringDeactivation>
		<serviceID>ServiceID</serviceID>
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<deactivationSource>DeactivationSource</deactivationSource>
			<deactivationDate>DeactivationDate</deactivationDate>
		<recurringData>
		<hash>Hash</hash>
	</recurringDeactivation>

I valori degli elementi: serviceID, clientHash relativi a ciascun pagamento ciclico disattivato, sono identici ai valori dei campi corrispondenti, indicati nel messaggio RPAN all'inizio del rispettivo pagamento di inizializzazione.

Descrizione dei parametri restituiti

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

NOTA: L'elemento hash (messaggio) viene utilizzato per autenticare il documento. Il valore di questo elemento è calcolato come valore di una funzione hash da una stringa contenente i valori concatenati di tutti i campi del documento e una chiave condivisa allegata.

Conferma della ricezione del messaggio

In risposta alla notifica, ci si aspetta uno stato HTTP 200 (OK) e un testo in formato XML (non codificato Base64), restituito dal Servizio nella stessa sessione HTTP, contenente una conferma di ricezione del messaggio.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Conferma dell'elemento

Il conferma è utilizzato per comunicare lo stato di verifica dell'autenticità dell'operazione da parte del Servizio. Il valore dell'elemento è determinato dalla verifica della correttezza dei valori dell'elemento serviceID e clientHash con quelli forniti nel messaggio RPAN all'inizio di un determinato pagamento di inizializzazione e verificando la coerenza dell'hash calcolato dai parametri del messaggio con il valore fornito nel campo hash.

Per l'elemento sono previsti due valori conferma:

a) CONFERMATO - i valori dei parametri sono corretti e i parametri hash sono coerenti - operazione autentica

b) NON CONFERMATO - i valori in entrambi i messaggi non sono validi o l'hash non corrisponde - l'operazione non è autentica

NOTA: L'elemento hash (nel messaggio di risposta) viene utilizzato per autenticare la risposta e viene calcolato a partire dai valori dei parametri della risposta. Per una descrizione di come viene calcolato l'hash, vedere la sezione Sicurezza delle transazioni.

In assenza di una risposta corretta alle notifiche inviate, il sistema farà ulteriori tentativi per comunicare lo stato più recente della transazione dopo che è trascorso il tempo specificato. Il Servizio partner deve eseguire la propria logica di business (ad esempio, l'invio di un'e-mail di conferma) solo dopo il primo messaggio relativo a un determinato stato di pagamento.

CONSIGLIO: Si consiglia di leggere anche le sezioni Monitoraggio delle comunicazioni ITN/ISTN/IPN/RPAN/RPDN e Schema di ripetizione dei messaggi ITN/ISTN/IPN/RPAN/RPDN.

Avvio di una transazione con parametri aggiuntivi

L'avvio della transazione può essere effettuato con i parametri aggiuntivi descritti nelle sezioni seguenti.

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Cestino prodotti

Descrizione del carrello di prodotti

Il carrello dei prodotti viene inviato come parametro (metodo POST) denominato Prodotti. Il suo valore è codificato con il protocollo di trasporto Base64.

Formato prima della codifica (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<productList>
		<product>
			<subAmount>SubAmount1</subAmount>
			<params>Params1</params>
		</product>
		<product>
			<subAmount>SubAmount2</subAmount>
			<params>Params2</params>
		</product>
		…
		<product>
			<subAmount>SubAmountN</subAmount>
			<params>ParamsN</params>
		</product>
	</productList>

Il elenco prodotti deve contenere almeno 1 nodo prodotto ogni elemento prodotto deve contenere un nodo subImporto e params ogni elemento.

Il subImporto deve contenere un importo positivo del prodotto (il separatore decimale è un punto seguito da due cifre al centesimo). La somma degli importi dei prodotti successivi deve essere uguale all'importo specificato nell'elemento Importo (importo della transazione).

Se le condizioni di cui sopra non sono soddisfatte, il sistema restituisce un errore.

Parametri dell'elemento

Il params può essere utilizzato per trasmettere informazioni specifiche sul prodotto. I nomi dei parametri e il loro significato sono soggetti a un accordo in forma operativa ogni volta durante l'integrazione.

Di seguito sono riportati alcuni esempi di parametri di prodotto e il loro significato.

• In questo caso, il nodo contiene il nome del prodotto:

		<params>
			<param name="productName" value="Product name 1" />
		</params>

• In questo caso, il nodo contiene due valori assegnati al prodotto, che possono indicare, ad esempio, il tipo di prodotto e il suo nome:

		<params>
			<param name="productType" value="ABCD" />
			<param name="productName" value="Product name 1" />
		</params>

• Nel caso in cui il Servizio abbia un saldo nel Sistema, e intenda effettuare rimborsi al Cliente di tutto o parte dell'importo pagato per il prodotto designato, è tenuto a trasferire nel prodotto il suo unico identificativo (parametro denominato productID di tipo string{1,36} (caratteri alfanumerici latini e caratteri ammessi: _ e -)):

		<params>
			<param name="productID" value="12456" />
		</params>

• Se il Partner utilizza una struttura estesa (punti di regolamento multipli), è tenuto a trasmettere in ogni prodotto l'identificativo del punto di regolamento (parametro denominato idBalancePoint di tipo intero{1,10}):

		<params>
			<param name="idBalancePoint" value="12456" />
		</params>

• Nel caso in cui il Partner utilizzi la fatturazione TRASFERIMENTO DI MASSA, cioè

  • ogni transazione viene regolata immediatamente al momento del deposito e

  • i regolamenti vengono effettuati a livello di prodotto/punto di fatturazione (cioè dopo il deposito vengono effettuati tanti trasferimenti di regolamento quanti sono i prodotti nel paniere), e

  • non sono stati impostati dati di fatturazione fissi (o non tutti i dati di fatturazione sono impostati in modo rigido nella configurazione di fatturazione),

Il partner deve fornire in ogni prodotto i dati mancanti per la fatturazione di quel prodotto. I parametri disponibili che costituiscono i dati sono:

• clienteNRB - numero di conto target per la fatturazione.
  Formato NRB (26 cifre con checksum). Se, durante l'integrazione, viene stabilito l'utilizzo di conti non polacchi, allora il campo trasferisce l'IBAN e l'intervallo di dati previsto per il campo cambia in: caratteri latini alfanumerici (min. 15, max. 32 caratteri). Specificando valori nel formato IBAN sarà necessario specificare nel prodotto anche i parametri swiftCode, foreignTransferMode.

• titolo - Il titolo del trasferimento di regolamento del prodotto. In alcuni casi, indipendentemente dall'AP, il titolo del trasferimento del regolamento può essere modificato autonomamente dalla Banca da cui è avvenuto il regolamento.
  Caratteri alfanumerici latini e caratteri dell'intervallo accettabili:

• NomeRicevitore - il nome del destinatario del bonifico che effettua la compensazione del prodotto.
  Caratteri alfanumerici latini e caratteri dell'intervallo accettabili:

Esempio di applicazione dei parametri a un prodotto:

	<params>
		<param name="customerNRB" value="83109010980000000107285707" />
		<param name="title" value="Settlement of product X" />
		<param name="receiverName" value="John Smith" />
	</params>

• Nel modello Marketplace, il Partner è tenuto a fornire un identificativo del punto di fatturazione (parametro denominato idPunto di equilibrio di tipo intero{1,10}). Questo vale anche per l'accredito del saldo del punto di regolamento.

Esempio di parametri del carrello:

	<params>
		<param name="idBalancePoint" value="12456" />
		<param name="productName" value="Balance transfer for Autopay" />
	</params>

Visualizzazione del carrello dei prodotti nella schermata di selezione del canale di pagamento

Se durante le discussioni relative al paniere prodotti è stato stabilito che il suo riepilogo deve essere visualizzato nella pagina del Sistema (schermata di selezione del Canale di pagamento), è possibile specificare le etichette di ciascun parametro utilizzato nel paniere. Il Sistema può utilizzare l'etichetta predefinita del parametro o adottarla all'inizio della transazione.

Il valore di titolo sarà visualizzato prima del valore del parametro del prodotto.

Esempio di attributo title

	<params>
		<param name="productName" value="Product name 1" title="Name"/>
		<param name="productType" value="ABCD" title="Type"/>
	</params>

Opzioni di comunicazione online aggiuntive per il partner

Campi aggiuntivi nel messaggio ITN/IPN della transazione in entrata

Descrizione

Le notifiche istantanee di una modifica dello stato di una transazione possono includere campi aggiuntivi (vedere Schemi di preautorizzazione). La loro presenza è un
configurazione, determinata in fase di integrazione (per impostazione predefinita viene inviato solo il nodo clienteDati).

Il fatto che si tratti di un messaggio ITN o IPN è determinato esclusivamente dalla presenza di un nodo prodotto.

Elenco completo dei campi aggiuntivi del messaggio ITN/IPN

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

NOTA: Per il conteggio dei valori Hash, l'opzione valore degli attributi del successivo prodotto.params nodi vengono presi.

Esempio di messaggio ITN/IPN con parametri aggiuntivi (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
	  <serviceID>ServiceID</serviceID>
	  <transactions>
	  <transaction>
		<orderID>OrderID</orderID>
		<remoteID>RemoteID</remoteID>
		<amount>999999.99</amount>
		<currency>PLN</currency>
		<gatewayID>GatewayID</gatewayID>
		<paymentDate>YYYYMMDDhhmmss</paymentDate>
		<paymentStatus>PaymentStatus</paymentStatus>                 
		<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
		<addressIP>127.0.0.1</addressIP>
		<customerNumber>1111111</customerNumber>
		<title>title</title>
		<customerData>
		  <fName>fName</fName>
		  <lName>lName</lName>
		  <streetName>streetName</streetName>
		  <streetHouseNo>streetHouseNo</streetHouseNo>
		  <streetStaircaseNo>streetStaircaseNo</streetStaircaseNo>
		  <streetPremiseNo>streetPremiseNo</streetPremiseNo>
		  <postalCode>postalCode</postalCode>
		  <city>city</city>
		  <nrb>nrb</nrb>
		  <senderData>senderData</senderData>    
		</customerData>
		<verificationStatus>verificationStatus</verificationStatus>
		<verificationStatusReasons>
		   <verificationStatusReason>reason1</verificationStatusReason>
		   <verificationStatusReason>reason2</verificationStatusReason>
		   <verificationStatusReason>reason3</verificationStatusReason>
		</verificationStatusReasons>
		<startAmount>999998.99</startAmount>    
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<expirationDate>YYYYMMDDhhmmss</expirationDate>
		</recurringData>
		<cardData>
			<index>Index</index>
			<validityYear>ValidityYear</validityYear>
			<validityMonth>ValidityMonth</validityMonth>
			<issuer>Issuer</issuer>
			<bin>BIN</bin>
		</cardData>
		<product>
			<subAmount>SubAmount</subAmount>
			<params>
				<param name="idBalancePoint" value="idBalancePoint"/>
				<param name="invoiceNumber" value="invoiceNumber"/>
				<param name="customerNumber" value="customerNumber"/>
				<param name="subAmount" value="SubAmount"/>
			</params>
		</product>
	  </transaction>
	  </transactions>
	  <hash>Hash</hash>
	</transactionList>

Descrizione dettagliata della modifica dello stato di verifica - per una transazione completata con successo (risultato positivo o negativo)

Descrizione dettagliata della modifica dello stato di verifica - per una transazione non completata correttamente

Stati dettagliati delle transazioni

Il messaggio ITN per una transazione in entrata contiene, oltre allo stato del pagamento (campo Stato del pagamento), una descrizione dettagliata di questo stato (campo pagamentoStatoDettagli). Questa descrizione è da considerarsi informativa, l'elenco dei valori ammessi è in continua crescita e la comparsa di nuovi valori non può implicare la non accettazione del messaggio ITN.

Valori di stato della transazione - Stati generali (indipendenti dal canale di pagamento)

Valori di stato delle transazioni - Stati delle carte

Valori di stato della transazione - Stati specifici della transazione BLIK

Notifica immediata di una modifica dello stato del prodotto (IPN)

Nel caso di un Partner che utilizza struttura estesa (Cestino prodotti con più punti di fatturazione), il sistema fornisce una notifica indipendente dei cambiamenti di stato per ciascun prodotto. Questo servizio ha senso se i singoli punti di fatturazione devono ricevere le proprie notifiche. In questo caso, la configurazione dell'IPN (indirizzo per le notifiche, campi da includere nel messaggio, ecc.) è memorizzata proprio a livello di configurazione del punto di fatturazione. La struttura dell'IPN è simile a quella dell'ITN (ampliata solo con un prodotto nodo simile a quello descritto nella sezione Campi aggiuntivi nel messaggio ITN/ transazione di inserimento IPN, completata solo dalla ripetizione dell'espressione subImporto nei parametri). Esempio di IPN nella sottosezione Campi aggiuntivi nel messaggio ITN/IPN di una transazione di ingresso).

Notifica immediata di una modifica dello stato di una transazione di regolamento (ISTN)

È possibile fornire messaggi relativi a tutte le erogazioni (liquidazioni, erogazioni a saldo e rimborsi) effettuate dal Sistema nell'ambito del servizio di pagamento. Poiché il servizio non è abilitato di default, la necessità di questo servizio, insieme all'indirizzo postale ISTN, deve essere richiesta dal Partner in fase di determinazione dei requisiti.

In caso di esito positivo dell'avvio della comunicazione ISTN, il Sistema trasmette immediatamente le notifiche relative all'ordine dell'operazione di regolamento (eventuali prelievi/rimborsi) e alla modifica del suo stato. Le conferme vengono inviate all'indirizzo del server di servizio del Partner stabilito durante la configurazione aggiuntiva del Servizio del Partner:

https://shop_name/receipt_of_settlement_information

Questa notifica consiste nell'invio da parte del Sistema di un documento XML contenente i nuovi stati delle transazioni. Il documento viene inviato tramite il protocollo HTTPS (porta predefinita 443). Il documento viene inviato con il metodo POST, come parametro HTTP denominato transazioni. Questo parametro viene memorizzato utilizzando il meccanismo di codifica Base64.

Formato del documento (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
		<serviceID>ServiceID</serviceID>
		<transactions>
			<transaction>
				<isRefund>true/false</isRefund>
				<productID>ProductID</productID>
				<orderID>OrderID</orderID>
				<orderOutID>OrderOutID</orderOutID>
				<remoteID>RemoteID</remoteID>
				<remoteOutID>RemoteOutID</remoteOutID>
				<amount>999999.99</amount>
				<currency>PLN</currency>
				<transferDate>YYYYMMDDhhmmss</transferDate>
				<transferStatus>TransferStatus</transferStatus>                 
				<transferStatusDetails>TranasferStatusDetails</transferStatusDetails>
				<title>Title</title>
				<receiverBank>ReceiverBank</receiverBank>      
				<receiverNRB>ReceiverNRB</receiverNRB>
				<receiverName>ReceiverName</receiverName>
				<receiverAddress>ReceiverAddress</receiverAddress>
				<senderBank>SenderBank</senderBank>
				<senderNRB>SenderNRB</senderNRB>
			</transaction>
		</transactions>
		<hash>Hash</hash>
	</transactionList>

Parametri restituiti

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Risposta alla notifica

In risposta alla notifica, ci si aspetta un testo in formato XML (non codificato Base64), restituito dal Servizio partner nella stessa sessione HTTP, contenente una conferma della ricezione dello stato della transazione.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<transactionsConfirmations>
			<transactionConfirmed>
				<remoteOutID>RemoteOutID</remoteOutID>
				<confirmation>Confirmation</confirmation>
			</transactionConfirmed>
		</transactionsConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Il conferma è utilizzato per comunicare lo stato di verifica dell'autenticità della transazione da parte del Servizio partner. Il valore dell'elemento è determinato dalla verifica della correttezza del valore dell'elemento serviceID e verificare che l'hash calcolato corrisponda al valore passato nel campo hash.

Per questo elemento sono previsti due valori:

a) CONFERMATO - il parametro hash è coerente - la transazione è autentica;

b) NON CONFERMATO - il parametro hash è inconsistente - la transazione non è autentica;

Se non c'è una risposta corretta alle notifiche inviate, il sistema farà ulteriori tentativi per comunicare un nuovo stato dopo un tempo specificato. Il Servizio partner deve eseguire la propria logica di business solo dopo il primo messaggio relativo a un determinato stato di pagamento.

CONSIGLIO: Vale la pena di dare un'occhiata a Schema di ripetizione dei messaggi ITN/ISTN/IPN/RPAN/RPDN.

Descrizione dettagliata del comportamento e della modifica degli stati di regolamento (transferStatus)

Nel modello di base, il sistema fornirà solo uno stato di SUCCESSOTuttavia, è possibile una notifica più accurata. L'opzione completa deve essere notificata durante l'integrazione e prevede il seguente schema di transizioni di stato.

ZUn ordine per una transazione di regolamento invia uno stato di IN ATTESA. In seguito, il sistema consegnerà SUCCESSO o FALLIMENTO. Per una transazione per la quale SUCCESSO si è verificato, non dovrebbe più esserci un cambiamento di stato in FALLIMENTO. Tuttavia, può verificarsi una modifica dello stato di dettaglio (i successivi messaggi di modifica dello stato di dettaglio sono solo informativi e non devono comportare la riesecuzione di alcuna logica aziendale).

In casi particolari (ad esempio un errore della banca), una transazione originariamente confermata può essere passata per una nuova esecuzione e quindi cambiare il suo stato in IN ATTESA e di nuovo a SUCCESSO.

Un altro caso particolare potrebbe essere un FALLIMENTO (ad esempio, dopo un errore interno del sistema), quindi sostituito da un messaggio SUCCESSO stato.

Servizi aggiuntivi

Interrogazione dell'elenco dei canali di pagamento attualmente disponibili

Descrizione

Per costruire una vista di selezione dei metodi di pagamento sul sito web, il sistema consente di interrogare da remoto l'elenco attuale dei canali di pagamento. A tal fine, richiamare il metodo gatewayList (https://{gate_host}/gatewayList/v3) con i relativi parametri (in formato JSON). Tutti i parametri sono trasmessi utilizzando la tecnologia REST. Il protocollo è sensibile alle maiuscole e minuscole sia per i nomi dei parametri che per i valori. I valori dei parametri trasmessi devono essere codificati in UTF-8.

Elenco dei parametri disponibili

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Esempio di messaggio

{
	"ServiceID": 47498,
	"MessageID": "11111111111111111111111111111111",
	"Currencies":"PLN,EUR",
	"Language": "PL",
	"Hash": "306519f632e53a5e662de0125da7ac3f8135c7e4080900f2b145d4b25ff1b55d"
}

Risposta alla richiesta

In risposta a una richiesta, vengono restituiti 2 elenchi di definizioni nella stessa sessione HTTP:

(a) Canali di pagamento (nodo gatewayList)

(b) Gruppi di pagamento (nodo gatewayGruppi)

Di seguito viene riportata una descrizione dettagliata del messaggio restituito:

Esempio di risposta

{
    "result": "OK",
    "errorStatus": null,
    "description": null,
    "gatewayGroups": [
        {
            "type": "PBL",
            "title": "Internet transfer",
            "shortDescription": "Select the bank from which you want to order the payment".,
            "description": null,
            "order": 1,
            "iconUrl": null
        },
        {
            "type": "FR",
            "title": "Transfer details",
            "shortDescription": "Order a transfer using the details provided",
            "description": null,
            "order": 2,
            "iconUrl": null
        },
        {
            "type": "BNPL",
            "title": "Buy now, pay later",
            "shortDescription": "Buy now, pay later",
            "description": null,
            "order": 3,
            "iconUrl": null
        }
    ],
    "serviceID": "10000",
    "messageID": "2ca19ceb5258ce0aa3bc815e80240000",
    "gatewayList": [
        {
            "gatewayID": 106,
            "name": "PBL test payment",
            "groupType": "PBL",
            "bankName": "NONE",
            "iconURL": "https://testimages.autopay.eu/pomoc/grafika/106.gif",
            "state": "OK",
            "stateDate": "2023-10-03 14:35:01",
            "description": "Test payment",
            "shortDescription": null,
            "descriptionUrl": null,
            "availableFor": "BOTH",
            "requiredParams": ["Nip"],
            "mcc": {
                "allowed": [1234, 9876],
                "disallowed": [1111]
            },
            "inBalanceAllowed": true,
            "minValidityTime": null,
            "order": 1,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 0.01,
                    "maxAmount": 5000.00
                }
            ],
            "buttonTitle": "Pay"
        },
        {
            "gatewayID": 9,
            "name": "Transfer from another bank",
            "groupType": "FR",
            "bankName": "BANK TEST",
            "iconURL": "https://testimages.autopay.eu/pomoc/grafika/9.gif",
            "state": "OK",
            "stateDate": "2023-10-03 14:35:02",
            "description": "<b>Fast transfer</b>",
            "shortDescription": "Fast transfer",
            "descriptionUrl": null,
            "availableFor": "BOTH",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": true,
            "minValidityTime": null,
            "order": 2,
            "currencies": [
                {
                    "currency": "PLN"
                }
            ],
            "buttonTitle": "Generate transfer details"
        },
		{
            "id": 701,
            "name": "Pay later with Payka",
            "groupType": "BNPL",
            "bankName": "NONE",
            "iconUrl": "https://testimages.autopay.eu/pomoc/grafika/701.png",
            "state": "OK",
            "stateDate": "2023-10-03 14:37:10",
            "description": "<div class=\"payway_desc\"><h1>Cost details</h1><p>Pay later - one-off up to 45 days (...). Offer details at: <a href="?r="https://payka.pl\" target=\"_blank\">Payka.pl</a></p></div>",
            "shortDescription": "Pay later - in one go up to 45 days or in several equal instalments",
            "descriptionUrl": null,
            "availableFor": "B2C",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": false,
            "minValidityTime": 60,
            "order": 3,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 49.99,
                    "maxAmount": 7000.00
                }
            ],
            "buttonTitle": "Pay"
        }
    ]
}

NOTA: Il risultato dell'interrogazione del metodo deve essere aggiornato ogni minuto (chiamando gatewayList Se non c'è risposta o se c'è una risposta errata, dovrebbe essere visualizzata l'ultima configurazione nota e corretta dei canali di pagamento. Questo è il secondo motivo per mantenere una copia temporanea della configurazione dei canali di pagamento. gatewayList sul servizio partner. Una risposta non valida deve essere considerata come una risposta vuota, un timeout o un elenco vuoto di gatewayGruppi o gatewayList nodi.

Richiesta di un elenco delle autorizzazioni formali attualmente disponibili

Descrizione

Una descrizione dell'integrazione che consente l'utilizzo di una lista di pagamento incorporata nel servizio (o nell'app mobile), senza fasi di transizione. In alcuni casi, invece di una fase di transizione, il comportamento standard del sistema prevede un avvio bloccato della transazione.

I contenuti formali pertinenti (ossia le clausole informative e, se del caso, i termini e le condizioni) dovrebbero essere visualizzati già al momento della selezione del metodo di pagamento, e successivamente la conferma della loro visualizzazione e, se del caso, accettazione (sotto forma di identificatori) dovrebbe essere inviata al Sistema di pagamento online.

Il sistema consente di interrogare a distanza l'elenco corrente degli obblighi e il relativo contenuto formale. A tal fine, è necessario richiamare l'opzione dati legali (https://{gate_host}/legalData) con i parametri appropriati (in formato JSON).

CONSIGLIO: Tutti i parametri sono trasmessi utilizzando la tecnologia REST. Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi che nei valori dei parametri. I valori dei parametri trasmessi devono essere codificati in UTF-8.

Elenco dei parametri disponibili

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Esempio di messaggio

	{
		"ServiceID": 102422,
		"MessageID": "11111111111111111111111111111111",
		"GatewayID": 1500,
		"Language": "PL",
		"Hash":"61789013d932e2bc728d6206f7e9222b93e3176f7f07f6aa8cce1ccd65afaf0d"
	}

Elenco dei parametri restituiti

In risposta alla richiesta, viene restituito un elenco (nella stessa sessione HTTP), contenente ulteriori contenuti formali sotto forma di: ID, tipo e formulazione del contenuto, sua posizione nel Servizio, indirizzo alle regole e altre informazioni aggiuntive.

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Esempio di risposta

	{
		"serviceID": "102422",
		"messageID": "11111111111111111111111111111111",
		"gatewayID": "1500",
		"language": "PL",
		"serviceModel": "PAYER",
		"regulationList": [
			{
				"regulationID": 6288,
				"type": "RECURRING",
				"url": "https://host/path?params",
				"labelList": [
					{
						"labelID": 1,
						"inputLabel": "<ul><li>\r\nI have read and accept <a id=\"regulations_pdf\" target=\"_blank\" href=https://{gate_host}/path?params>Regulations for the payment services</a> and <a class=\"privacy-policy\" href=\"https://{gate_host}/polityka-prywatnosci.pdf\" target=\"_blank\">Privacy Policy</a></li><li>\r\nI want the service to be provided without delay and, in the event of withdrawal, I know that I will not be reimbursed for the services provided at my request until the withdrawal has taken place\r\n</li></ul>",
						"placement": "ABOVE_BUTTON",
						"showCheckbox": true,
						"checkboxRequired": true
					}
				]
			},
			{
				"regulationID": 1,
				"type": "PRIVACY",
				"labelList": [
					{
						"labelID": 1,
						"inputLabel": "Autopay uses cookies. By remaining on this website, you consent to the use of cookies in accordance with the <a class=\"privacy-policy\" href="?r="https://{gate_host}/polityka-prywatnosci.pdf\" target=\"_blank\">Autopay S.A. privacy policy.</a> You can manage cookies yourself by changing the settings of your browser or device software accordingly."
						"placement": "BOTTOM_OF_PAGE",
						"showCheckbox": false,
						"checkboxRequired": false
					}
				]
			}
		],
		"hash": "61789013d932e2bc728d6206f7e9222b93e3176f7f07f6aa8cce1ccd65afaf0d",
		"result": "OK",
		"errorStatus": null,
		"description": null
	}

Descrizione della gestione delle risposte

Poiché i requisiti formali per il contenuto delle clausole, la loro distribuzione e il metodo di accettazione dipendono dal canale di pagamento utilizzato, questo metodo deve essere invocato ogni volta che viene selezionato (da qui il parametro obbligatorio del GatewayID).

Il contenuto e il comportamento pertinenti dovrebbero essere adattati dinamicamente alle risposte del sistema (ad esempio, dovrebbe apparire una casella di controllo obbligatoria con una clausola informativa e un link ai termini e alle condizioni). Naturalmente, affinché l'applicazione venga eseguita rapidamente, è auspicabile l'uso di una cache per ricordare le risposte delle chiamate recenti (ad esempio, per 1 minuto).

Il consenso visualizzato (ed eventualmente approvato) al momento del passaggio al pagamento deve essere confermato nel Sistema allegando al messaggio di avvio della transazione il parametro start del suo identificativo (e quindi il corrispondente valore del parametro regolamentoID).

A seconda del valore del parametro tipo campo dei regolamenti:

- per la clausola visualizzato/accettato di tipo=DEFAULT:

a. al parametro DefaultRegulationAcceptanceID il suo valore di regolamentoID;

b. il Stato di accettazione della regolamentazione predefinita deve essere impostato su ACCETTATO e

c. il Tempo di accettazione del regolamento predefinito deve essere impostato sul valore corrispondente al momento in cui il consenso viene accettato selezionando la casella di controllo e facendo clic sul pulsante "Avvia pagamento".

- per la clausola visualizzato/accettato di tipo=RECURRING:

a. al RecurringAcceptanceID dovrebbe essere il suo parametro regolamentoID VALORE;

b. il Stato di accettazione ricorrente deve contenere il valore ACCETTATO e

c. il Tempo di accettazione ricorrente deve essere impostato sul valore corrispondente al momento in cui il consenso viene accettato selezionando la casella di controllo e facendo clic sul pulsante "Avvia pagamento".

NOTA: I campi (ad es. serviceModel, url, labelID) e i valori dei campi (ad es. PSD2, RODO, PRIVACY) del dati legali non sono obbligati a essere gestiti, ma si deve prevedere la possibilità che si presentino nella risposta della richiesta.

Richiesta di saldo

Descrizione

Per tutti i servizi è possibile interrogare il saldo corrente. A questo scopo, il metodo balanceGet https://{gate_host}/webapi/balanceGet con i relativi parametri. Tutti i parametri vengono passati tramite il metodo POST (Tipo di contenuto: application/x-www-form-urlencoded). Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi dei parametri che nei valori. I valori dei parametri passati devono essere codificati in UTF-8.

Elenco dei parametri disponibili per la bilancia corrente

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Risposta alla richiesta di saldo corrente

In risposta alla richiesta, viene restituito un testo (nella stessa sessione HTTP) in formato XML, contenente una conferma dell'operazione da eseguire o una descrizione dell'errore.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balanceGet>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<balance>Balance</balance>
		<currency>Currency</currency>
		<hash>Hash</hash>
	</balanceGet>

o

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balanceGet>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<balance>Balance</balance>
		<currency>Currency</currency>
		<hash>Hash</hash>
	</balanceGet>

Elenco dei campi di risposta

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Equilibrio dell'offerta

Descrizione

Per i servizi che hanno un saldo nel Sistema, è possibile eseguire un'operazione di ricarica per futuri rimborsi. A tal fine, avviare la transazione con l'opzione Modalità di transazione con il valore NESSUNO e Importo indicando il importo di ricarica.

Utilizzo Pre-transazione consentirà di consegnare semplicemente la transazione conclusa al pagatore (ad esempio, fornendo l'indirizzo contabile del partner in CustomerEmail).

NOTA: Il servizio deve essere concordato con il custode commerciale. Nel modello Marketplace, sarà inoltre necessario costruire un paniere di prodotti indicando quale Punto di regolamento (BalancePointID) deve essere alimentato.

Prelievi dal saldo

Descrizione

Per i servizi che hanno un saldo nel Sistema, è possibile eseguire
un'operazione di prelievo di tutto o parte del saldo su un conto definito per
regolamento. A tal fine, è necessario richiamare il metodo saldoPagamento (https://{gate_host}/settlementapi/balancePayoff) con i relativi parametri.

Tutti i parametri vengono passati tramite il metodo POST (Content-Type: application/x-www-form-urlencoded). Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi dei parametri che nei valori. I valori dei parametri passati devono essere codificati in UTF-8.

Elenco dei parametri disponibili per il prelievo del saldo

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

NOTA: Uno dei campi ID servizio o Punto di equilibrioID è necessario. W
Se si specificano entrambi, l'elaborazione della richiesta viene interrotta e viene visualizzato un errore http.

Risposta alla richiesta

Alla ricezione di una richiesta di prelievo di saldo, il Sistema esegue una prima verifica dei campi e dei loro valori inviati nel messaggio e salva l'ordine per l'esecuzione. In risposta alla richiesta, viene restituito un testo in formato XML (nella stessa sessione HTTP), contenente la conferma che l'ordine è stato salvato nella coda per l'esecuzione o la descrizione dell'errore (la struttura del messaggio di errore è descritta nella sezione Messaggi di errore.

NOTA: La conferma di ricezione di un ordine non equivale alla sua effettiva esecuzione. Un prelievo dal saldo può essere elaborato fino a 30 minuti dopo l'invio della richiesta di prelievo e non sempre va a buon fine. In caso di problemi riscontrati durante l'elaborazione di un prelievo dal saldo (ad esempio, fondi insufficienti nel saldo), il giorno lavorativo successivo viene inviato un rapporto contenente informazioni sui prelievi dal saldo che non sono andati a buon fine.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</balancePayoff>

o

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</balancePayoff>

Descrizione dei campi

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

NOTA: Tutte le risposte diverse da quelle ipotizzate (ad esempio con campi non validi, in particolare con campi vuoti o non validi) sono state inviate a un'altra persona. hash) può essere considerato un errore. Nel caso in cui il sistema autorizzi il mittente di un messaggio di ritorno ma l'operazione fallisca, la risposta seguirà lo schema descritto in Messaggi di errore. In caso di errore di comunicazione o di saldo insufficiente (ad esempio ON_DEMAND_ERROR), l'ordine può essere ritentato. Se il saldo è bloccato (BALANCE_DISABLED) o la configurazione non è attiva (PARTNER_DISABLED), l'ordine non deve essere rinnovato.

IMPORTANTE! In caso di errore in risposta a una richiesta di prelievo del saldo, la richiesta può essere ripetuta, ma si noti che qualsiasi richiesta di prelievo che non si concluda con un errore può essere eseguita. In caso di problemi di connessione, che superino il tempo massimo di risposta, la richiesta può essere ripetuta con lo stesso MessageID senza timore di duplicare l'ordine.
In caso di saldo bloccato (BALANCE_DISABLED) o di configurazione inattiva (PARTNER_DISABLED), la richiesta non deve essere rinnovata. 3 errori consecutivi (indipendentemente dalla causa) bloccheranno il servizio di erogazione su richiesta per l'IP mittente del messaggio specificato per 10 minuti - le chiamate durante questo periodo per questo IP termineranno con un errore TEMPORARY_DISABLED.

Rimborso delle transazioni

Descrizione

Per i servizi che presentano un saldo nel Sistema, è possibile effettuare l'operazione di restituzione al Cliente di tutto o parte dell'importo pagato per la transazione indicata. Il rimborso dell'intera transazione può essere effettuato una sola volta (in caso di ripetuti tentativi di rimborso della stessa transazione, il Sistema restituisce un errore opportunamente descritto). Il rimborso di parte dell'importo di una transazione può essere effettuato più volte, purché la sua somma non superi l'importo del deposito.

Per eseguire il rimborso di una transazione, richiamare il metodo transazioneRimborso (https://{gate_host}/settlementapi/transactionRefund) con i relativi parametri. Tutti i parametri vengono passati tramite il metodo POST (Tipo di contenuto: application/x-www-form-urlencoded). Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi che nei valori dei parametri. I valori dei parametri passati devono essere codificati in UTF-8.

Elenco dei parametri disponibili

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

In risposta alla richiesta, viene restituito un testo in formato XML (nella stessa sessione HTTP), che conferma l'operazione o descrive l'errore (descritto di seguito).

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<transactionRefund>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</transactionRefund>

Descrizione dei campi

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

L'opzione di rimborso delle transazioni pagate è possibile fino a 12 mesi fa, a partire dalla data di inizio della transazione. Fanno eccezione i pagamenti BLIK che, a causa di vincoli temporali da parte del fornitore del canale di pagamento, possono essere rimborsati fino a 6 mesi prima.

Le scadenze di cui sopra si applicano all'elaborazione delle restituzioni tramite il pannello amministrativo e il pannello di controllo. transazioneRimborsoad esempio tramite i propri strumenti amministrativi. Quando questi valori vengono superati, viene restituito un errore (TRANSAZIONE_TROPPO_VECCHIA_PER_RIMBORSARE). Lo schema di funzionamento è analogo a quello dei prelievi da saldo. Ovvero, il Sistema accetta l'ordine e lo elabora in modo asincrono entro un massimo di 30 minuti; in caso di fallimento, le informazioni sulle operazioni che si concludono con un errore vengono inviate in un report il giorno lavorativo successivo.

In caso di problemi di connessione, che superino il tempo massimo di risposta, la richiesta può essere rinnovata con la stessa MessaggioID senza timore di richieste doppie. Tutte le risposte diverse da quella ipotizzata (cioè con campi non corretti, in particolare campi vuoti o non corretti) sono state inviate a un'altra persona. hash). Se il sistema autorizza il mittente del messaggio di ritorno, ma l'operazione non riesce, viene restituito un messaggio di errore.

Restituzione del prodotto

Descrizione

Per i siti che hanno un saldo nel Sistema e che specificano l'opzione ID prodotto nel carrello dei prodotti, è possibile eseguire un'operazione di restituzione al Cliente di tutto o parte dell'importo pagato per il prodotto indicato. La restituzione dell'intero importo di un prodotto può essere eseguita una sola volta (in caso di ripetuto tentativo di ordinare la restituzione dello stesso prodotto, il Sistema restituisce un errore opportunamente descritto). I rimborsi parziali del prodotto possono essere effettuati più volte, purché il loro totale non superi l'importo pagato per il prodotto.

Per eseguire una restituzione di prodotto, richiamare il metodo prodottoRimborso(https://{gate_host}/settlementapi/productRefund) con i parametri appropriati. Tutti i parametri vengono passati con il metodo POST (Content-Type: application/x-www-form-urlencoded). Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi dei parametri che nei valori. I valori dei parametri passati devono essere codificati in UTF-8.

Elenco dei parametri

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Risposta alla richiesta

In risposta alla richiesta, viene restituito un testo (nella stessa sessione HTTP) in formato XML, contenente una conferma dell'operazione da eseguire o una descrizione dell'errore.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<productRefund>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</productRefund>

Descrizione dei campi

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

L'opzione di rimborso delle transazioni pagate è possibile fino a 12 mesi fa, a partire dalla data di inizio della transazione. Fanno eccezione i pagamenti BLIK che, a causa di vincoli temporali da parte del fornitore del canale di pagamento, possono essere rimborsati fino a 6 mesi prima.

Le scadenze di cui sopra si applicano all'elaborazione dei rimborsi tramite il pannello di amministrazione e prodottoRimborsoad esempio tramite i propri strumenti di amministrazione. Se questi valori vengono superati, viene restituito un errore (TRANSAZIONE_TROPPO_VECCHIA_PER_RIMBORSARE).

Lo schema di funzionamento è analogo a quello dei prelievi da saldo. In altre parole, il Sistema accetta l'ordine e lo elabora in modo asincrono entro un massimo di 30 minuti; in caso di errore, le informazioni sulle operazioni che si concludono con un errore vengono inviate in un report il giorno lavorativo successivo.

In caso di problemi di connessione, che superino il tempo massimo di risposta, la richiesta può essere rinnovata con lo stesso MessageID senza temere di avere richieste duplicate. Tutte le risposte diverse da quella ipotizzata (cioè con campi errati, in particolare campi vuoti o errati) sono da considerarsi come un'eccezione. hash). Se il sistema autorizza il mittente del messaggio di ritorno, ma l'operazione non riesce, viene restituito un messaggio di errore.

Richiesta di informazioni sullo stato di un rimborso o di un ritiro del saldo

Descrizione

Una volta effettuato il rimborso o il prelievo del saldo, abbiamo la possibilità di verificare lo stato della transazione di fatturazione e
quale identificativo gli è stato assegnato dal Sistema di pagamento online. A tal fine, richiamare il metodo dettagli (https://{gate_host}/settlementapi/outDetails) con i parametri corrispondenti. Tutti i parametri vengono passati tramite il metodo POST (Content-Type: application/x-www-form-urlencoded). Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi dei parametri che nei valori. I valori dei parametri passati devono essere codificati in UTF-8.

Elenco dei parametri disponibili per il prelievo del saldo

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

NOTA: Uno dei campi ID servizio o Punto di equilibrioID è necessario.
Se si specificano entrambi, l'elaborazione della richiesta viene interrotta e viene visualizzato un errore http.

Risposta alla richiesta

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<outDetails>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
	  	<status>Status</status>
		<remoteOutId>RemoteOutId</remoteOutId>
		<hash>Hash</hash>
	</outDetails>

o

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<outDetails>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<status>Status</status>
		<remoteOutId>RemoteOutId</remoteOutId>
		<hash>Hash</hash>
	</outDetails>

Descrizione dei campi

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Pagina di riepilogo della transazione

Descrizione

Il sistema consente di visualizzare un riepilogo della transazione al cliente. A tal fine, il partner può creare dei link di attivazione con il metodo dei parametri appropriati. conferma (https://{gate_host}/web/conferma/pagamento). Tutti i parametri sono trasferiti con il metodo GET. Il protocollo è sensibile alle maiuscole e alle minuscole sia per i nomi dei parametri che per i valori. I valori dei parametri passati devono essere codificati in UTF-8.

Elenco dei parametri per il metodo di riepilogo della transazione

Il reindirizzamento di un Cliente con i parametri corretti comporta la visualizzazione di un riepilogo della transazione (con contenuti che dipendono dal suo stato) o di informazioni sulla sua assenza (se il Sistema non la trova).

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

NOTA: Il servizio deve essere attivato previo accordo con il supervisore aziendale. È possibile modificare il contenuto dei messaggi o adattare il layout grafico (questi sono soggetti a un accordo in forma operativa ogni volta durante l'integrazione).

Richiesta di informazioni sullo stato di una transazione

Descrizione

Per tutti i servizi è possibile interrogare il saldo corrente. A questo scopo, il metodo Stato della transazione (https://{gate_host}/webapi/transactionStatus) con i relativi parametri. Tutti i parametri vengono passati tramite il metodo POST (Content-Type: application/x-www-form-urlencoded). Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi dei parametri che nei valori. I valori dei parametri passati devono essere codificati in UTF-8.

Elenco dei parametri disponibili per lo stato della transazione

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Intestazione HTTP per la richiesta di stato della transazione

Per una corretta interrogazione, insieme ai parametri passati deve essere inviata un'intestazione HTTP definita con un contenuto appropriato. L'intestazione allegata deve essere denominata 'BmHeader' e hanno il seguente valore 'pay-bm', nella sua interezza, dovrebbe essere la seguente BmHeader: pay-bm'.. In caso di messaggio valido, viene restituito (nella stessa sessione HTTP) un testo in formato XML contenente tutte le transazioni con l'OrderID indicato, insieme alle informazioni di base su di esse.

CONSIGLIO: Questa situazione può verificarsi, ad esempio, quando il cliente cambia il canale di pagamento, richiama la stessa transazione dalla cronologia del browser, ecc. Il sistema consente di bloccare questi casi, ma l'opzione è sconsigliata (non sarebbe possibile pagare la transazione abbandonata).

IMPORTANTE! Se la query si riferisce a un ID ordine presente in più di 50 transazioni di un determinato servizio, viene restituita una risposta (XML) con il codice di errore 403.

Struttura di risposta quando viene raggiunto il limite di transazioni con lo stesso orderId:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<transaction>
    <reason>LIMIT_REQUESTED_TRANSACTIONS_WITH_THE_SAME_ORDER_ID_AND_SERVICE_ID_EXCEEDED</reason>
    <description>Transaction limit 50 with the same order id {{ORDER_ID}} and service id {{SERVICE_ID}} exceeded. Requested count {{TRANSACTION_AMOUNT}}
    </description>
</transaction>

Elenco dei campi per una query sullo stato della transazione

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

NOTA: Poiché il metodo può restituire più transazioni, le transazioni successive vengono scaricate nell'Hash (secondo l'ordine di comparsa delle transazioni nella risposta). All'interno di una determinata transazione, si applica l'ordine in base al numero accanto al campo (escluso il parametro ServiceID, livello superiore).

Esempio di funzione hash stringa

		Hash = funkcja(<serviceID> + „|” +
	<orderID1> + „|” + <remoteID1> + „|” + <amount1> + „|” + <currency1> + „|” + <gatewayID1> + „|” + <paymentDate1> + „|” + <paymentStatus1> + „|” + <paymentStatusDetails1> + „|” +
	<orderID2> + „|” + <remoteID2> + „|” + <amount2> + „|” + <currency2> + „|” + <gatewayID2> + „|” + <paymentDate2> + „|” + <paymentStatus2> + „|” + <paymentStatusDetails2> + …

Gestione delle risposte alle interrogazioni sullo stato delle transazioni - proposta di gestione di più transazioni nella risposta

Annullamento di una transazione non pagata

Descrizione dell'annullamento di una transazione non pagata

Per tutti i servizi è possibile annullare una transazione avviata ma non pagata chiamando il metodo transazioneAnnulla (https://{gate_host}/webapi/transactionCancel) con i parametri corrispondenti. Tutti i parametri vengono passati tramite il metodo POST (Content-Type: application/x-www-form-urlencoded).

Il protocollo è sensibile alle maiuscole e minuscole sia nei nomi che nei valori dei parametri. I valori dei parametri trasmessi devono essere codificati in UTF-8.

Elenco dei parametri disponibili per l'annullamento di una transazione non pagata

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Intestazione per l'annullamento di una transazione non pagata

Per una corretta interrogazione, insieme ai parametri passati deve essere inviata un'intestazione HTTP definita con un contenuto appropriato. L'intestazione allegata deve essere denominata 'BmHeader' e hanno il seguente valore 'pay-bm'. Nella sua interezza, dovrebbe essere come segue "BmHeader: pay-bm".

Nel caso di un messaggio valido, viene restituito un testo in formato XML (nella stessa sessione HTTP), contenente la conferma dell'operazione o la descrizione dell'errore.

Struttura di conferma (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transaction>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<confirmation>ConfStatus</confirmation>
		<reason>Reason</reason>
		<hash>Hash</hash>
	</transaction>

Elenco dei parametri per l'annullamento di una transazione non pagata

IMPORTANTE! L'ordine degli attributi per l'enumerazione Hash deve seguire la loro numerazione.

Risposte alle richieste di annullamento delle transazioni

Se il messaggio è sintatticamente corretto, il sistema restituirà una delle seguenti coppie che descrivono il risultato dell'elaborazione. Oltre all'interpretazione, si raccomanda di controllare lo stato della transazione (metodo Stato della transazione).

Si noti che una volta che almeno una transazione è stata annullata con successo, non è possibile avviarne una nuova o continuare una transazione già avviata con lo stesso nome. ID ordine.

Messaggi di errore

Descrizione dei messaggi di errore

Tutti i messaggi di errore vengono restituiti come documento XML, contenente il codice dell'errore, il nome e la descrizione. A causa dell'elevata variabilità degli errori possibili, non viene mantenuta una documentazione completa degli errori.

CONSIGLIO: Il descrizione descrive ogni errore in modo dettagliato (il campo codice di stato e nome possono essere ignorati).

Esempio di errore (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<error>
		<statusCode>55</statusCode>
		<name>BALANCE_ERROR</name>
		<description>Wrong services balance! Should be 100 but is 40</description>
	</error>

Modelli di transazione e di regolamento

Questa sezione presenta i modelli, gli scenari degli eventi e le informazioni sui flussi.

Modello paywall

Il modello più semplice, in cui la scelta dei canali di pagamento avviene sulle pagine Autopay (paywall).

Modello WhiteLabel

È caratterizzato dalla presentazione dei canali di pagamento da parte dell'esercente. A tal fine, è necessario ottenere un elenco di canali con le relative descrizioni dal file elenco gateway/v3 e ottenere un elenco delle norme e dei regolamenti necessari per ogni canale di pagamento (/dati legali). Il resto del processo è lo stesso del modello Paywall.

Struttura estesa dei servizi e dei punti di fatturazione

La struttura del partner è costituita da almeno 1 servizio (identificato da un identificatore ID servizio) e un numero qualsiasi di conti punti (identificati da un identificatore idPunto di equilibrio).

• I servizi sono di solito le fonti dei link di pagamento (sito web, app mobile, e-mail, ecc.). I servizi distribuiscono anche il traffico relativo a diversi settori (pagamenti di fatture, acquisti di e-Commerce, ecc.). Poiché la transazione è identificata da una coppia di ID ordine e ID servizioSi può dire che "il servizio corrisponde al livello della transazione".

• I punti di regolamento sono definiti se è necessario distinguere in qualche modo i pagamenti che li compongono (ad esempio, indicandoli nelle segnalazioni o nei regolamenti indipendenti). Poiché il prodotto di una transazione è identificato dal punto di regolamento associato (idPunto di equilibrio), si può dire che il "punto di fatturazione corrisponde al livello del prodotto".

Il paniere di prodotti (e quindi anche i punti di fatturazione) può non essere presente nella struttura che descrive il Partner. Il motivo dell'aggiunta dei punti di fatturazione alla struttura influenza la decisione sul modello di fatturazione:

• La necessità di distinguere le componenti di un deposito nell'elenco delle transazioni (nei report) non implica necessariamente il regolamento separato di ogni prodotto o punto di fatturazione; in questa situazione, i modelli di fatturazione a livello di servizio (batch o dopo ogni deposito) sono solitamente sufficienti.

• La necessità di separare i regolamenti componenti di un deposito comporta l'utilizzo di un modello di regolamento a livello di punto di regolamento (aggregato o dopo ogni deposito).

Di seguito è riportata un'illustrazione di una struttura esemplificativa (senza indicare uno specifico modello di insediamento)

Modelli di insediamento

Modello di regolamento collettivo per le transazioni (modello predefinito)

Il regolamento sintetico avviene il giorno lavorativo successivo (D+1).

Modello di regolamento per le transazioni dopo ogni pagamento

Il regolamento dopo ogni pagamento può essere eseguito immediatamente dopo la ricezione del pagamento da parte del Cliente ai dati della transazione indicati nei parametri del Link di pagamento (opzioni: Conto del destinatario, Titolo del trasferimento del regolamento, Nome del destinatario del trasferimento del regolamento).

Modello di fatturazione collettiva dei prodotti

Il regolamento sintetico avviene il giorno lavorativo successivo (D+1).

Modello di fatturazione del prodotto dopo ogni pagamento

Il regolamento dopo ogni pagamento può essere effettuato immediatamente dopo la ricezione del pagamento da parte del Cliente ai dati del prodotto indicati nei parametri del Link di pagamento (opzioni: Conto destinatario, Titolo del trasferimento del regolamento, Nome del destinatario del trasferimento del regolamento).

Modello di liquidazione on-demand

Le liquidazioni possono essere ordinate dal socio chiamando il metodo: transazioneSettlement.