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 numerosi metodi di pagamento disponibili sul mercato, come bonifici bancari, Pay by link, BLIK, Google Pay, Apple Pay. In questa documentazione troverete tutto ciò che vi serve per implementare rapidamente un gateway di pagamento nel vostro negozio online. La documentazione sui pagamenti online Autopay comprende sezioni come. Elaborazione di transazioni e regolamenti, Registrazione e gestione dei punti di regolamento tra l'AP e la piattaforma del mercato dei partner., Registrazione e funzionamento dei Servizi basati sul Modulo Integratore, Estensioni aggiuntive.

Definizioni

Applicazione - Applicazione mobile del partner, che comunica con il SDK del sistema di pagamento online Autopay per registrare le transazioni.

AP - Autopay Spółka Akcyjna con sede legale a Sopot in ul. Powstańców Warszawy 6, iscritta nel registro degli imprenditori tenuto dal Tribunale Distrettuale di Danzica-Północ a Danzica, VIII Divisione Commerciale del Registro Nazionale dei Tribunali con numero KRS 0000320590, NIP 585-13-51-185, Regon 191781561, con capitale sociale di 2.205 PLN 500 (interamente versato), sottoposta a vigilanza della Commissione di vigilanza finanziaria e iscritta nel registro degli istituti di pagamento nazionali con il numero IP17/2013, proprietaria del Sistema.

Punto di equilibrio - oggetto nel Sistema di Pagamento che rappresenta il Negozio integrato con la Piattaforma Marketplace e registrato nel Sistema di Pagamento utilizzando il modulo messo a disposizione del Partner da AP.

ClientHash - nei messaggi; esso consente di assegnare al Cliente lo strumento di pagamento (ad es. Carta) in modo anonimo. Su questa base, il Partner può attivare gli addebiti successivi nel modello di pagamento automatico.

Modello di Commissione - Il modello di commissione concordato con l'integratore. Descrive i valori delle commissioni per le transazioni passate all'AP e all'integratore.

Giorno lavorativo - nei giorni feriali dal lunedì al venerdì, esclusi i giorni festivi.

Modulo per l'integratore - sito web in cui è presente un modulo che consente al Cliente di registrarsi, modificare o aggiungere un altro Servizio.

Strumento di pagamento (Canale di pagamento) - un insieme di procedure concordate o un dispositivo individualizzato, utilizzato dal cliente per inviare un ordine di pagamento, ad esempio carta, PBL.

Strumento di trasferimento elettronico - Un insieme di procedure o un dispositivo personalizzato concordato tra il Partner e l'AP, utilizzato dal Partner per impartire un ordine di pagamento che consenta l'esecuzione di un prelievo di fondi dal saldo al conto bancario del Partner o del Cliente e da un altro strumento di pagamento appartenente al Partner o al Cliente. La fornitura della funzionalità è soggetta ad accordi individuali tra il Partner e AP.

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

IPN (Notifica immediata del prodotto) - Una 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 (estesa 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) - notifiche immediate di modifica dello stato di un'operazione di regolamento. Il sistema trasmette immediatamente le notifiche del fatto che un'operazione di regolamento è stata ordinata (eventuali ritiri/restituzioni) e di una modifica del suo stato.

ICN (Notifica di configurazione istantanea) - Notifica immediata della configurazione di un negozio appena registrato, comunicazione di informazioni su una 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 modifica dei dati AML, di abilitazione/disabilitazione di un canale di pagamento.

Scheda - una carta di pagamento emessa nell'ambito degli schemi VISA e Mastercard, autorizzata dai regolamenti di tali schemi a eseguire Transazioni senza la sua presenza fisica.

Cliente (pagatore) - una persona che effettua un pagamento sul Sito web per servizi
data-deepl-translation/>o prodotti del Partner utilizzando il Sistema.

Cestino prodotti - è l'informazione sulle componenti del pagamento, trasmessa (nel link di pagamento) al Sistema per la successiva elaborazione. Ogni prodotto del carrello è descritto da due campi obbligatori: il componente dell'importo e un campo che consente di passare parametri specifici al prodotto.

Link per il pagamento - richiesta che abilita l'inizio della transazione di input (descritta in parte Inizio della transazione). Può essere utilizzato direttamente sulle pagine web (metodo POST), mentre nelle e-mail ai clienti si deve utilizzare il metodo Pre-transazione per ottenere un link breve al pagamento (metodo GET).

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

Mercato - Una soluzione di pagamento che funziona all'interno 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 Advanced Transaction Settlement e Settlement Transaction consentono di effettuare pagamenti direttamente dal Cliente alla Controparte del Partner, tenendo conto del Paniere di Prodotti. La fornitura della funzionalità è soggetta a accordi individuali tra il Partner e AP.

Modello di pagamento - modello in cui la commissione per la transazione effettuata viene pagata dal cliente ad 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 - 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 web.
Un partner, nel caso del modello Marketplace, è un'entità, che non è un consumatore, interessata a gestire l'accettazione da parte dell'AP dei pagamenti dovuti al partner per prodotti o servizi distribuiti dal partner.

Pay By Link (PBL) - strumento che consente l'esecuzione di pagamenti tramite un bonifico intrabancario 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 informativi del destinatario, numero del suo conto bancario, importo e data di esecuzione del bonifico) vengono compilati automaticamente grazie al sistema di scambio 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 del file 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 senza la necessità di inserire ogni volta i dati della carta o i dati di autorizzazione del
trasferimento.

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

Pagamento ciclico - è un pagamento automatico ordinato senza
data-deepl-translation/>il coinvolgimento del Cliente (da parte del Servizio Partner).

Pre-transazione - ordinamento specifico (eseguito in background) del link di pagamento
.

Trasferimento di verifica - La parte del processo relativa alla registrazione e alla modifica dei Servizi del Partner nel Sistema. Comporta per il Partner l'esecuzione di un trasferimento di fondi per verificare i dati e il conto bancario per l'erogazione dei fondi al Partner. La verifica dei dati è un obbligo dell'AP ai sensi, tra l'altro, della 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 il termine sopra specificato, il sistema attribuirà automaticamente uno stato negativo. Questo processo si applica alle verifiche in cui Autopay invia al cliente una richiesta di completamento dei dati e non riceve indietro le informazioni necessarie per completare la verifica.

Conto di pagamento (saldo) - Un conto di pagamento gestito da AP per il Partner in cui vengono raccolti i fondi depositati dai Clienti.

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 o i siti web del Partner integrati con il Sistema in cui il Cliente può acquistare prodotti o servizi dal Partner (o dal Partner Contraente 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 AP fornisce al Partner un'applicazione che consente l'elaborazione dei pagamenti del Cliente effettuati con gli Strumenti di pagamento, nonché la verifica dello stato dei pagamenti e la ricezione dei pagamenti.

Trasferimento rapido - L'esecuzione di pagamenti tramite bonifico intrabancario dal conto del Cliente al conto dell'AP. Il pagamento 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 del 19 agosto 2011 sui servizi di pagamento.

Transazione di ingresso - la parte del processo di gestione del pagamento relativa al pagamento effettuato dal cliente all'AP.

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

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

Validità del link - 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.

Validità delle transazioni - parametro che specifica il momento oltre il quale il Sistema di pagamento online si blocca e restituisce automaticamente i pagamenti del cliente. Il valore predefinito è calcolato aggiungendo 6 giorni alla data in cui il Cliente ha selezionato il Canale di pagamento. Può anche essere impostato dal parametro ValidityTime nel Link di pagamento. In questo caso, allo scadere del tempo indicato, il collegamento non è più attivo e i pagamenti vengono restituiti al Cliente. La validità massima della transazione è di 31 giorni.

Widget per l'autopagamento - un meccanismo che consente di effettuare pagamenti con carta per prodotti/servizi offerti dal Partner, in cui i dati della carta vengono inseriti dal Cliente in un meccanismo incorporato direttamente nel sito Web del Partner. L'invocazione del formato widget Card 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 di 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à nel Servizio seleziona il canale di pagamento e accetta le norme (a condizione che la necessità di accettarle derivi da accordi individuali tra il Partner e l'AP), e l'inizio della transazione contiene un campo GatewayID compilato (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 a una pagina in base al canale di pagamento selezionato oppure (per i pagamenti automatici, e-wallet o BLIK) viene effettuato un tentativo di addebito sulla carta o sul conto presso il fornitore del canale di pagamento.

Indirizzi delle comunità

TEST

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

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

PRODUZIONE

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

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

Elaborazione di transazioni e regolamenti

Diagramma di flusso del servizio di transazione e compensazione

Sul Sito del Partner, una volta completato l'ordine, al cliente
viene presentata l'opzione di poter effettuare un pagamento tramite il Sistema
. Facendo clic sul link corrispondente 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 (cfr. Modello paywall) o

b) direttamente da un Canale di Pagamento (Banca, BLIK o per il pagamento con Carta) - (vedi Modello WhiteLabel).

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à stato superato, il cliente riceverà un messaggio corrispondente (la verifica della validità della transazione avviene anche quando viene modificato lo stato del 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, precedentemente concordata tra l'AP e il Partner, o un valore dinamico trasmesso dal Partner all'inizio della transazione.

Modello di integrazione consigliato consiste nel trasmettere un messaggio per avviare una transazione di 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), diagnostica della correttezza dei parametri trasmessi e molte altre estensioni.

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

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

Lo stato di autorizzazione (pagamento) ricevuto dal Canale di pagamento viene trasmesso dal Sistema al Servizio partner mediante un messaggio ITN. Il Sistema ripeterà l'invio di messaggi finché la ricezione non sarà confermata dal Servizio partner o la notifica scadrà. Le transazioni, che vengono pagate dopo la scadenza del periodo di validità della transazione - saranno restituite al Cliente (mittente del bonifico).

Facoltativamente, il Sistema può notificare il fatto che è stata emessa una transazione di regolamento
. A tal fine viene utilizzato un messaggio ISTN opportunamente modificato.

Fasi di integrazione della gestione delle transazioni e dei 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 dall'AP al Partner e nella direzione inversa.

Vengono inoltre fornite informazioni generali, ovvero i canali di pagamento attivi insieme a grafici (come risultato dell'interrogazione dell'elenco dei canali di pagamento disponibili).

Facoltativamente, possono essere presenti ulteriori dati trasmessi dal Partner 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 i saldi prepagati). Per i pagamenti automatici BLIK anche la durata 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
• Meccanismo di funzione di scelta rapida
• 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
• Meccanismo di funzione di scelta rapida
• 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 operativo. Se necessario, vale la pena di familiarizzare anche con i parametri aggiuntivi o i servizi
.

Test di integrazione e migrazione all'ambiente di produzione

Durante il test, completare i campi bianchi del foglio e rispedirlo ad AP per confermare la corretta integrazione di prima di migrare all'ambiente di produzione.

CONSIGLIO: Prima della distribuzione in produzione, si raccomanda di eseguire i test in conformità con il documento 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

Quando avvia una transazione, il Servizio partner trasmette al sistema di pagamento online i parametri necessari alla sua esecuzione e alla 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 sia nei nomi che nei valori dei parametri
. I valori dei parametri trasmessi devono essere codificati in UTF-8 (e transport-protocol-encode prima dell'invio, a meno che lo strumento usato 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 della transazione

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

NOTE: 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 concluso.

Esempio di avvio di una transazione:

Indirizzo:

• https://{host_gates}/pathway

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 dei loro
, causerà l'interruzione del processo di pagamento con un codice di errore della transazione e un breve messaggio di errore (senza ritorno alla pagina del Servizio partner).

IMPORTANTE! "Coppia di parametri ID servizio i ID ordine identifica univocamente la transazione. Non è consentita la ripetizione del valore del parametro
. ID ordine per l'intera durata della fornitura di servizi da parte del Sistema ad un
Servizio Partner (ID servizio)."

Parametro opzionale GatewayID è utilizzato per specificare il Canale di pagamento, con cui deve essere effettuato il pagamento. Ciò consente di trasferire la schermata di selezione dei Canali di pagamento al Servizio. L'elenco attuale degli identificativi dei canali di pagamento, insieme ai loghi, è disponibile tramite il metodo gatewayList.

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 del Partner.

Reindirizzamento al sito del partner

Descrizione del reindirizzamento al sito del partner

Subito dopo aver completato l'autorizzazione alla transazione, il Cliente viene reindirizzato dal sito web del Canale di pagamento al sito web online del Sistema di pagamento, dove il Cliente viene automaticamente reindirizzato al Servizio del Partner.

Il reindirizzamento viene attuato inviando una richiesta HTTPS (utilizzando il metodo GET) a un indirizzo di ritorno predeterminato sul Servizio 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://sklep_nazwa/strona_powrotu?ServiceID=123458&OrderID=123402816&Hash=5432d69a66d721b2f5f785432bf5a1fc1b913bdb3bba465856a5c228fe95c1f8

Notifiche istantanee (ITN)

Descrizione delle notifiche istantanee

Il Sistema trasmette le notifiche di modifica dello stato delle transazioni non appena riceve tali informazioni dal Canale di pagamento, e il messaggio si riferisce sempre a una singola transazione. Le conferme sono inviate dal Sistema di pagamento online all'indirizzo del server del Servizio del Partner, come stabilito al momento dell'aggiunta della configurazione del Servizio del Partner.

NOTE: 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 (Certificate authority) Il server deve presentarsi con una catena di certificati completa (Chain of Trust) La comunicazione deve essere basata su TLS proxy versione 1. 2 o 1.3 *Altre forme di sicurezza della connessione, ad esempio VPN, mTLS devono essere concordate individualmente.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://sklep_nazwa/odbior_statusu

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) - metodo POST, come parametro HTTP con il nome transazioni. Questo parametro è memorizzato utilizzando il meccanismo di codifica 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>

NOTE: Nodo transazioni può contenere solo un nodo transazione (e quindi la notifica riguarda sempre una transazione). Valori degli elementi ID ordine i importo relativi a ciascuna delle transazioni sono identici ai valori dei campi corrispondenti forniti dal Servizio partner all'inizio della rispettiva transazione.

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) è usato per autenticare il documento. Per una descrizione di come viene calcolato l'hash, vedere la sezione Sicurezza delle transazioni.

Risposta alla notifica immediata

La risposta di notifica prevede uno stato HTTP di 200 (OK) e un testo in formato XML (non codificato Base64), restituito dal Partner Service nella stessa sessione HTTP, contenente la conferma della 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
.

Se non c'è una risposta corretta alle notifiche inviate, il Sistema farà ulteriori tentativi per comunicare l'ultimo stato della transazione dopo che è trascorso un tempo specificato. Il servizio partner deve eseguire la propria logica aziendale (ad es. e-mail di conferma) solo dopo il primo messaggio di un determinato stato di pagamento.

CONSIGLIO: Vale la pena di dare un'occhiata a Schema di rinnovo 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à ogni volta uno stato
. IN ATTESA. In un'ulteriore comunicazione ITN, il sistema fornirà lo stato di SUCCESSO o FALLIMENTO.

NOTA Stato IN ATTESA non verrà inviato se:

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

Per una singola transazione (con parametri unici ID ordine e ID remoto) non ci può essere alcun cambiamento di status SUCCESSO su IN ATTESA o SUCCESSO su FALLIMENTO.

In ogni caso, è possibile che si verifichi una modifica dello stato dettagliato -. pagamentoStatoDettagli (I successivi messaggi di modifica dello stato dei dettagli sono solo a scopo informativo e non devono portare alla riconsegna del servizio/prodotto pagato ecc.)

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

a) FALLIMENTO su 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 su FALLIMENTO (ad esempio, dopo l'attivazione di più transazioni con la stessa ID ordinema diverso ID remoto). Un caso del genere si verifica quando il Cliente avvia più pagamenti con lo stesso ID ordine (ad esempio, il Cliente cambia la sua decisione su quale Canale di pagamento vuole pagare per la transazione). Ciascuno dei pagamenti da lui avviati genera ITN e il Partner deve distinguere le singole transazioni sulla base del parametro ID remoto. Al momento della ricezione dello status FALLIMENTO possono essere molto diversi, può accadere che si riceva tale stato dopo aver ricevuto un SUCCESSO (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 e-mail/sms gli stati di non successo, è possibile limitare la quantità di informazioni salvate nel database del servizio e il tracciamento delle modifiche del RemoteID.

Quando è troppo è troppo:

• per gli stati diversi da SUCCESSOogni volta confermare l'ITN con la struttura di risposta corretta, lo stato CONFERMATO e il valore correttamente conteggiato del campo Hash,

• in caso di ricezione di prima stato SUCCESSOaggiungere anche aggiornare lo stato, l'ora e il RemoteID nel database del Servizio e eseguire processi aziendali (notifiche al cliente di un cambiamento di stato, esecuzione di un servizio a pagamento/spedizione di un prodotto, ecc,)

• in caso di stato successivo SUCCESSOogni volta che conferma l'ITN con la struttura di risposta corretta, lo status CONFERMATO e il valore correttamente calcolato 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 è necessaria l'intera cronologia dei cambiamenti di stato delle transazioni e/o la notifica al cliente dei principali cambiamenti di stato delle 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 tramite esso. La trasmissione di tra tutte le parti coinvolte in una transazione avviene tramite una connessione sicura basata sul protocollo TLS con 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). L'impostazione predefinita è SHA256.

Calcolo del valore di una funzione hash

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

NOTE: Gli esempi non tengono conto di tutti i possibili campi opzionali
, pertanto se tali campi sono presenti in un particolare messaggio
, devono essere inclusi nella funzione di scelta rapida nell'ordine del numero accanto al campo.

Calcolo del valore della funzione hash - Campo hash

Il valore della funzione hash, utilizzata per autenticare il messaggio, viene 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 (sotto forma di carattere |) viene inserito tra valori consecutivi (non vuoti). L'ordine in cui i campi sono incollati segue l'ordine in cui essi appaiono nell'elenco dei parametri nella documentazione.

IMPORTANTE! In assenza di un parametro opzionale nel messaggio o nel 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, viene calcolato il valore della funzione hash che costituisce il valore del campo Hash del messaggio.

Hash = function(values_field_1_message + "|" + values_field_2_message + "|" + ... + "|" + values_field_n_message + "|" + key_shared);

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://{host_gates}/pathway

a. Inizio della transazione.

Chiamata POST senza carrello, 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 un cliente torna al Sito del Partner

Dati di servizio dei partner:

ServiceID = 2

chiave_condivisa = 2test2

<https://sklep_nazwa/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": "Wybierz bank, z którego chcesz zlecić płatność",
            "description": null,
            "order": 1,
            "iconUrl": null
        },
        {
            "type": "BNPL",
            "title": "Kup teraz, zapłać później",
            "shortDescription": "Kup teraz, zapłać później",
            "description": null,
            "order": 2,
            "iconUrl": null
        }
    ],
    "serviceID": "10000",
    "messageID": "2ca19ceb5258ce0aa3bc815e80240000",
    "gatewayList": [
        {
            "gatewayID": 106,
            "name": "Płatność testowa PBL",
            "groupType": "PBL",
            "bankName": "NONE",
            "iconURL": "https://testimages.autopay.eu/pomoc/grafika/106.gif",
            "state": "OK",
            "stateDate": "2023-10-03 14:35:01",
            "description": "Płatność testowa",
            "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": "Płacę"
        },
		{
            "gatewayID": 701,
            "name": "Zapłać później z 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>Dane dotyczące kosztu</h1><p>Zapłać później - jednorazowo do 45 dni (...). Szczegóły oferty na: <a href="?r="https://payka.pl\" target=\"_blank\">Payka.pl</a></p></div>",
            "shortDescription": "Zapłać później - jednorazowo do 45 dni lub w kilku równych ratach",
            "descriptionUrl": null,
            "availableFor": "B2C",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": false,
            "minValidityTime": 60,
            "order": 2,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 49.99,
                    "maxAmount": 7000.00
                }
            ],
            "buttonTitle": "Płacę"
        }
    ]
}

Registrazione e funzionamento dei Servizi basati sul Modulo Integratore

Schema di funzionamento per l'aggiunta e la modifica di servizi

Questo capitolo descrive le regole relative allo scambio di messaggi tra l'AP e la Piattaforma Integratore nell'ambito della funzionalità di aggiunta e modifica dei Servizi, che per impostazione predefinita avviene utilizzando l'API REST e opzionalmente utilizzando i Web-Services del protocollo SOAP (il Servizio fornisce la sua definizione sotto forma di un documento WSDL).

Il Partner mette a disposizione un link sulla propria Piattaforma, la cui selezione da parte del Cliente invia un messaggio ad AP per ricevere un link che indirizza al Modulo Integratore predisposto da AP (gli effetti visivi come la combinazione di colori o il logo dell'Integratore sul modulo sono determinati durante l'integrazione).

NOTA È anche possibile incorporare il modulo Integrator preparato da Autopay direttamente nel sito web dell'Integrator (in un Iframe). A tale scopo, il viene utilizzato un elemento HTML chiamato Iframe. L'uso di questo tipo di soluzione comporta un lavoro aggiuntivo da parte dell'integratore, ma consente al partner di rimanere sul sito web dell'integratore durante l'intero processo di registrazione/modifica del negozio. La soluzione è descritta in dettaglio nel capitolo "Il sito web dell'integratore". "Widget per l'onboarding".

I dati raccolti nel modulo (dopo che è stato compilato dal cliente) vengono elaborati da AP, dove, a seconda del tipo di modulo, viene eseguita la registrazione/modifica/aggiunta di un altro servizio. Dopo aver superato con successo questa fase, i dati di configurazione del servizio e i link di verifica (quando si modificano dati non sensibili, i link non appaiono) vengono inviati in modo asincrono all'integratore tramite i canali stabiliti durante l'integrazione. Parallelamente, viene inviata al cliente anche un'e-mail contenente i link al pagamento di verifica (è possibile disattivare questo invio di per sostituirlo con una comunicazione che avviene direttamente tramite il Partner).

A questo punto il cliente viene automaticamente reindirizzato alla pagina di ritorno dell'integratore (l'indirizzo viene determinato durante l'integrazione) o viene presentata una pagina di ringraziamento per l'utilizzo del servizio
, che facoltativamente può includere collegamenti alla verifica del pagamento e/o un collegamento alla piattaforma dell'integratore.

Una volta che il Cliente ha pagato la transazione di verifica, AP controlla la correttezza dei dati dichiarati da quel Cliente durante la registrazione al servizio. Se AP assegna uno stato di verifica positivo, il servizio di pagamento del servizio viene attivato e viene inviato un messaggio al Cliente con i termini e le condizioni accettati da lui/lei nel modulo di registrazione.

IMPORTANTE! La versione di produzione del servizio si trova dietro il firewall. L'accesso è assegnato per un numero finito e definito durante l'integrazione del pool di IP
. Questo non si applica all'ambiente di prova.

IMPORTANTE! Per un singolo Integratore su un determinato ambiente (test/produzione) viene fornito un singolo ID di piattaforma (PlatformID) e una chiave condivisa utilizzata per costruire l'hash per tutti i messaggi scambiati tra l'Integratore e l'AP nell'ambito del processo di registrazione e modifica dei servizi.

IMPORTANTE! Il link generato dall'AP che conduce al modulo per la registrazione/modifica dei dati del servizio ha un tempo di validità predefinito di 24 ore.

IMPORTANTE! Non è consentito condividere in alcuna forma di (anche nel codice in esecuzione su un server di terzi) i dati di autorizzazione per il servizio fornito dall'AP (PlatformID/key condivisi).

IMPORTANTE! Se, al momento della registrazione o della modifica di un negozio, il cliente seleziona diverse valute con cui effettuare i pagamenti nel negozio, ciascuna di queste valute, insieme al conto di fatturazione ad essa assegnato, deve essere verificata separatamente, tramite un trasferimento di verifica.

IMPORTANTE! Sul modulo utilizzato per la modifica dei dati, la verifica dell'identità deve avvenire prima che il su di esso visualizzi i dati attuali del Servizio. A tal fine, al Cliente vengono presentati due canali di verifica: un messaggio sms o un'e-mail. Dopo aver selezionato uno di essi, viene inviato al Cliente un codice di verifica (a tal fine viene utilizzato il numero di telefono o l'indirizzo di posta elettronica fornito dal Cliente durante il processo di registrazione), che deve essere inserito dal Cliente in un ulteriore modulo. Una volta che il di questo campo è stato correttamente compilato e verificato da AP, al Cliente viene concesso l'accesso al modulo di modifica dei dati con tutti i suoi contenuti.

NOTE: In parte Elaborazione di transazioni e regolamenti Vengono descritte le funzionalità di e il modo in cui sono integrate nell'ambito relativo alla gestione dei pagamenti per il Servizio e i servizi relativi alla gestione dei pagamenti, ad esempio lo schema di fatturazione.

I seguenti elementi non sono disponibili nel modello Integrator funzioni della parte transazionale:

a) Dati da scambiare durante l'integrazione

b) Carrello dei prodotti

Dati scambiati durante l'integrazione del Modulo Integratore

Dati scambiati nell'ambiente di test

Dati trasferiti dall'AP al Partner:

• Indirizzo del sistema di pagamento online
• Indirizzo di servizio (indirizzi verso i quali i vari metodi possono essere utilizzati dall'integratore)
• PiattaformaID
• ServiceID (per il servizio Verifica trasferimento crediti)
• Chiave condivisa per la registrazione e il servizio di editing
• Chiave condivisa per il servizio Verifica trasferimento crediti
• Meccanismo di funzione di scelta rapida
• Indirizzo IP da cui vengono inviati gli ITN
• Indirizzo del pannello di amministrazione dell'integratore (opzionale)
• Accesso
• Password

Dati forniti dal Partner all'AP:

• Indirizzo ITN dopo il trasferimento di verifica
• Indirizzo di ritorno dopo il trasferimento di verifica
• Informazioni sulle valute che devono essere disponibili per i negozi dell'integratore
• Informazioni sui canali per l'invio della configurazione del servizio e dei link di verifica
• Indirizzo e-mail dell'integratore per l'invio delle configurazioni del servizio via e-mail
• Indirizzo in cui l'integratore emetterà i servizi per ricevere i messaggi ICN
• Informazioni in caso di modifica del periodo di validità predefinito di un link che porta al modulo di registrazione/modifica dei dati del servizio (default 24 ore)

Dati trasferiti in un ambiente di produzione

Da AP a Partner:

• Indirizzo del sistema di pagamento online
• Indirizzo di servizio (indirizzi verso i quali i vari metodi possono essere utilizzati dall'integratore)
• PiattaformaID
• ServiceID (per il servizio Verifica trasferimento crediti)
• Chiave condivisa per la registrazione e il servizio di editing
• Chiave condivisa per il servizio Verifica trasferimento crediti
• Meccanismo di funzione di scelta rapida
• Indirizzo IP da cui vengono inviati gli ITN
• Indirizzo del pannello di amministrazione dell'integratore (opzionale)
• Accesso
• Password

Da Partner ad AP:

• Indirizzo IP da cui viene effettuata la connessione ai servizi emessi da Autopay
• Indirizzo ITN dopo il trasferimento di verifica
• Indirizzo di ritorno dopo il trasferimento di verifica
• Indirizzi e-mail per i rapporti di fatturazione all'integratore
• Informazioni sulle valute che devono essere disponibili per i negozi dell'integratore
• Informazioni sui canali per l'invio della configurazione del servizio e dei link di verifica
• Indirizzo e-mail dell'integratore per l'invio delle configurazioni del servizio via e-mail
• Indirizzo in cui l'integratore emetterà un servizio per ricevere i messaggi ICN
• Indirizzo presso il quale l'integratore emetterà un servizio per ricevere le notifiche sullo stato della carta (necessario se l'integratore vuole ricevere tali informazioni)
• Informazioni in caso di modifica del periodo di validità predefinito di un link che porta al modulo di registrazione/modifica dei dati del servizio (default 24 ore)

Link per il download di Integrator al modulo Integrator

Lo scambio di messaggi (in formato JSON) tra l'AP e la Piattaforma Integratore, che implementa la funzionalità di download dei link al modulo di registrazione/modifica dei servizi, avviene tramite un'API REST. L'accesso al servizio è protetto dal filtraggio degli indirizzi IP.

Descrizione dei campi inviati nel messaggio di richiesta all'AP

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

Esempio 1: Registrazione del servizio

	{
	   "platformId":1,
	   "messageId":"22111111112411111111111111111130",
	   "messageTime":"2016-07-20T09:35:00.000",
	   "hash":"43688c048e451fba81ea7895cca13c5b6eb953a6ddf23c6089918259163381e1",
	   "formAction":"REGISTRATION",
	   "formParams":{
		  "SERVICE_URL":"https://serivce-integrator-test.pl",
		  "COMMISSION_MODEL":{
			 "PLN":"5"
		  },
		  "IS_CARDS_ENABLED":"TRUE"
	   }
	}

Esempio 2: Modifica dei dati di un servizio con ID = 11111

	{
	   "platformId":1,
	   "messageId":"11111111111111111111111111211254",
	   "messageTime":"2016-07-20T09:35:00.000",
	   "hash":"b16c13f8b2f6e43d583689287aaa8ca87181d037df8083c9d678e34a23983750",
	   "formAction":"UPDATE",
	   "acceptorId":120,
	   "serviceIds":[
		  11111
	   ]
	}

Esempio 3: Modifica dei dati di un servizio con ID = 11111

	{
	   "platformId":1,
	   "messageId":"11111111111111111111111111211254",
	   "messageTime":"2016-07-20T09:35:00.000",
	   "hash":"b16c13f8b2f6e43d583689287aaa8ca87181d037df8083c9d678e34a23983750",
	   "formAction":"UPDATE",
	   "formParams":{
		  "SERVICE_URL":"https://serivce-integrator-test-nowy.pl",
		  "COMMISSION_MODEL":{
			 "PLN":"4"
		  },
	   "acceptorId":120,
	   "serviceIds":[
		  11111
	   ]
	}

Esempio 4: Aggiunta di un altro negozio a un commerciante esistente con ID = 222222

	{
	   "platformId":1,
	   "messageId":"22111111112411111111111111111131",
	   "messageTime":"2016-07-20T09:35:00.000",
	   "hash":"81bc2f50d4284cf4c638c4cf0ca6a07827eccf937152db151979b394a67a863d",
	   "formAction":"ADD_SERVICE",
	   "acceptorId":222222,
	   "formParams":{
		  "SERVICE_URL":"https://serivce-integrator-test.pl",
		  "COMMISSION_MODEL":{
			 "PLN":"5"
		  },
		  "IS_CARDS_ENABLED":"TRUE"
	   }
	}

Esempio 5: registrazione del negozio nel mercato spagnolo.

{
    "platformId":1,
    "messageId":"22111111112411111111111111111131",
    "messageTime":"2016-07-20T09:35:00.000",
    "hash":"81bc2f50d4284cf4c638c4cf0ca6a07827eccf937152db151979b394a67a863d",
    "formAction": "REGISTRATION",
    "formParams": {
        "SERVICE_NAME": "Test ES 13",
        "SERVICE_URL": "https://serivce-integrator-test.pl",
        "ITN_URL": "https://serivce-integrator-test.pl/itn",
        "NUMERIC_TRADE": "58",
        "IS_REFUNDS_ENABLED": "true",
        "RETURN_URL": "https://serivce-integrator-test.pl/return",
        "COMPANY_NAME": "Test ES Company",
        "TAX_ID": "ES04211376N",
        "CITY": "Madrid",
        "COUNTRY": "ES",
        "POSTAL_CODE": "28006",
        "ADDRESS": "Testino 35",
        "IS_CARDS_ENABLED": "true",
        "ACTIVITY_KIND": "FOREIGN",
        "LEGAL_FORM": "AUTONOMO",
        "REGISTRATION_DATE": "2012-01-01",
        "REGISTRATION_COUNTRY": "ES",
        "CONTACT_EMAIL": "test@test.autopay.eu",
        "PHONE": "780171556",
        "NRB": "7720387252204459354426",
        "STATEMENT_DESCRIPTOR": "test shop ES",
        "LANGUAGE": "ES"
    }
}

Descrizione dei campi del messaggio di risposta all'integratore

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

CONSIGLIO: Risposta corretta - stato http 200.

CONSIGLIO: Risposta con messaggio di errore - stato http 400.

Esempio di risposta corretta:

	{
		"link": "https://integrator-form-domain/ e2287514541105a2eda2b85751e88be5998aec8c99cd83ba3073365ce1a243a1",
		"hash": "f9e02e83fe50920ee2efb0d2322b6200a71f3afcc366893487ced7ad2330a610",
		"messageId": "11111111111111111111111111111229",
		"formHash": "e2287514541105a2eda2b85751e88be5998aec8c99cd83ba3073365ce1a243a1"
	}

Esempi di risposte errate:

	{
		"errors": [
			{
				"field": "acceptorId",
				"error": "Value for field acceptorId required!",
				"errorCode": 6003
			}
		]
	}

>

	{
		"errors": [
			{
				"field": "messageTime",
				"error": "Message time is outdated",
				"errorCode": 6016
			}
		]
	}

>

	{
		"errors": [
			{
				"field": "hash",
				"error": "Invalid hash",
				"errorCode": 6000
			}
		]
	}

Codici di errore

Widget di onboarding

Si tratta di un'opzione aggiuntiva offerta da Autopay nel processo di onboarding del negozio, che consente all'integratore di incorporare il modulo direttamente sul sito web dell'integratore. In questa versione della soluzione, il modulo di registrazione/modifica del negozio è ancora preparato e mantenuto sul sito di Autopay, con la differenza che il Partner attraversa l'intero processo mentre si trova sul sito dell'Integratore, evitando il reindirizzamento al dominio di Autopay. Il posizionamento del modulo sul sito dell'integratore avviene tramite un elemento HTML chiamato IFRAME. L'integratore che opta per questo tipo di soluzione dovrà inoltre implementare la funzionalità di ricezione degli eventi inviati dall'iframe di Autopay, necessaria per la corretta visualizzazione del modulo di Onboarding sul sito dell'integratore.

NOTA Autopay consiglia di incorporare il widget di onboarding in un sito dell'integratore il cui sito web sia protetto con un certificato SSL.

NOTA L'indirizzo web del modulo di Onboarding collocato nell'IFRAME sul sito di Integrator è un valore variabile (il parametro formHash nel link cambia), quindi deve essere interrogato prima di ogni visualizzazione della pagina del modulo sul sito di Integrator.

Esempio di codice HTML della pagina che utilizza il widget di onboarding

<!doctype html>
<html lang="pl">
<head>
	<meta charset="utf-8">
	<title>Example usage of Autopay onboarding widget</title>
	<base href="/">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<style>
		body {
			padding: 0;
			margin: 0;
		}
		.container {
			width: 100%;
			padding-left: 15px;
			padding-right: 15px;
			max-width: 1200px;
			margin: 0 auto;
		}
		header {
			padding: 30px 0;
			border-bottom: 1px solid #ccc;
		}
		footer {
			padding: 30px 0;
			border-top: 1px solid #ccc;
		}
		iframe {
			width: 700px;
			border: 0;
		}
	</style>
</head>
<body>
<header>
	<div class="container">
		INTEGRATOR PAGE HEADER
	</div>
</header>
<main>
	<section>
		<div class="container">
			<h1>Example usage of Autopay onboarding widget</h1>
			<p>integrator text before</p>
		</div>
	</section>
	<section>
		<div class="container">
			<iframe id="iframe" src="?r=quot;https://adres-formularza-onboardingowego/form/<formHash>"></iframe>
		</div>
	</section>
	<section>
		<div class="container">
			<p> integrator text after</p>
		</div>
	</section>
</main>
<footer>
	<div class="container">
		INTEGRATOR PAGE FOOTER
	</div>
</footer>
<script type="text/javascript">
	// wait for page to load everything
	document.addEventListener("DOMContentLoaded', function() {
		// create listener for widget events
		window.addEventListener('message', (e) => {
			// if event origin not matches autopay onboarding origin, then event not belongs to widget
			if (!/onboarding\.autopay\.eu$/.test(e.origin) {
				return;
			}
			// if there is no data in event or data is not string, then event is not valid 
			if (!e.data || typeof e.data !== 'string') {
				return;
			}
			let messageData;
			// parse event data string to JSON, if it fails, messageData will remain empty
			try {
				messageData = JSON.parse(e.data)
			} catch (err) {}
			if (!messageData) {
				return;
			}
			// listener for HEIGHT_CHANGE event, thanks to which the iframe window is at full height and the scroll bar is not displayed
			if (messageData.event === 'HEIGHT_CHANGE') {
				document.getElementById('iframe').style.height = messageData.data + 'px'
			}
			// listener for SCROLL_TOP event, which scrolls page to iframe top, because scroll can't happen in full height iframe window
			if (messageData.event === 'SCROLL_TOP') {
				const scrollToPosition = window.scrollY + document.getElementById('iframe').getBoundingClientRect()['y'];
				window.scrollTo({left: 0, top: scrollToPosition, behavior: 'smooth'});
			}
			// listener for FORM_SUCCESS event, which provides necessary data to continue onboarding process
			if (messageData.event === 'FORM_SUCCESS') {
				console.log('Verification links:', messageData.data.verificationLinks)
			}
		})
	})
</script>
</body>
</html>

Ritorno del cliente alla piattaforma dell'integratore

Il reindirizzamento del cliente può avvenire direttamente dopo la corretta registrazione/modifica del negozio o può essere reso disponibile sulla pagina con un ringraziamento sotto forma di link.

Invio dei dati di configurazione del servizio e dei link di verifica (ICN)

Una volta che il cliente ha inviato il modulo e finalizzato il processo di registrazione/modifica, l'AP deve inviare all'integratore i dati di configurazione del servizio e i link di verifica. Ciò può avvenire in diversi modi. I canali di invio vengono concordati con l'integratore durante l'integrazione.

È possibile fornire le informazioni di cui sopra scambiando messaggi tramite tecnologia REST, Web-Services o inviando messaggi via e-mail (sotto forma di file protetto da password).

Ciascuno dei canali di invio ha un proprio sistema di rinnovo in caso di fallimento del tentativo di invio di informazioni all'integratore.

Per motivi di sicurezza, si suggerisce che lo scambio di informazioni sui dati di configurazione venga effettuato utilizzando l'API REST (predefinita) o i Web-Services su un tunnel IPSec compilato o filtrando gli indirizzi IP.

Un campo viene utilizzato per associare un messaggio ICN (ricevuto dall'integratore) a una specifica registrazione del cliente dal modulo. formHashche viene inviato sia nel messaggio ICN sia in risposta alla richiesta di collegamento al modulo
. Ciò garantisce che l'integratore disponga di informazioni per quale registrazione ha ricevuto i dati di configurazione nel messaggio ICN.

Invio di dati di configurazione via REST

Lo scambio di messaggi tra l'AP e il Servizio partner che implementa la funzionalità di aggiunta e modifica dei Servizi partner avviene tramite utilizzando l'API REST. I messaggi vengono inviati in formato JSON.

Descrizione dei campi inviati nel messaggio di richiesta all'Integratore

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

Esempio 1.

	{
	   "acceptorID":11111,
	   "serviceID":22222,
	   "serviceKey":"sa22a2729462f643cf4c989dddcf226b99b3a6bda11db43a433ab31a7ec2abe925",
	   "hash":"580a285b9bf95e60d4eaeb470d32858a5f0191a2a51b40a18ee7612fa9ced187",
	   "verificationLinks ":[
		  {
			 "link":"sampleLink",
			 "currency":"PLN"
		  }
	   ],
	   "panelLogin":"sample panel login",
	   "panelPassword":"sample panel password",
	   "panelAddress":"sample panel address",
	   "formHash":"sample form hash",
	   "method":"REGISTER"
	}

Descrizione dei campi del messaggio di risposta all'AP

	{
		"resultStatus":"OK",
		"description":"sample description"
	}

Invio di dati di configurazione tramite servizi Web

Lo scambio di messaggi tra l'AP e il Servizio partner che esegue la funzionalità di aggiunta e modifica dei Servizi partner avviene utilizzando la tecnologia Web-Services del protocollo SOAP.

Il servizio fornisce la sua definizione sotto forma di un documento WSDL (Web Service Definitions Language), fornito dall'AP durante l' integrazione.

Descrizione dei campi inviati nel messaggio di richiesta all'integratore - InstantConfigurationNotificationRequest

	<xsd:element name="InstantConfigurationNotificationRequest">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:elementname="InstantConfigurationNotification" type="tns: InstantConfigurationNotification "/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

	<xsd:complexType name=" InstantConfigurationNotification ">
		<xsd:sequence>
			<xsd:sequence>
				<xsd:element name="AcceptorID" type="xsd:int"/>
				<xsd:element name="ServiceID" type="xsd:int"/>
				<xsd:element name="ServiceKey" type="xsd:string"/>
				<xsd:element name="Hash" type="xsd:string"/>
				<xsd:element minOccurs="0" name="VerificationLinks" type="tns:VerificationLinks"/>
				<xsd:element minOccurs="0" name="PanelLogin" type="xsd:string"/>
				<xsd:element minOccurs="0" name="PanelPassword" type="xsd:string"/>
				<xsd:element minOccurs="0" name="PanelAddress" type="xsd:string"/>
				<xsd:element name="FormHash" type="xsd:string"/>
				<xsd:element name="Method" type="tns:Method"/>
			</xsd:sequence>
		</xsd:sequence>
	</xsd:complexType>

	<xsd:complexType name="VerificationLink">
		<xsd:sequence>
			<xsd:element name="Currency" type="xsd:string"/>
			<xsd:element name="Link" type="xsd:string"/>
		</xsd:sequence>
	</xsd:complexType>

	<xsd:complexType name="VerificationLinks">
		<xsd:sequence>
			<xsd:element maxOccurs="unbounded" name="VerificationLink" type="tns:VerificationLink"/>
		</xsd:sequence>
	</xsd:complexType>

	<xsd:simpleType name="Method">
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="REGISTER"/>
			<xsd:enumeration value="UPDATE"/>
			<xsd:enumeration value="ADD_SERVICE"/>
		</xsd:restriction>
	</xsd:simpleType>

Descrizione dei campi del messaggio

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

Esempio 1.

	<SOAP-ENV:Envelope
		xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
		<SOAP-ENV:Header/>
		<SOAP-ENV:Body>
			<ns2: InstantConfigurationNotificationRequest
				xmlns:ns2="http://integrator/ws/">
				< InstantConfigurationNotification>
					<AcceptorID>11111</AcceptorID>
					<ServiceID>22222</ServiceID>                
					<ServiceKey>22a2729462f643cf4c989dddcf226b99b3a6bda11db43a433ab31a7ec2abe925</ServiceKey>                
					<Hash>580a285b9bf95e60d4eaeb470d32858a5f0191a2a51b40a18ee7612fa9ced187</Hash>
					<VerificationLinks>
						<VerificationLink>
							<Currency>PLN</Currency>
							<Link>sampleLink</Link>
						</VerificationLink>
					  </VerificationLinks>
					<FormHash>generated_hash</FormHash>
		   <Method>REGISTER</Method>
				</ InstantConfigurationNotification>
			</ns2: InstantConfigurationNotificationRquest>
		</SOAP-ENV:Body>
	</SOAP-ENV:Envelope>

Messaggio di risposta a AP

	<xsd:element name=" InstantConfigurationNotificationResponse">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="Result" type="tns:ResultStatus"/>
				<xsd:element name="Description" type="xsd:string"/>
			 </xsd:sequence>
		</xsd:complexType>
	</xsd:element>

>

	<xsd:simpleType name="ResultStatus">
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="OK"/>
			<xsd:enumeration value="ERROR"/>
		</xsd:restriction>
	</xsd:simpleType>

Descrizione dei campi del messaggio

	<SOAP-ENV:Envelope
		xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
		<SOAP-ENV:Header/>
		<SOAP-ENV:Body>
			<ns2: InstantConfigurationNotificationResponse
				xmlns:ns2="http://integrator/ws/">
				 <Result>OK</Result>
				 <Description>sample description</Description>
			</ns2: InstantConfigurationNotificationResponse>
		</SOAP-ENV:Body>
	</SOAP-ENV:Envelope>

Invio dei dati di configurazione via e-mail

Le informazioni sul servizio vengono inviate all'indirizzo e-mail specificato dall'integratore sotto forma di file protetto da password. Il numero di telefono a cui inviare le password viene concordato con l'integratore durante l'integrazione di
.

Notifica immediata della modifica dei dati AML dopo la verifica nel Sistema di verifica Autopay- ICN

Il sistema Autopay consente all'integratore di essere informato delle modifiche ai dati AML del negozio. In questo modo l'integratore può aggiornare i dati modificati in Autopay e presentarli al partner.

Ciò è stato realizzato inviando messaggi in formato JSON con il metodo HTTP POST. Il corretto funzionamento del servizio richiede l'implementazione di un metodo dal lato dell'integratore per accettare il suddetto messaggio.

Struttura del messaggio

La struttura del messaggio inviato all'integratore è suddivisa in tre nodi principali, come mostrato nella tabella seguente.

Esempio 1. Messaggio con stato di verifica positivo

{ 
   "revisionHeader":{ 
      "orderId":"123_2d87806818cf319d7127ffb", 
      "revisionId":"03d5627b-b9fe-40c0-ae32-5c9620d804ee", 
      "autopayVerificationStatus":"POSITIVE" 
   }, 
   "dataHeader":{ 
      "acceptorId":345, 
      "dataTime":"2024-01-16T 09:16:13", 
      "serviceId":123, 
      "hash":"35a56e960b4a4650b727b098bafd1912cf4e3012c8927ec29b3af6408bc99199" 
   }, 
   "currentData":{ 
      "company":{ 
         "name":"Testowa firma", 
         "address":{ 
            "address":"ul Testowa 77", 
            "postalCode":"80-462", 
            "city":"Gdańsk", 
            "country":"PL", 
            "street":null, 
            "houseNumber":null, 
            "flatNumber":null 
         }, 
         "nip":"8219663675",
         "regon":"955459555", 
         "edg":"123",
         "krs":"1234567890",
         "phone":{ 
            "currentValue":"+48123456789", 
            "waitingValue":null 
         }, 
         "representingPersons":[ 
            { 
               "personName":{ 
                  "firstName":"Jan", 
                  "lastName":"Kowalski" 
               }, 
               "pesel":"PL", 
               "documentData":{ 
                  "number":"BKI332498",
                  "type":"ID", 
                  "expirationDate":"2030-01-01", 
                  "country":"PL" 
               }, 
               "citizenship":"32061970611", 
               "birthData":{ 
                  "date":"1932-06-19", 
                  "country":"PL" 
               } 
            } 
         ],
         "activityKind":"SP_ZOO", 
         "beneficials":[ 
            { 
               "personName":{ 
                  "firstName":"Piotr", 
                  "lastName":"Nowak" 
               },
               "citizenship":"PL", 
               "pesel":"32061970611", 
               "birthDate":"1932-06-19" 
            } 
         ], 
         "registrationDate":"2000-01-01", 
         "plenipotentiary":{ 
            "personName":{ 
               "firstName":"Jan", 
               "lastName":"Kowalski" 
            }, 
            "citizenship":"PL", 
            "birthData":{ 
               "date":"1932-06-19", 
               "country":"PL" 
            }, 
            "pesel":"32061970611", 
            "documentData":{ 
               "number":"BKI332498", 
               "type":"ID", 
               "expirationDate":"2030-01-01", 
               "country":"PL" 
            } 
         }, 
         "physicalPerson":null, 
         "partners":[ 
            { 
               "personName":{ 
                  "firstName":"Jan", 
                  "lastName":"Kowalski" 
               }, 
               "citizenship":"PL", 
               "pesel":"32061970611", 
               "birthData":{ 
                  "date":"1932-06-19", 
                  "country":"PL" 
               }, 
               "documentData":{ 
                  "number":"BKI332498", 
                  "type":"ID", 
                  "expirationDate":"2030-01-01", 
                  "country":"PL" 
               } 
            } 
         ] 
      }, 
      "service":{ 
         "name":"Testowy sklep", 
         "serviceUrl":"https://test.autopay.eu", 
         "urlITN":"https://test.autopay.eu/itn", 
         "returnUrl":"https://test.autopay.eu/return", 
         "trade":{ 
            "id":1, 
            "name":"Alkohol" 
         }, 
         "invoiceEmail":"invoice@test.autopay.eu", 
         "contactEmail":{ 
            "currentValue":"contact@test.autopay.eu", 
            "waitingValue":null 
         },
         "complaintEmail":"complaint@test.autopay.eu", 
         "reportEmail":"report@test.autopay.eu", 
         "balanceDetails":[ 
            { 
               "settlementNRB":"59124053967877760136628953", 
               "currency":"PLN", 
               "swiftCode":null, 
               "commissionModel":2, 
               "regulationId":12 
            } 
         ] 
      } 
   } 
} 

Esempio 2. Messaggio con stato di verifica positivo per un negozio nel mercato spagnolo

{ 
   "revisionHeader":{ 
      "orderId":"123_2d87806818cf319d7127ffb", 
      "revisionId":"03d5627b-b9fe-40c0-ae32-5c9620d804ee", 
      "autopayVerificationStatus":"POSITIVE"      
   }, 
   "dataHeader":{ 
      "acceptorId":345, 
      "dataTime":"2024-01-16T 09:16:13", 
      "serviceId":123, 
      "hash":"35a56e960b4a4650b727b098bafd1912cf4e3012c8927ec29b3af6408bc99199" 
   }, 
   "currentData":{ 
      "company":{ 
         "name":"Test Company", 
         "address":{ 
            "address":"ul Testinio 77", 
            "postalCode":"80-462", 
            "city":"Madrid", 
            "country":"ES", 
            "street":null, 
            "houseNumber":null, 
            "flatNumber":null 
         }, 
         "nip":"1215505438",
         "regon":null, 
         "edg":null,
         "krs":null,
         "phone":{ 
            "currentValue":"123456789", 
            "waitingValue":null 
         }, 
         "representingPersons":[ 
            { 
               "personName":{ 
                  "firstName":"Joan", 
                  "lastName":"Martinez" 
               }, 
               "pesel":null, 
               "documentData":{ 
                  "number":"BKI332498",
                  "type":"ID", 
                  "expirationDate":"2030-01-01", 
                  "country":"ES" 
               }, 
               "citizenship":"ES", 
               "birthData":{ 
                  "date":"1932-06-19", 
                  "country":"ES" 
               } 
            } 
         ],
         "activityKind":"FOREIGN", 
         "beneficials":[ 
            { 
               "personName":{ 
                  "firstName":"Roberto", 
                  "lastName":"Marques" 
               },
               "citizenship":null, 
               "pesel":null, 
               "birthDate":null 
            } 
         ], 
         "registrationDate":"2000-01-01", 
         "plenipotentiary":null, 
         "physicalPerson":null, 
         "partners":[],
         "language":"ES",
         "taxId": "1215505438", 
         "registrationCountry":"ES",
         "legalForm":"AUTONOMO",
         "tradeRegisterName":"NO_REGISTER"         
      }, 
      "service":{ 
         "name":"Test shop", 
         "serviceUrl":"https://test.autopay.eu", 
         "urlITN":"https://test.autopay.eu/itn", 
         "returnUrl":"https://test.autopay.eu/return", 
         "trade":{ 
            "id":1, 
            "name":"Alkohol" 
         }, 
         "invoiceEmail":"invoice@test.autopay.eu", 
         "contactEmail":{ 
            "currentValue":"contact@test.autopay.eu", 
            "waitingValue":null 
         },
         "complaintEmail":"complaint@test.autopay.eu", 
         "reportEmail":"report@test.autopay.eu", 
         "balanceDetails":[ 
            { 
               "settlementNRB":"59124053967877760136628953", 
               "currency":"EUR", 
               "swiftCode":"XXXXXXYY", 
               "commissionModel":2, 
               "regulationId":12 
            } 
         ] 
      } 
      "addons": {
            "service": {
                "statementDescriptor": "shop name"
            }
        }
   } 
} 

Esempio 3. Messaggio con stato di verifica positivo per un negozio nel mercato spagnolo

{ 
   "revisionHeader":{ 
      "orderId":"123_2d87806818cf319d7127ffb", 
      "revisionId":"03d5627b-b9fe-40c0-ae32-5c9620d804ee", 
      "autopayVerificationStatus":"POSITIVE",
      "autopayVerificationStatusReasons": []       
   }, 
   "dataHeader":{ 
      "acceptorId":345, 
      "dataTime":"2024-01-16T 09:16:13", 
      "serviceId":123, 
      "hash":"35a56e960b4a4650b727b098bafd1912cf4e3012c8927ec29b3af6408bc99199" 
   }, 
   "currentData":{ 
      "company":{ 
         "name":"Test Company", 
         "address":{ 
            "address":"ul Testinio 77", 
            "postalCode":"80-462", 
            "city":"Madrid", 
            "country":"ES", 
            "street":null, 
            "houseNumber":null, 
            "flatNumber":null 
         }, 
         "nip":"1215505438",
         "regon":null, 
         "edg":null,
         "krs":null,
         "phone":{ 
            "currentValue":"123456789", 
            "waitingValue":null 
         }, 
         "representingPersons":[ 
            { 
               "personName":{ 
                  "firstName":"Joan", 
                  "lastName":"Martinez" 
               }, 
               "pesel":null, 
               "documentData":{ 
                  "number":"***",
                  "type":"***", 
                  "expirationDate":null, 
                  "country":"***" 
               }, 
               "citizenship":"ES", 
               "birthData":{ 
                  "date":"1932-06-19", 
                  "country":"ES" 
               } 
            } 
         ],
         "activityKind":"FOREIGN", 
         "beneficials":[ 
            { 
               "personName":{ 
                  "firstName":"Roberto", 
                  "lastName":"Marques" 
               },
               "citizenship":null, 
               "pesel":null, 
               "birthDate":null 
            } 
         ], 
         "registrationDate":"2000-01-01", 
         "plenipotentiary":null, 
         "physicalPerson":null, 
         "partners":[],
         "language":"ES",
         "taxId": "1215505438", 
         "registrationCountry":"ES",
         "legalForm":"AUTONOMO",
         "tradeRegisterName":"NO_REGISTER"         
      }, 
      "service":{ 
         "name":"Test shop", 
         "serviceUrl":"https://test.autopay.eu", 
         "urlITN":"https://test.autopay.eu/itn", 
         "returnUrl":"https://test.autopay.eu/return", 
         "trade":{ 
            "id":58, 
            "name":"Usługi medyczne" 
         }, 
         "invoiceEmail":"invoice@test.autopay.eu", 
         "contactEmail":{ 
            "currentValue":"contact@test.autopay.eu", 
            "waitingValue":null 
         },
         "complaintEmail":"complaint@test.autopay.eu", 
         "reportEmail":"report@test.autopay.eu", 
         "balanceDetails":[ 
            { 
               "settlementNRB":"ES1111111111111111111111", 
               "currency":"EUR", 
               "swiftCode":"XXXXXXYY", 
               "commissionModel":2, 
               "regulationId":12 
            } 
         ] 
      } 
      "addons": {
            "service": {
                "statementDescriptor": "shop name"
            }
        }
   } 
}

Descrizione dei campi principali

Valori dei singoli campi a seconda dello scenario

• Dettagli di contatto e verifica

È possibile che alcuni dei dati di contatto richiedano una verifica da parte del cliente. I campi che potrebbero richiedere una verifica sono:

currentData.company.phone 
currentData.service.contactEmail 

Ciascuno di questi campi è rappresentato come un oggetto:

{ 
"currentValue":"wartość", 
"waitingValue":null 
} 

valore corrente - valore attualmente in vigore nel sistema
waitingValue - in attesa di verifica da parte del client. In una situazione in cui il client ha inserito diversi valori senza verificarne nessuno, il campo waitingValue conterrà l'ultimo. Un valore nullo significa che nessun dato è in attesa di verifica da parte del client.

• RevisionHeader

Questo titolo può avere diverse forme:

Completato:

"revisionHeader":{ 
"revisionId":"046b8dcf-3581-4079-813c-34d0a2871fae", 
"autopayVerificationStatus":"PENDING", 
"orderId":"151007_2d87806818cf319d7127ffb" 
} 

Tale intestazione si verifica quando la transazione di verifica di un cliente deve essere pagata durante un'azione avviata dall'integratore.

Ordine vuoto:

"revisionHeader":{ 
"revisionId":"046b8dcf-3581-4079-813c-34d0a2871fae", 
"autopayVerificationStatus":"PENDING", 
"orderId":null 
} 

Questa forma di intestazione si verifica quando l'azione dell'integratore genera una verifica non sensibile, ossia che non richiede il pagamento della transazione di verifica.

Nessun revisionHeader:

"revisionHeader":null 

Il revisionHeader non si verificherà quando una modifica all'interno del servizio/accettante viene inizializzata da Autopay ad esempio come risultato di una verifica periodica dei dati.

• Campo revisionHeader.autopayVerificationStatus

Il campo indica lo stato di verifica della revisione indicata. Valori possibili per questo campo:
IN ATTESA - revisione in corso
POSITIVO - la revisione è stata accettata
NEGATIVO - la revisione è stata respinta
BISOGNO DI UN RISCONTRO - Informazioni/azioni richieste sul lato client

Valore del campo revisionHeader.autopayVerificationStatus indica lo stato di verifica da parte di Autopay e non è legato alla verifica dei dati di contatto effettuata dal cliente.
Valore del campo revisionHeader.autopayVerificationStatus non si applica ai dati del nodo currentData, ma è lo stato della revisione caricata.

Stato di verifica negativo:

"revisionHeader":{ 
      "orderId":"123_2d87806818cf319d7127ffb", 
      "revisionId":"03d5627b-b9fe-40c0-ae32-5c9620d804ee", 
      "autopayVerificationStatus":"NEGATIVE",
      "autopayVerificationStatusReasons": [
            {
                "reason": "ACTIVITY_KIND_INACTIVE",
                "description": "działalność zawieszona"
            },
            {
                "reason": "WRONG_REPRESENTATIVE_BENEFICIARY_DATA",
                "description": "błędne dane reprezentanta/beneficjenta"
            }
        ]       
   }

Tale intestazione può verificarsi se il negozio riceve uno stato di verifica NEGATIVO o NEED_FEEDBACK dopo la verifica da parte di Autopay. L'invio di un nodo aggiuntivo autopayVerificationStatusReasons è facoltativo e dipende dalla configurazione dell'integratore.

• Campo currentData.company.physicalPerson Questo campo viene compilato con l'oggetto sotto riportato quando la registrazione o la modifica riguarda un'attività non registrata, cioè un'azienda. activityKind = NON_ACCOUNTED_ACTIVITY

{ 
   "personName":{ 
      "firstName":"Jan", 
      "lastName":"Kowalski" 
   }, 

   "pesel":"69010583482", 
   "documentData":{ 
      "number":"BKI332498", 
      "type":"ID", 
      "expirationDate":"2030-01-01", 
      "country":"PL" 
   }, 
   "citizenship":"PL", 
   "birthData":{ 
      "date":"1951-06-19", 
      "country":"PL" 
   }
} 

• Campo currentData.company.address
  Il campo dell'indirizzo, a seconda dei dati memorizzati in Autopay, può assumere due forme:

  • indirizzo.indirizzo riempito e indirizzo.via vuoto, indirizzo.numero civico, indirizzo.numero appartamento vuoto
    Esempio:

  "address":{ 
   "address":"ul Testowa 77/3", 
   "postalCode":"80-462", 
   "city":"Gdańsk", 
   "country":"PL", 
   "street":null, 
   "houseNumber":null, 
   "flatNumber":null
  }
  

  • campo vuoto indirizzo.addres e compilato indirizzo.via, indirizzo.numero civico, indirizzo.numero appartamento
    Esempio:

  "address":{ 
   "address":null, 
   "postalCode":"80-462", 
   "city":"Gdańsk", 
   "country":"PL", 
   "street":"ul Testowa", 
   "houseNumber":77, 
   "flatNumber":3 
  }
  

• Campi aggiuntivi

"language":"ES",
"taxId": "1215505438", 
"registrationCountry":"ES",
"legalForm":"AUTONOMO",
"tradeRegisterName":"NO_REGISTER"

Questi sono i campi inviati in caso di integrazione in un mercato diverso da quello polacco.

"statementDescriptor": "shop name"

Un campo che contiene il nome del Punto vendita da visualizzare sugli estratti conto (il servizio di trascrizione del valore di questo campo sugli estratti conto non è attualmente disponibile).

Notifica immediata di una modifica dello stato dei pagamenti con carta (ICN Card)

Il processo di messa a disposizione del negozio delle carte di pagamento richiede la verifica del negozio sia dal lato AP che dal lato dell'amministratore della carta di pagamento, motivo per cui l'avvio della richiede solitamente più tempo dell'attivazione del negozio stesso.

Il sistema consente di inviare una notifica istantanea quando la possibilità di effettuare pagamenti con carte di pagamento in negozio è abilitata o disabilitata, per garantire la coerenza della configurazione del negozio tra la piattaforma integratore e l'AP. Ciò è stato realizzato inviando un messaggio in formato JSON tramite l'API REST.

NOTE: Il corretto funzionamento del servizio richiede l'implementazione sul lato dell'integratore di un metodo per accettare il suddetto messaggio.

Descrizione dei campi del messaggio inviati all'integratore

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

Esempio.

	{
	"serviceId":"1111111",
	"orderId":"22222",
	"cardsStatus":"ACTIVE",
	"hash":"81eb70b8f2c4576bfb375a7ccbfcfb196b235556bcc329aa40a3dc8bfd",
	"currencies":["PLN","EUR","GBP","USD"]
	}

Descrizione dei campi del messaggio di ritorno all'AP

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

Esempio.

	{
	"serviceId":"1111111",
	"orderId":"22222",
	"confirmation":"CONFIRMED",
	"hash":"81eb70bcb8f2c4576bfb375a7ccbfcfb196b2355986556b29aa40a3dc8bfd"
	}

Notifica immediata della modifica per abilitare o disabilitare un canale di pagamento sul negozio (ICN Gateway)

Il sistema consente di inviare una notifica immediata all'integratore quando i canali di pagamento indicati vengono attivati e disattivati in un determinato negozio. Ciò è stato realizzato inviando un messaggio in formato JSON. Il corretto funzionamento del servizio richiede l'implementazione di un metodo da parte dell'integratore per ricevere tale messaggio.

Descrizione del campo del messaggio inviato all'integratore.

NOTE: Se durante l'integrazione con il Partner è stato stabilito un separatore per il conteggio degli hash per i messaggi, questo verrà utilizzato. In questo caso, il conteggio degli hash seguirà lo schema:

Hash = SHA256(messaggio_campo_1_valore + delimitatore + messaggio_campo_2_valore + delimitatore + messaggio_campo_3_valore + delimitatore + [campi consecutivi separati da delimitatore]+ chiave_condivisa)

Esempio:

{
    "serviceId": 111111,
    "gatewayConfigurations": [
        {
            "gatewayId": 101,
            "active": false
        },
        {
            "gatewayId": 100,
            "active": true
        }
    ],
    "orderId": "47781_0a25c3c9-e0a7-4bfa-9bdf-75ca75c2569d",
    "hash": "5f3dfeec2cea228e2f4db8840fdc0e4d91d224da195618c0c67c6a7ea53c1832"
}

Descrizione dei campi del messaggio di ritorno ad Autopay.

Esempio:

Przykład.
{
"serviceId":"1111111",
"orderId":"22222",
"confirmation":"CONFIRMED",
"hash":"81eb70bcb8f2c4576bfb375a7ccbfcfb196b2355986556b29aa40a3dc8bfd"
}

GetAMLCompanyData recuperato dal Service Integrator

GetAMLCompanyDataReq

Messaggio per ottenere i dati del Partner aggiornati nel Sistema.

	<xsd:element name="GetAMLCompanyDataReq">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="AcceptorID" type="xsd:int"/>
				<xsd:element name="Header" type="tns:Header"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Descrizione dei campi del messaggio

	<xsd:complexType name="Header">
		   <xsd:sequence>
				   <xsd:element name="PlatformId" type="xsd:string"/>
				   <xsd:element name="MessageTime" type="xsd:dateTime"/>
				   <xsd:element name="RequestId" type="xsd:long"/>
				   <xsd:element name="Hash" type="xsd:string"/>
			 </xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

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

"GetAMLCompanyDataResp"

Il messaggio è una risposta a GetAMLCompanyDataResp.

	<xsd:element name="GetAMLCompanyDataResp">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="Result" type="xsd:string"/>
				<xsd:element name="ErrorStatus" type="xsd:string" nillable="true"/>
				<xsd:element name="Company" type="tns:Company"/>
				<xsd:element name="isServiceActive" type="xsd:boolean" nillable="true"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Descrizione dei campi del messaggio

CONSIGLIO: Tipo di messaggio Aziendae i suoi singoli componenti
data-deeplation/> sono descritti in dettaglio nella sezione Tipi di composito.

Recuperare informazioni sull'elenco attuale delle normative disponibili - GetLegalData

Il sistema consente all'integratore di recuperare l'elenco completo dei regolamenti corrispondenti alle percentuali di commissione disponibili per l'integratore (CommissionModel) o un elenco specifico di regolamenti limitato dai filtri specificati nei parametri di richiesta. A tale scopo, richiamare il metodo getLegalData (https://domena_BMAutopay/getLegalData) con i parametri appropriati. Lo scambio di messaggi tra Autopay e la piattaforma Integrator avviene in formato JSON. Tutti i parametri vengono passati tramite il metodo POST (Content-Type: application/json). Di seguito è riportato un elenco dei parametri disponibili. L'accesso al servizio è protetto dal filtraggio degli indirizzi IP.

Descrizione dei campi del messaggio di richiesta

Esempio.
Richiesta di un elenco di regolamenti per i tassi di commissione 1 e 2, in polacco e in inglese per la valuta PLN.

{ 
   "header":{ 
      "platformId":"111111", 
      "messageId":22222, 
      "messageTime":"2020-06-01 09:36:00", 
      "hash":"31772235489560079037848456"

   }, 
   "filterParams":{ 
      "commissionmodelList":[ 
         1, 
         2 
      ], 
      "languageList":[ 
         "PL", 
         "EN" 
      ] 
   } 
} 

Descrizione dei campi del messaggio di risposta

Risposta corretta: stato http 200.

Risposta con messaggio di errore - stato http 400.

Esempio.
Restituzione dell'elenco dei regolamenti

{ 
    "regulationList": [ 
        { 
            "commissionModel": 1, 
            "language": "PL", 
            "regulationLink":"https://platnosci-accept.bm.pl/regulations/api/download/4eaf489b-c27f-40ac-b888-032f562077dd", 
            "regulationId": 41,
             "currency": "PLN" 
        }, 
        { 
            "commissionModel": 3, 
            "language": "PL", 
            "regulationLink":"https://platnosci-accept.bm.pl/regulations/api/download/70c5638e-7301-46f9-87e1-522dcff1db4e", 
            "regulationId": 42, 
 	"currency": "PLN" 
        }, 
        { 
            "commissionModel": 6, 
            "language": "PL", 
            "regulationLink":"https://platnosci-accept.bm.pl/regulations/api/download/0ef22461-7245-4501-970f-e09f2929856f", 
            "regulationId": 43, 
	    "currency": "PLN" 
        } 
    ],
    "messageId": "22121111112411112211111311212260", 
    "status": "OK", 
    "hash": "a2bd34888537a5c91c2700f12ec4e59786b03e9d4a92ad9ffd1dc49c8c8edad2" 
} 

Elenco dei codici di errore

Modifica della configurazione del servizio - "UpdateConfiguration"

"UpdateConfigurationReq"

Un messaggio che consente all'integratore di modificare la configurazione del negozio senza dover eseguire un trasferimento di verifica.

	<xsd:element name="UpdateConfigurationReq">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="ServiceID" type="xsd:int" minOccurs="0"/>
				<xsd:element name="Header" type="tns:Header"/>
				<xsd:element name="ConfigurationData" type="tns:ConfigurationData"/>
				<xsd:element name="Currency" type="xsd:string"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Descrizione dei campi del messaggio

	<xsd:complexType name="Header">
		<xsd:sequence>
			<xsd:element name="PlatformId" type="xsd:string"/>
			<xsd:element name="MessageTime" type="xsd:dateTime"/>
			<xsd:element name="RequestId" type="xsd:long"/>
			<xsd:element name="Hash" type="xsd:string"/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

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

	<xsd:complexType name="ConfigurationData">
		<xsd:sequence>
			<xsd:element name="isTransactionRefundAllowed" type="tns:BooleanType" minOccurs="0"/>
			<xsd:element name="CommissionModel" type="xsd:long" nillable="true"/>
			<xsd:element name="isCardsPaymentRequired" type="tns:BooleanType" minOccurs="0"/>
			<xsd:element name="ServiceUrl" type="xsd:string" minOccurs="0"/>
		</xsd:sequence>
	 </xsd:complexType>

Descrizione dei campi del messaggio

NOTE: Dato in ServiceUrl l'indirizzo deve contenere la parte fissa del dominio.
Ad esempio, un cambio di indirizzo: https://nazwasklepu.integrator.pl su https://nazwasklepu.pl

"UpdateConfigurationResp"

Il messaggio è una risposta a UpdateConfigurationReq.

	<xsd:element name="UpdateConfigurationResp">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="Result" type="xsd:string"/>
				<xsd:element name="ErrorStatus" type="xsd:string" nillable="true"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Descrizione dei campi del messaggio

Annullamento dell'edizione corrente del servizio in corso di revisione - "CancelUpdate".

Messaggio utilizzato per annullare la modifica dei dati di un servizio che è attualmente in fase di verifica. Il metodo viene utilizzato quando la configurazione dell'integratore dal lato del sistema Autopay blocca la gestione di più verifiche contemporaneamente per mantenere la coerenza dei dati modificati. Esecuzione corretta Annullamento dell'aggiornamento consente di inviare i dati del modulo per modificare i dati del negozio senza
data-deepl-translation/>attendere lo stato di verifica finale della modifica precedente.

NOTE: I tentativi di recuperare il link del modulo per un sito che è attualmente in fase di verifica si concluderanno con un errore: SHOP_IN_VERIFICATION_STATUS.

AnnullamentoAggiornamentoRichiesta

	<xsd:element name="CancelUpdateReq">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="ServiceID" type="xsd:int" minOccurs="0"/>
				<xsd:element name="AcceptorID" type="xsd:int" minOccurs="0"/>
				<xsd:element name="Header" type="tns:Header"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Descrizione dei campi

AnnullamentoAggiornamentoResp

	<xsd:element name="CancelUpdateResp">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="Result" type="xsd:string"/>
				<xsd:element name="ErrorStatus" type="xsd:string" nillable="true"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Descrizione dei campi

Tipi di composito

Intestazione

Tipo di messaggio per la trasmissione di dati di intestazione relativi alla sicurezza della comunicazione e alla correttezza dei dati trasmessi.

	<xsd:complexType name="Header">
		<xsd:sequence>
			<xsd:element name="PlatformId" type="xsd:string"/>
			<xsd:element name="MessageTime" type="xsd:date"/>
			<xsd:element name="RequestId" type="xsd:long"/>
			<xsd:element name="Hash" type="xsd:string"/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

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

Indirizzo

Questo tipo di messaggio viene utilizzato per trasmettere l'indirizzo dell'entità in questione.

	<xsd:complexType name="Address">
		<xsd:sequence>
			<xsd:element name=”Address” type=”xsd:string/>
			<xsd:element name=”PostalCode” type=”xsd:string/>
			<xsd:element name=”City” type=”xsd:string/>
			<xsd:element name=”Country” type=”xsd:string/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

Tipo NIP

Un tipo che descrive il numero TIN con un limite da 2 a 15 caratteri.

	<xsd:simpleType name="NIPType">
		<xsd:restriction base="xsd:string">
			<xsd:minLength value="2"/>
			<xsd:maxLength value="15"/>
		</xsd:restriction>
	</xsd:simpleType>

Valuta

Tipo che descrive la valuta.

	<xsd:simpleType name="Currency">
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="PLN"/>
			<xsd:enumeration value="EUR"/>
			<xsd:enumeration value="USD"/>
			<xsd:enumeration value="GBP"/>
			<xsd:enumeration value="CZK"/>
		</xsd:restriction>
	</xsd:simpleType>

ForeignTransferModeType

Sistema di trasferimento del regolamento nel caso di un conto estero.

	<xsd:simpleType name="ForeignTransferModeType">
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="SWIFT"/>
			<xsd:enumeration value="SEPA"/>
		</xsd:restriction>
	</xsd:simpleType>

Beneficiari

L'oggetto è un elenco dei tipi di beneficiari reali del Partner.

	<xsd:complexType name="Beneficials">
		<xsd:sequence>
			<xsd:element name="Beneficial" type="tns:Beneficial" minOccurs="0" maxOccurs="2"/>
		</xsd:sequence>
	</xsd:complexType>

Vantaggioso

L'oggetto contiene il tipo di beneficiario effettivo e un possibile elenco di beneficiari di quel tipo.

	<xsd:complexType name="Beneficial">
		<xsd:sequence>
			<xsd:element name="BeneficialType" type="xsd:int"/>
			<xsd:element name="BeneficialOwners" type="tns:BeneficialOwners" minOccurs="0" />
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

Proprietari Beneficiari

Il tipo descrive l'elenco dei beneficiari reali.

	<xsd:complexType name="BeneficialOwners">
		<xsd:sequence>
			<xsd:element name="BeneficialOwner" type="tns:BeneficialOwner" minOccurs="0" maxOccurs="8"/>
		</xsd:sequence>
	</xsd:complexType>

BeneficiarioProprietario

Il tipo descrive i dati di un singolo titolare effettivo.

	<xsd:complexType name="BeneficialOwner">
		<xsd:sequence>
			<xsd:element name="FirstName" type="xsd:string" nillable="false"/>
			<xsd:element name="LastName" type="xsd:string" nillable="false"/>
			<xsd:element name="Citizenship" type="xsd:string"/>
			<xsd:element name="Share" type="xsd:int" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

Plenipotenziario

Tipo di messaggio che descrive il proxy.

	<xsd:complexType name="Plenipotentiary">
		<xsd:sequence>
			<xsd:element name="FirstName" type="xsd:string"/>
			<xsd:element name="LastName" type="xsd:string"/>
			<xsd:element name="Citizenship" type="xsd:string"/>
			<xsd:element name="Pesel" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthCountry" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentType" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Document" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentExpirationDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentCountryId" type="xsd:string" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

Partner

Il tipo descrive l'elenco degli associati.

	<xsd:complexType name="Partners">
		<xsd:sequence>
			<xsd:element name="Partner" type="tns:Partner" minOccurs="0" maxOccurs="7"/>
		</xsd:sequence>
	</xsd:complexType>

Partner

Tipo di messaggio che descrive l'associato.

	<xsd:complexType name="Partners">
		<xsd:sequence>
			<xsd:element name="FirstName" type="xsd:string"/>
			<xsd:element name="LastName" type="xsd:string"/>
			<xsd:element name="Citizenship" type="xsd:string"/>
			<xsd:element name="Pesel" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthCountry" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentType" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Document" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentExpirationDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentCountryId" type="xsd:string" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

Servizio

Tipo di messaggio che descrive il servizio partner.

	<xsd:complexType name="Service">
		<xsd:sequence>
			<xsd:element name="Name" type="xsd:string" nillable="false"/>
			<xsd:element name="ServiceUrl" type="xsd:string" nillable="false"/>
			<xsd:element name="UrlITN" type="xsd:string" nillable="false"/>
			<xsd:element name="ReturnUrl" type="xsd:string" nillable="false"/>
			<xsd:element name="SettlementNRB" type="xsd:string" />
			<xsd:element name="SwiftCode" type="xsd:string" minOccurs="0"/>
			<xsd:element name="ForeignTransferMode" type="tns:ForeignTransferModeType" minOccurs="0"/>
			<xsd:element name="CommissionModel" type="xsd:long" nillable="true"/>
			<xsd:element name="isCardsPaymentRequired" type="xsd:boolean" minOccurs="0" />
			<xsd:element name="AverageServiceTurnover" type="xsd:decimal" minOccurs="0" />
			<xsd:element name="AverageTransactionAmount" type="xsd:decimal" minOccurs="0" />
			<xsd:element name="EconomicPurpose" type="xsd:string" minOccurs="0" />
			<xsd:element name="EconomicPurposeDescription" type="xsd:string" minOccurs="0" />
			<xsd:element name="NumericTrade" type="xsd:int" minOccurs="0" />
			<xsd:element name="InvoiceEmail" type="xsd:string" minOccurs="0" />
			<xsd:element name="ContactEmail" type="xsd:string" minOccurs="0"/>
			<xsd:element name="ComplaintEmail" type="xsd:string" minOccurs="0"/>
			<xsd:element name="ReportEmail" type="xsd:string" minOccurs="0"/>
			<xsd:element name="isTransactionRefundAllowed" type="xsd:boolean" minOccurs="0" />
			<xsd:element name="Currency" type="tns:Currency" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

Azienda

Tipo di messaggio per la trasmissione dei dati del Partner.

	<xsd:complexType name="Company">
		<xsd:sequence>
			<xsd:element name="CompanyRemoteId" type="xsd:string"/>
			<xsd:element name="Name" type="xsd:string"/>
			<xsd:element name="Address" type="tns:Address"/>
			<xsd:element name="Nip" type="tns:NIPType"/>
			<xsd:element name="Krs" type="xsd:string"/>
			<xsd:element name="Phone" type="xsd:string"/>
			<xsd:element name="RepresentingPersonFirstName" type="xsd:string"/>
			<xsd:element name="RepresentingPersonLastName" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPesel" type="xsd:string"/>
			<xsd:element name="RepresentingPersonDateOfBirth" type="xsd:string"/>
			<xsd:element name="RepresentingPersonBirthCountry" type="xsd:string" minOccurs="0"/>
			<xsd:element name="RepresentingPersonCitizenship" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPersonalDocumentType" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPersonalDocument" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPersonalDocumentExpirationDate" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPersonalDocumentCountryId" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Service" type="tns:Service"/>
			<xsd:element name="ActivityKind" type="xsd:string"/>
			<xsd:element name="LegalForm" type="xsd:string" minOccurs="0"/>
			<xsd:element name="PanelAdministrator" type="xsd:string" minOccurs="0" />
			<xsd:element name="isListedOnTheStockExchange" type="tns:BooleanType" />
			<xsd:element name="Beneficials" type="tns:Beneficials" minOccurs="0" />
			<xsd:element name="TradeRegisterName" type="xsd:string" minOccurs="0"/>
			<xsd:element name="RegistrationDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Plenipotentiary" type="tns:Plenipotentiary" minOccurs="0"/>
			<xsd:element name="Partners" type="tns:Partners" minOccurs="0" />
			<xsd:element name="PhysicalPerson" type="tns:PhysicalPerson" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

Persona fisica

Tipo di messaggio utilizzato per trasferire i dati di un individuo. Da compilare quando ActivityKind = NON_ACCOUNTED_ACTIVITY.

	<xsd:complexType name="PhysicalPerson">
		<xsd:sequence>
			<xsd:element name="FirstName" type="xsd:string"/>
			<xsd:element name="LastName" type="xsd:string"/>
			<xsd:element name="Pesel" type="xsd:string"/>
			<xsd:element name="DocumentType" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Document" type="xsd:string"/>
			<xsd:element name="DocumentExpirationDate" type="xsd:string"/>
			<xsd:element name="DocumentCountryId" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Citizenship" type="xsd:string"/>
			<xsd:element name="BirthDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthCountry" type="xsd:string" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Descrizione dei campi del messaggio

Regole per la verifica dei dati dei beneficiari sul modulo

La verifica dei dati riportati sul modulo si basa principalmente sulla forma giuridica dell'azienda. In base ad essa, sono previste le tipologie di beneficiari, le loro reciproche esclusioni e il numero massimo di occorrenze di per ogni tipologia.

Il tipo di beneficiario viene definito nel modulo spuntando dal cliente con la dichiarazione appropriata.

Elenco dei parametri per un trasferimento di crediti di verifica

Il Partner che crea un nuovo conto nel Sistema è tenuto a eseguire un Trasferimento di verifica. Dopo la sua esecuzione, l'AP effettua una valutazione dell'affidabilità del Partner, della correttezza dei suoi dati e della valutazione antiriciclaggio.

Quando il Partner aggiorna i dati, AP si aspetta che venga eseguito un Trasferimento di verifica, solo per i dati sensibili e chiave.

Elenco dei parametri per i quali la registrazione o la modifica dei dati del servizio genererà un link al Trasferimento di verifica.

Nome del campo

• Nome
• Indirizzo
• Email
• Nip
• Krs
• Tipo di attività
• ServiceUrl
• InsediamentoNRB
• Commercio numerico
• Nome del registro commerciale
• Data di registrazione
• Codice Swift
• Nome
• Cognome
• Pesel
• Tipo di documento
• Documento
• Data di scadenza del documento
• PaeseDocumento
• Cittadinanza
• Data di nascita
• Paese di nascita

NOTE: ServiceUrl è trattato come lo stesso se:
a. si differenzia solo per il protocollo (http/https)
b. nel corso dell'integrazione con il Partner, è stata confermata la migrazione dell'indirizzo del sito web da/verso il sottodominio CMS dell'integratore (ad es. przykladowastrona.integrator.pl = przykladowastrona.pl)
c. il componente "www" dell'indirizzo del negozio è stato omesso o aggiunto (ad es. przykladowastrona.pl = www. przykladowastrona.pl)

NOTE: TIN, KRS e forma giuridica sono dati che non possono essere modificati. Se questi dati devono essere modificati, è necessario registrare nuovamente il servizio
.

Collegamento al trasferimento di verifica

Il link al Trasferimento di verifica e tutte le sue notifiche ITN, includono il ServiceID e l'OrderID dedicati costruiti secondo lo schema menzionato durante l'integrazione:

OrderID = ActivationServiceID_UID

Dove:

• AttivazioneServizioID - è il valore ServiceID del servizio verificato
• UID - è una stringa che garantisce l'unicità del Trasferimento di verifica di un determinato Servizio.
• Tutte le comunicazioni (inizio e ritorno della transazione di verifica, nonché tutte le sue notifiche ITN, che forniscono informazioni sullo stato di avanzamento del processo di verifica) sono firmate con la chiave condivisa per il servizio Trasferimento di verifica (anch'essa menzionata durante l'integrazione).

CONSIGLIO: I parametri ITN dedicati al processo di verifica sono descritti nella sezione Campi aggiuntivi nel messaggio ITN/IPN della transazione in entrata. In particolare, i campi di verificaStato e motivi della verifica.

CONSIGLIO: Le possibili transizioni degli stati di pagamento, le verifiche e i relativi dettagli sono inclusi nelle sezioni: Descrizione dettagliata della modifica dello stato di verifica - per una transazione completata correttamente (risultato positivo o negativo), Descrizione dettagliata della modifica dello stato di verifica - per una transazione non completata correttamente.

Registrazione e gestione dei punti di regolamento tra l'AP e la piattaforma del mercato dei partner.

Descrizione del funzionamento del servizio di registrazione automatica e di punti di regolamento

Questo documento descrive le regole relative allo scambio di messaggi tra l'AP e la piattaforma Marketplace del partner nell'ambito della funzionalità di aggiunta dei punti di regolamento (tecnologia REST).

L'Affiliato deve fornire un pulsante sulla sua Piattaforma di mercato, il cui clic da parte del Cliente attiverà un metodo nel sistema AP che genera un link effettivo a un modulo che consente la registrazione di un Punto di regolamento.

Al ricevimento del suddetto link, la Piattaforma Marketplace dovrebbe eseguire un reindirizzamento automatico al modulo presente in questo link.

La compilazione e l'invio dei dati del Negozio da parte del Cliente comporterà la registrazione del Punto di fatturazione nel sistema AP e la restituzione di una pagina di ringraziamento e di un link di verifica online per verificare la correttezza dei dati inseriti. Il link di verifica viene inviato anche all'indirizzo e-mail indicato dal Cliente nel modulo.

Una volta che il Cliente ha effettuato il pagamento di verifica e l'AP ha ricevuto i dati necessari dal Canale di pagamento, il Punto di regolamento riceve uno stato di verifica finale. Il suo valore positivo determina l'attivazione del Punto di Regolamento e la disponibilità a effettuare pagamenti con esso, e verrà inviato un messaggio al Cliente con i termini e le condizioni da lui accettati nel modulo di registrazione.

IMPORTANTE! La versione di produzione del servizio si trova dietro il firewall. L'accesso ad esso è assegnato a un pool di IP finito e definito durante l'integrazione. Questo non vale per l'ambiente di test.

IMPORTANTE! Un ID di piattaforma (MarketplaceID) e una chiave condivisa per il servizio di registrazione sono forniti per una piattaforma Marketplace per ambiente (test/produzione).

IMPORTANTE! Non è consentito rendere disponibili i dati di autorizzazione per il servizio, ovvero MarketplaceID e chiave condivisa, in qualsiasi forma (anche nel codice di un'applicazione in esecuzione su un server di terzi).

Dati da scambiare durante l'integrazione dei servizi del Punto di fatturazione

Dati scambiati nell'ambiente di test

Dati trasferiti in un ambiente di produzione

Procedura per l'aggiunta di punti di regolamento

Descrizione del processo

Lo scambio di messaggi tra l'AP e il servizio partner che implementa la funzionalità di aggiunta dei punti di regolamento avviene tramite la tecnologia REST. Tutti i parametri dei messaggi vengono passati con il metodo POST. Il protocollo è sensibile alle maiuscole e minuscole, sia per i nomi che per i valori dei parametri. I valori dei parametri trasmessi devono essere codificati in UTF-8.

Scarica il link attivo al modulo di registrazione

Dopo che il cliente ha cliccato sul pulsante di registrazione sulla piattaforma Marketplace, il seguente indirizzo verrà inviato a https://adres_usługi/api/marketplace/link deve essere inviata una richiesta per il link corrente al modulo di registrazione. Il messaggio deve essere inviato con l'intestazione Content-Type: application/json e i parametri indicati nella tabella seguente:

Descrizione dei campi del messaggio

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

Esempio di calcolo dell'hash per il seguente messaggio:

	{
	"marketplaceID":1,
	"messageID":"12345678901234567890123456789000",
	"hash":"wartosc_hash"
	}

dove

Hash=SHA256(1|12345678901234567890123456789000|klucz_wspoldzielony) = wartosc_hash

Risposta alla richiesta

In risposta alla richiesta di cui sopra, viene restituito un messaggio (nella stessa sessione HTTP) contenente un link al modulo o, in caso di errore, la sua descrizione insieme all'indicazione del campo interessato.

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

NOTE: Quando la piattaforma Marketplace riceve un link al modulo
, deve essere eseguito un reindirizzamento automatico al modulo.

NOTE: Ogni tentativo di registrazione deve essere preceduto dal download del link al modulo.

NOTE: Il link al modulo è attivo di default per 24 ore (il valore può essere modificato su richiesta del Partner) dopo la sua generazione.

Esempi di messaggi scambiati quando si scarica un link a un modulo

(a) Richiesta elaborata correttamente.

RICHIESTA

	{
	"marketplaceID":1,
	"messageID":"12345678901234567890123456789000",
	"hash":"437c941b5c88b9d0bfa58a1d073d724f55cfed794c1cf9648ba2340c3dcc803f"
	}

RISPOSTA

	{
	"link": "https://adres_usługi/marketplace/ee0e88d81c11b110c1a35a740996453d745dcde0be449686be6ec0777a02be5d",
	"messageID": "12345678901234567890123456789000",
	"hash": "d01e20cc8ab2c3fbe907e805329d915a20058e96f1d6d91a863361444cbd6379"
	}

(b) MessageID è già stato utilizzato, non è unico.

RICHIESTA

	{
	"marketplaceID":1,
	"messageID":"12345678901234567890123456789012",
	"hash":"e43ff5f4b3121d1fd267bd66aaf446b079c28292f2a966e23eb1e8a8c0aaf81a"
	}

RISPOSTA

	{
		"errors": [
			{
				"field": "messageID",
				"error": "messageId not unique"
			}
		]
	}

(c) Il MessageID univoco deve essere di 32 caratteri.

RICHIESTA

	{
	"marketplaceID":1,
	"messageID":"1234567890123456789012345678900022222",
	"hash":"dc8d14b5e3491a700e7f2479f8c196cc0db76f41b2b2ffac1f042a6cad1e5914"
	}

RISPOSTA

	{
		"errors": [
			{
				"field": "messageID",
				"error": "size must be between 32 and 32"
			}
		]
	}

(d) L'hash specificato non è corretto.

RICHIESTA

	{
	"marketplaceID":1,
	"messageID":"12345678901234567890123456789001",
	"hash":"dc8d14b5e3491a700e7f2479f8c196cc0db76f41b2b2ffac1f042a6cad1eaaaa"
	}

RISPOSTA

	{
		"errors": [
			{
				"field": "hash",
				"error": "Invalid hash"
			}
		]
	}

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 le informazioni sull'ordine iniziale).

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 questa operazione transazioneCancellare causa di 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 i termini e le condizioni del servizio di pagamento automatico
data-deepl-translation/> fornito da AP (RecurringAcceptanceState=ACCEPTED, o dopo accordi sul valore aziendale PROMEMORIA/FORZA)

- la scelta di inizializzare un pagamento automatico con un potenziale
data-deepl-translation/> 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 del pagamento automatico secondo la documentazione, modificato dal momento dell'effettivo addebito della carta e dell'instaurazione del pagamento automatico - nel modello di pre-autorizzazione questa operazione transazioneCancellare causa di questi eventi.

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

- canale di pagamento con carta (GatewayID=1503)

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

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

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

Ciascuno di questi metodi per stabilire un blocco dà luogo a un messaggio ITN il cui stato indica il risultato dell'autorizzazione della transazione. Oltre agli stati standard
, in caso di blocco dei fondi, il Sistema può fornire nello stato ITN
paymentStatus=ON_HOLDche costituisce la conferma della creazione di un blocco di fondi sulla carta del Cliente. Inoltre, l'ITN conterrà, per impostazione predefinita, un identificatore globale di transazione (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 stabilito il blocco, il Partner può effettuare un ordine di addebito sulla carta precedentemente autorizzata (cfr. Schema D per la preautorizzazione). In questo caso è necessario richiamare un servizio dedicato. transazioneCancellare (https://{host_gateway}/webapi/transactionClear) con i corrispondenti parametri
. Tutti i parametri sono 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 di 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, insieme ai parametri passati deve essere inviata un'intestazione HTTP definita con un contenuto appropriato. L'intestazione allegata dovrebbe essere denominata 'BmHeader' e avere il seguente 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'esecuzione dell'operazione o la 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 su carta su richiesta del partner

Rilascio del blocco su richiesta del Partner

Una volta stabilito il blocco, il Partner può ordinarne il rilascio (senza detrarre alcun fondo) (Cfr. Schema E per la preautorizzazione). Per questa operazione, utilizzare il servizio releaseHold (Vedi Annullamento di una transazione non pagata). Dopo l'avvio con successo di un lock release (una risposta corretta a una transazione di cancellazione
), il Sistema consegnerà in modo asincrono l'ITN dal paymentStatus=FAILURE e paymentStatusDetails=CANCELLATO.

Sblocco del blocco dopo le transazioni in ritardo

In caso di inattività del Partner (dopo che il blocco è stato stabilito) per un periodo predeterminato di validità della transazione, questa viene rilasciata dal Sistema (senza detrarre alcun fondo) (Rif. Schema F per la preautorizzazione). Il sistema annullerà la transazione, rimuoverà il blocco e fornirà all'ITN l'indirizzo di posta elettronica. paymentStatus=FAILURE e paymentStatusDetails=CANCELLATO.

Schemi di preautorizzazione

Schema A per la preautorizzazione: Impostazione 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 (enrollment della carta)

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 detrarre 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 in base ai parametri inviati

• addebiti al cliente (se non è richiesta un'ulteriore autorizzazione da parte del cliente)

• verificare la correttezza del link di pagamento prima che il cliente venga reindirizzato al sistema - la chiamata convalida i parametri e la configurazione del sistema

• Accorciamento del link di pagamento - invece di diversi parametri, il link viene accorciato a due identificatori

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

• l'uso dell'SDK mobile in una variante mista - l'inizio della transazione viene eseguito dal backend dell'applicazione mobile piuttosto che dall'SDK stesso utilizzando il token di transazione
  

CONSIGLIO: Dettagli sulle varianti dell'SDK in Documentazione SDK.

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

• BLIK 0
  Per poter usufruire di 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 o 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 del sistema.

• Autorizzazioni attraverso i portafogli Google Pay

NOTE: 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 modello Etichetta bianca integrare come descritto e poi fornire il GatewayID=1512 e il token codificato nel parametro Token di pagamento. In assenza di un token (o di un modello diverso dal modello Etichetta bianca) si limita a dichiarare GatewayID=1512 - L'autorizzazione
data-deepl-translation/> avverrà sul sito web del sistema.

• Autorizzazioni attraverso i portafogli Apple Pay
  Per poter usufruire di questo servizio, è necessario fornire GatewayID=1513. L'autorizzazione avverrà sul sito del sistema.

• Autorizzazione attraverso il formato nativo dell'SDK mobile

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

Oltre al GatewayID appropriato - 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 in sezione Avvio di una transazione con parametri aggiuntivi)

Chiamare una pre-transazione

È obbligatorio per le pre-transazioni inviare al backend (utilizzando ad esempio cURL) il messaggio standard di avvio della transazione (cfr. Inizio della transazione), con un'intestazione 'BmHeader' con valori
: 'pay-bm-continue-transaction-url':

Esempio di intestazione

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

Inoltre, si raccomanda che il parametro ClienteIP (per richieste di risarcimento, per scopi 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://{host_bramki}/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 corretta convalida dei parametri (e della configurazione) e di necessità per il cliente di eseguire un'azione aggiuntiva (selezione del canale di pagamento - se specificato GatewayID=0, esecuzione/conferma del trasferimento
, 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://{host_bramki}/payment/continue/96VSD39Z6E/L6CGP5BH
		</redirecturl>
		<orderID>20180824105435</orderID>
		<remoteID>96VSD39Z6E</remoteID>
		<hash>
		1c6eae2127f0c3f81fbed3b6372f128040729a4d4e562fb696c22e0db68dbbe1
		</hash>
	</transaction>

Oggetto pre-transazione

Oggetto transazione rappresenta la ricezione o il prelievo di fondi da un conto 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>Klucz1</blikAMKey>
	<blikAMLabel>Etykieta1</blikAMLabel>
	</blikAM>
	…
	<blikAM>
	<blikAMKey>KluczN</blikAMKey>
	<blikAMLabel>EtykietaN</blikAMLabel>
	</blikAM>

Convalida corretta dei parametri

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

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

Se i parametri (e la configurazione) non sono convalidati correttamente - 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).

NOTE: 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, vale a dire 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 di trasferimento rapido

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

Il trasferimento rapido è un metodo di pagamento che richiede al cliente di riscrivere autonomamente i dati di trasferimento forniti dal sistema. Il tipo di canale di pagamento è indicato dal parametro gatewayType in risposta alla chiamata di servizio "Querying the list of currently available Payment Channels". I dati di trasferimento possono essere visualizzati al cliente:

• sul sito dell'AP (esecuzione della transazione basata sul modello standard di avvio della transazione descritto nella parte Inizio della transazione)

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

Chiamata

Per una corretta trasmissione del messaggio, è necessario inviare al backend un messaggio standard di avvio della transazione (ad esempio cURL), con un'intestazione 'BmHeader' di valore: 'pay-bm' (Per esteso, l'intestazione dovrebbe apparire come questa BmHeader: pay-bm'.). Nel caso di un'intestazione definita in modo errato o mancante, il messaggio verrà letto male. Inoltre, si consiglia di passare il parametro CustomerIP come descritto in IP utente (necessario per i processi di reclamo, segnalazione) e richiesto è per passare un parametro diverso da zero GatewayID (o gatewayType "Trasferimento rapido
".).

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://{host_bramki}/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 eseguire 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. Powstańców 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
.

NOTE: Utilizzare le informazioni di cui sopra per visualizzare i dati del 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 effettuare un pagamento senza inserire un codice BLIK (e senza dover lasciare il sito web). Il suo avvio con successo nel Sistema attiva l'avvio automatico dell'applicazione mobile della banca e la presentazione della transazione all'Utente per la conferma.

Potenziali benefici:

• L'offerta del primo metodo di pagamento comodo e sicuro nel mCommerce che non richiede un numero di carta apre questo segmento a nuovi clienti,

• un'esperienza di acquisto migliore per i clienti, che pagano più velocemente e in modo più comodo,

• Frequenza d'acquisto e valore di vita del cliente - I clienti sono più disposti e più propensi ad acquistare 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 è eliminato,

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

• Il servizio ha la possibilità di coprire l'analisi della fase stessa di effettuazione dei pagamenti
  .

Un prerequisito per rendere disponibile BLIK 0 OneClick al Cliente è l'autorizzazione al Servizio (possedere un account e avervi precedentemente effettuato l'accesso). Se, durante un pagamento BLIK precedentemente effettuato, 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, al momento della conferma del pagamento nell'applicazione mobile
, ha indicato di voler ricordare il negozio, ciò ha avuto l'effetto di collegare in modo permanente (in genere per un periodo di 2 anni) il Cliente del servizio alla sua applicazione, ossia registrando l'Alias UID. L'uso successivo di tale codice comporterà l' autorizzazione della transazione senza il codice.

Chiamare i pagamenti BLIK 0 OneClick

Si consiglia di non forzare il codice BLIK quando si seleziona un canale di pagamento BLIK. È invece opportuno visualizzare il collegamento ipertestuale "Voglio inserire il codice BLIK" sotto il pulsante "Acquista e paga" per consentire l'inserimento del codice al primo tentativo (nel caso in cui il Cliente voglia effettuare un pagamento BLIK da un'applicazione mobile diversa da quella in cui ha precedentemente memorizzato il dato Servizio).

Il servizio dovrebbe eseguire una Pre-transazione, con particolare attenzione a:

• specificando il parametro GatewayID = 509 - indicazione del canale di pagamento BLIK,

• indicazione dei parametri Chiave BlikUID e Etichetta BlikUID - indicazione del richiesto nel BLIK 0 OneClick Alias UID (identificatore utente
  )

• specificando il parametro Codice di autorizzazione - se il cliente ha inserito il codice BLIK,

• specificando il parametro BlikAMKey - se il cliente ha indicato l'etichetta dell'applicazione mobile della banca dall'elenco presentato nel Servizio,

• gestione delle possibili risposte pre-transazione, compresa la gestione di "Response - no follow-up" e degli errori specifici di BLIK 0 OneClick:

(a) un errore in molte applicazioni mobili della banca (conferma=NOTCONFIRMED e motivo=ALIAS_NONUNIQUE) - visualizzare l'elenco delle etichette restituite nella pre-transazione dell'elenco di alias (coppie chiave + etichetta contenute nella struttura dell'oggetto Elenco BlikAML), per recuperare la chiave selezionata e inserirla nel parametro BlikAMKey un altro tentativo di pre-transazione

(b) errori di autorizzazione (conferma=NOTCONFIRMED e motivo di uno dei valori: ALIAS_DECLINATO, ALIAS_NON_TROVATO, BIGLIETTO_ERRATO, BIGLIETTO_SCADUTO, BIGLIETTO_USATO) - visualizzare il campo del codice Blik, per scaricarlo e inserirlo nel parametro Codice di autorizzazione un altro tentativo di pre-transazione

Trasferimenti all'Agenzia delle Entrate

Descrizione

Il sistema consente di effettuare trasferimenti all'Ufficio delle imposte.

Convalida dei titoli di trasferimento all'Ufficio delle imposte

nome del validatore: US_TITLE_VALIDATOR

Title="/TI/______________/OKR/______/SFP/_______/TXT/_________{idtransremote_out}", gdzie:

(a) TI: sta per Taxpayer Identifier (P per PESEL o N per NIP o R per REGON). Ha effetto su:

• Y in NRB (0/1)
• X in NRB, che è un PESEL o un NIP.

(b) OKR: anno, tipo di periodo e numero del periodo per il quale viene effettuato il pagamento dell'imposta

• R - anno in formato a due cifre
• P - semestre
• K - trimestre
• M - mese
• D - decennio
• J - giorno
• 0 (zero) - per i crediti non relativi al periodo contabile

Numero di periodo:

• per i caratteri R 4-7 non vanno compilati
• per P caratteri 4-5 = 01 o 02, caratteri 6-7 non compilati
• per K caratteri 4-5 = 01,02,03 o 04, caratteri 6-7 non compilati
• per M caratteri 4-5 = da 01 a 12, caratteri 6-7 non compilati
• per D caratteri 4-5 = 01, 02 o 03, caratteri 6-7 = da 01 a 12
• per J caratteri 4-5 = da 01 a 31, caratteri 6-7 = da 01 a 12

(c) SFP: simbolo del modulo di pagamento:

d) TXT: testo aggiuntivo (max 29 caratteri)

e) {idtransremote_out} → costante del titolo, che deve trovarsi alla fine della stringa. Non si devono incollare altri valori in questo punto.

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 di un 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.

NOTE: Il servizio richiede la preventiva sottoscrizione di un accordo con l'operatore della carta
. Per maggiori dettagli, contattare il Business Department di Autopay.

Schema di comunicazione

Dopo aver fatto clic su "Paga con Google Pay", sulla pagina del negozio viene visualizzato un modulo Google Pay. In esso, il cliente conferma il proprio account Google e la carta con cui intende pagare (in questa fase, può anche cambiare la carta con un'altra o aggiungerne una nuova). Lo script passa i dati codificati della carta sullo sfondo della tramite la funzione messaggiopoi il negozio deve accettarli e codificarli tramite la funzione base64 e infine inviarli nel parametro Token di pagamento insieme ad 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 sostituiti.

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 deve inviare una richiesta al sistema di pagamento online AP, per recuperare i dati necessari per elaborare 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 presso la struttura 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", sulla pagina del negozio viene visualizzato un modulo Google Pay. In esso il cliente conferma il proprio account Google e la carta con cui intende pagare (in questa fase può anche cambiare la carta con una diversa o aggiungerne una nuova). Uno script in background passa i dati codificati della carta, che il negozio deve accettare e poi codificare con la funzione Base64 e inviare nel parametro Token di pagamento insieme agli altri parametri iniziali della transazione (cioè i dati della transazione del Sistema di pagamento online AP - i dettagli sono descritti nella parte del file Avvio di una transazione con parametri aggiuntivi).

CONSIGLIO: Un esempio completo di integrazione con Google Pay è disponibile all'indirizzo GitHub Autopay.

Informazioni aggiuntive

Per mantenere l'integrità estetica del design utilizzato sul sito web e sull'applicazione mobile di
, utilizzare la guida che fornisce nel documento parti della documentazione per gli sviluppatori delle Linee guida del marchio Google per descrizioni di stile e pulsanti per le pagine web e per parti Tutorial della documentazione per sviluppatori Google, dove troverete le informazioni necessarie per sviluppare un'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, in un dominio registrato con Apple (utilizzando 2 certificati di Apple):

- fino all'inizio della sessione

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

SUGGERIMENTO: safari (il browser del cliente) comunica con l'endpoint di ritorno della sessione (menzionato sopra), dopodiché Apple interroga se stessa per la sessione Autopay.

4. Elaborazione di Apple Pay

• Come parte della registrazione del servizio con Apple, generare il proprio certificato identità del commerciante.
• Generare un certificato elaborazione dei pagamenti sulla base del certificato fornito da AP CSR

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)

Gli affiliati 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) e Visa Mobile inizia (PaywayId 1523)

IMPORTANTE! Il Partner non è autorizzato a memorizzare i dati della Carta (in particolare il numero della carta, il codice di sicurezza CVC, il CVV2), ad eccezione dei parametri trasmessi durante l'elaborazione dei pagamenti automatici da parte di 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 utilizzando il protocollo TLS.

IMPORTANTE! Il partner si impegna a presentare ad 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'SDK Autopay WidgetJS per incorporare e comunicare con il widget Autopay. In breve, si tratta di incorporare l'IFRAME HTML con il widget e 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 stato 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 ottiene l'accesso 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 z 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: "PLN 1,23" è 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'app 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 proprio 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 sono verificati per la coerenza del dominio (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 formato della carta (basata su HTML IFRAME). Quando nel widget vengono inseriti i dati completi e validi della carta, (grazie agli eventi di convalida) viene attivato il pulsante "Paga" sul front-end dell'esercente.

Suggerimento: 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'SDK JS riceve eventi dal widget quando il widget Autopay viene inserito. STATO_DI_VALIDITÀ con valore valido: falso

Una volta ottenuti i dati completi della carta, l'ultimo evento sarà STATO_DI_VALIDITÀ con un valore di 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

Suggerimento: 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 di utilizzare l'addebito della carta nella sua valuta nativa o di lasciare la valuta originale. In questa schermata avviene anche la convalida.

La selezione della valuta del titolare della carta non influisce sull'esercente e sull'importo originale della transazione, ma influisce sull'importo che verrà addebitato alla carta. Se il titolare della carta non desidera utilizzare l'offerta di conversione di valuta DCC, seleziona la valuta originale (in questo caso il PLN).

Ottenere un token

Il pulsante deve essere collegato all'SDK Autopay Widget JS, in modo che il clic su di esso attivi una chiamata al metodo widget.sendForm(); nella struttura WidgetConnection Che alla fine si tradurrà in un evento MODULO_INTERROTTOcioè ottenere il valore del paymentToken (nel campo messaggio).

{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) Inoltrare al front-end i dati di configurazione che avviano l'incorporazione del widget.
• (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) Iniziare con l'inserimento dei dati della carta da parte del titolare della carta.
• (3) Trasmissione dei dati della carta utilizzando una connessione TLS protetta da un certificato Extended Validation al backend di CardsAutopay ** ** Si applica solo se è possibile proporre la DCC ** ** (3a) Restituzione dei dettagli della proposta di conversione valutaria DCC ** (3b) Il titolare della carta decide, se vuole utilizzare la DCC ** (3c) Trasmissione dei dati della carta precedentemente inseriti dal titolare della carta e segue la decisione della DCC
• (4) WidgetJS riceve da CardsAutopay e invia al front-end dell'esercente (tramite JS) il valore dell'opzione paymentToken
• (5) Il Merchant Front riceve il token di pagamento dal Widget tramite un evento JavaScript.
• (6) Il Merchant Front trasferisce il token di pagamento al Merchant Backend.
• (7) Avvio del backend Pre-transazione con paymentToken ricevuto in precedenza dal fronte
• (8) L'API Autopay restituisce l'URL il proseguimento della transazione che sarà usato per reindirizzare all'inizio della transazione con l'utente
• (9) Il backend del commerciante passa un URL di reindirizzamento al frontend del commerciante.
• (10) Reindirizzamento del titolare della carta dal sito web dell'esercente a PayAutopay per l'autenticazione del 3DS.
• Viene effettuata 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 un risultato di addebito
• (13) Lo stato della transazione viene comunicato al sistema di pagamento online (in background).
• (14) Il titolare della carta viene reindirizzato dal sito web di PayAutopay (dopo l'autenticazione 3DS). al sito web del commerciante
• (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 riceve anche un messaggio supplementare RPAN )

Widget Visa Mobile - Esempio di implementazione su un sito web partner

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 status MODULO_INTERROTTOcome contiene nel campo 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 luogo in cui viene collocato l'IFRAME HTML, in cui verrà inserito l'indirizzo del widget (visamobile o scheda standard, a seconda delle necessità)
• 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 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'Autopay Widget JS SDK riceve eventi dal widget STATO_DI_VALIDITÀ con valore valido: falso Una volta ottenuto il numero di telefono completo, l'ultimo evento sarà STATO_DI_VALIDITÀ con un valore di 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 clic su di esso attivi una chiamata al metodo widget.sendForm(); nella struttura WidgetConnection Che alla fine si tradurrà in un evento MODULO_INTERROTTOcioè ottenere il 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

Inizio della transazione:

• (1) Iniziate inserendo il vostro numero di telefono nel widget VisaMobile.
• (2) Lancio delle transazioni VisaMobile
• (3) Rimborso da parte di VisaMobile
• (4) Ritornare dal widget a Merchant (usando JS) il file generato paymentToken
• (5) Il Merchant Front trasferisce il token di pagamento al Merchant Backend.
• (6) Avvio del backend Pre-transazione con paymentToken ilToken di pagamento precedentemente ricevuto
• (7) Il ritorno riceve immediatamente una risposta XML PENDING (perché viene elaborata in background).
• (8) Sul fronte Mercante, viene presentata la schermata di attesa dei risultati

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 dal paywall.
• (9b) Il sistema CardsAutopay invia una richiesta di cancellazione a Visa.
• (9c) Il sistema CardsAutopay riceve un risultato di cancellazione da Visa.
• (9d) Il risultato della cancellazione viene accettato dal sistema PayAutopay e presentato all'utente sul paywall PayAutopay.
• (9e) Viene inviato un parallelo ITN (con stato negativo) a Merchant

Carica e restituisce il risultato:

• (10) Attesa dei dati del token di pagamento da Visa (se un cliente VisaMobile conferma nell'app mobile di voler pagare con una carta specifica per un determinato ordine)
• (11) Segue un ordine di addebito
• (12) Riceviamo un risultato di carico 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 un messaggio di conferma. ITN

Discussione 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>/* pominięte w przykladzie */</style>
</head>
<body>
<div>
  <form onsubmit="submitForm(event)" novalidate>
   <div class="form-group"><p>Transaction amount:</p><span>1,23 PLN</span></div>

    <!-- przykładowa implementacja mechanizmu wyboru kanału płatności po stronie merchanta -->
    <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>

    <!-- miejsce, w które wstrzyknięty zostanie HTML IFRAME z widget"em -->
    <div class="form-group" id="iframe-wrapper">
      <iframe id="iframe"></iframe>
    </div>

    <!-- przycisk wywołujący akcję w widget'cie -->
    <button type="submit" id="button" disabled="disabled">PayButton</button>
  </form>
</div>
<script type="text/javascript">
window.addEventListener('load', () => {
    // pomocnicze zmienne (tylko na potrzeby przykładu)
    var currentPayway = null;
    var widget = null;

    // przykładowe konfiguracje zależne od środowiska devloperskiego (tylko na potrzeby przykładu)
	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;

    // pomocnicza metoda obsługująca wybór kanału płatności i osadzenie widget'u
    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
        }
    }

    // pomocnicza metoda (tylko na potrzeby przykładu) ustawiająca obramowanie na wybranym kanale płatności
    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');
    }

    // główna metoda odpowiadająca za osadzenie IFRAME z widget'em i zestawienia komunikacji między nim a jego obiektowym reprezentantem 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(() => {

            // obsłużenie głównego, finalnego event'u zawierającego wartość PaymentToken'a
            widget.on(widgetEvents.formSuccess, function (message, eventData) {
                console.log('payment token event =>', eventData);
                console.log('payment token value:', message);
                // w tym miejscu powinno być wywołanie API merchanta, aby przekazać paymentToken (message) do backend'u merchanta;    <<<<<<<<<<<<<<<<<
            })

            // obsłużenie event'ów związanych z walidacją podczas wprowadzania danych w widget'cie przez użytkownika/cardholder'a
            widget.on(widgetEvents.validityStatus, function (message, eventData) {
                console.log('form validation status =>', eventData);
                if (eventData.valid) {
                    enableSubmitButton();
                } else {
                    disableSubmitButton();
                }
            })

            // obsłużenie event'u związanego z walidacją w momencie wprowadzania danych w widget'cie przez użytkownika/cardholder'a
            widget.on(widgetEvents.validationResult, function (message, eventData) {
                console.log('form validation result =>', eventData);
                if (eventData.valid) {
                    enableSubmitButton();
                } else {
                    disableSubmitButton();
                }
            })

            // obsłużenie event'u showModal
            widget.on(widgetEvents.showModal, function () {
                console.log('show modal');
            })
        })
    }

    // pomocnicza metoda (tylko na potrzeby przykładu) ustawiająca usuwanie widget'u dla innych, niż kartowe, kanałów płatnosći (w przykladzie jest kanał 106 PBL)
    function removeWidget () {
        if (!widget) {
            return;
        }
        widget.stopConnection();
    }

    // pomocnicza metoda (tylko na potrzeby przykładu)
    function enableSubmitButton () {
        document.getElementById('button').removeAttribute('disabled');
    }

    // pomocnicza metoda (tylko na potrzeby przykładu)
    function disableSubmitButton () {
        document.getElementById('button').setAttribute('disabled', 'disabled');
    }

    // pomocnicza metoda (tylko na potrzeby przykładu) powiązująca naćiśnięcie aktywnego przycisku zapłać z wywołaniem sendForm() w obiekcie widget'u
    function submitForm (event) {
        event.preventDefault();
        if (!widget || widget.invalid) {
            return;
        }
        disableSubmitButton();
        widget.sendForm();
    }

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

Pagamento con carta incorporata nel servizio (iFrame)

L'iFrame della carta (PayBmCheckout) non è più supportato, invece, per il pagamento con carta incorporata nel sito del partner, usare Widget della scheda.

Pagamento automatico

Descrizione del pagamento automatico

I pagamenti automatici sono un modo estremamente comodo e sicuro per effettuare transazioni ricorrenti. Consiste nella riscossione automatica dei crediti da parte del cliente alle date di pagamento. Il servizio deve essere prima attivato. Nel caso delle carte, ciò avviene tramite reindirizzamento del cliente al modulo di attivazione del servizio. Per BLIK
, invece, accettando un pagamento automatico nell'applicazione mobile
. Una volta autorizzata con successo tale transazione di attivazione, l'AP trasmette al Partner un messaggio standard di modifica dello stato della transazione (ITN) e un messaggio di attivazione del servizio di pagamento automatico (RPAN). Il messaggio RPAN contiene il campo clientHashche il Partner identificherà il pagamento automatico specifico durante gli addebiti successivi e la disattivazione del servizio.

Tutte le transazioni all'interno del ciclo di vita di un pagamento automatizzato (attivazione e addebiti) vengono elaborate all'interno di canali di pagamento dedicati (BLIK - GatewayID=522, Carte - GatewayID = 1503) o gatewayType="Pagamento automatico".. Quando si integrano i pagamenti automatici BLIK, è possibile specificare (nei dati forniti prima dell'integrazione) la durata dei pagamenti automatici attivati (illimitata per impostazione predefinita) o specificarla nell'operazione di inizializzazione (parametro Tempo di validità ricorrente).

Attivazione del pagamento automatico

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

Si tratta di attivare il servizio di pagamento automatico durante il pagamento di un servizio/bene (così 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 esteso dal nodo
Dati ricorrentie - per i pagamenti con carta - Dati scheda).

Messaggio di avvio della transazione automatica

Il processo di attivazione del servizio viene avviato dal sito del partner mediante l'avvio della transazione con il parametro Azione ricorrente consente di controllare il comportamento di del sistema:

(a) il valore di INIT_WITH_PAYMENT - corrisponde all'attivazione del servizio di pagamento automatico al momento del pagamento di un servizio/bene (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 pagamenti automatici (a meno che non sia stato selezionato un canale di pagamento nel Servizio),

(b) il valore di INIT_WITH_REFUND - corrisponde all'attivazione del servizio di pagamento automatico al di fuori del processo di pagamento del servizio/merce (l'addebito sulla carta o sul conto viene effettuato con l'importo di 1 PLN, seguito dal ritorno automatico dei fondi sul conto del Cliente); nell'elenco dei canali di pagamento disponibili, il Sistema presenta solo i pagamenti automatici (se non è stato selezionato alcun canale di pagamento sul Sito web),

(c) il valore di INIT_SENZA_PAGAMENTO - corrisponde all'attivazione del servizio di pagamento automatico al di fuori del processo di pagamento del servizio/bene; valore supportato solo nel modello White-Label, per il metodo BLIK. L'importo iniziale per questo valore è 0,00.

d) nessun parametro (o vuoto) - a meno che non sia stato selezionato un canale di pagamento sul Servizio, il Sistema visualizzerà tutti i canali di pagamento disponibili per il Servizio (compresi quelli automatici) e lascerà al Cliente la decisione: pagamento unico o avvio di un pagamento automatico.

NOTE: 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) sono richiesti anche i parametri Stato di accettazione ricorrente (con un valore di ACCETTATOil che significa che il Cliente ha letto e accettato i termini e le condizioni del pagamento automatico sul Sito Partner) e RecurringAcceptanceID.

L'attivazione del servizio di carta di pagamento automatico viene effettuata sui formati 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 avviene senza specificare i dati della carta: ad esempio con il codice BLIK (trasportato nei parametri iniziali in AuthorisationCode), o tramite BLIK OneClick Alias (trasportato nei parametri iniziali in BlikUIDKey/BlikUIDLabel). I pagamenti automatici per il metodo BLIK possono essere avviati in due varianti:

1. Modello M - con conferma di ogni pagamento da parte del cliente sull'app mobile della banca (canale 522),
2. Modello O - senza conferma del pagamento in banca (canale 524). In questo modello, la certificazione del Merchant Service secondo la procedura descritta in: https://blik.com/lp/reccuring-payments/BLIK-Recurring-Payments---Certification-Checklist.141951091.html

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à durante i successivi addebiti e disattivazioni del servizio. Il RPAN contiene anche informazioni sull'azione per il 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.

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 ciascuno dei pagamenti automatici attivati 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) è usato per autenticare il del documento. Il valore di questo elemento è calcolato come valore della funzione hash da una stringa contenente i valori concatenati di tutti i campi del documento e la chiave condivisa allegata. Per una descrizione di come viene calcolato l'hash
, vedere la sezione Sicurezza delle transazioni.

Risposta alla notifica

La risposta di notifica prevede uno stato HTTP di 200 (OK) e un testo in formato XML (non codificato Base64), restituito dal Partner Service 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

Elemento conferma è utilizzato per comunicare lo stato della verifica dell'autenticità della transazione da parte del Servizio partner. Il valore dell'elemento è determinato dalla verifica della correttezza del valore del parametro. serviceID, un confronto tra i valori dei campi ID ordine i importo nel messaggio di notifica e nel messaggio di avvio della transazione, oltre a verificare che l'hash calcolato dai parametri del messaggio corrisponda al 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: Elemento hash (in risposta a un messaggio) è usato per autenticare la risposta ed è calcolato a partire dai valori dei parametri della risposta. Per una descrizione di come viene calcolato il digest, fare riferimento alla 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 periodo di tempo specificato. Il servizio del Partner deve eseguire la propria logica di business (ad esempio, lanciare un servizio di pagamento automatico, spedire ecc. ClientHash.

Schema di riproduzione 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).

NOTE: La ripetizione continua dell'identico messaggio da parte del Sistema indica una risposta mancante o errata da parte del Servizio e richiede da parte del Partner per una diagnosi urgente della causa.

Caricamento 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 i pagamenti una tantum. È esteso solo dal nodo RecurringData e (per i pagamenti con carta) CardData.

Messaggio di avvio della transazione di pagamento automatizzata

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

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

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

NOTE: La partecipazione del cliente all'opzione MANUALE, di solito, si limita a richiamare un messaggio (selezionando nel Servizio l'opzione di pagamento con la carta memorizzata). Nella maggior parte dei casi, è necessaria un'ulteriore autorizzazione in banca (sotto forma di codice 3DS o CVC). In tal caso, invece di un addebito (e dello stato dell'ordine in risposta a una pre-traduzione), il sistema restituirà un link per proseguire - questo è il comportamento predefinito del sistema nell'ambiente di test
. Per testare uno scenario di carico senza la necessità di autorizzazioni aggiuntive, è necessario dichiarare la necessità di modificare la configurazione del Sistema per la durata del test.

NOTE: 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 del e in un messaggio RPDN (dedicato agli eventi di cancellazione del servizio di pagamento automatico).

Può anche accadere che l'annullamento del servizio sia avviato da parte dell'AP (ad esempio su richiesta del cliente, della banca o dell'organizzazione della carta). In questo caso, il sistema invierà anche un messaggio RPDN.

Messaggio di disattivazione del pagamento automatico

Il servizio può essere disattivato tramite un messaggio dedicato. Tutti i parametri di vengono passati tramite il metodo POST (al file https://{host_gateway}/disattiva_ricorrenti). 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
.

NOTE: 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, viene restituito un testo formattato in XML nella stessa sessione HTTP
, contenente una conferma.

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

Elemento conferma è utilizzato per comunicare lo stato di verifica dell'autenticità dell'operazione da parte del Servizio. Il valore dell'elemento viene determinato verificando la correttezza dei valori dei parametri. serviceID e clientHash con quelli specificati nel messaggio RPAN all'inizio di un determinato pagamento di attivazione, oltre a verificare che l'hash calcolato dai parametri del messaggio corrisponda al valore passato 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 corretti o Hash mismatch - operazione non autentica;

NOTE: 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 ClientHash, viene inviato un messaggio dedicato sotto forma di documento XML, è tramite protocollo HTTPS (porta predefinita 443), utilizzando il metodo POST, con un parametro denominato ricorrente. Questo parametro è memorizzato utilizzando il meccanismo di codifica del 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 ciascuno dei pagamenti ciclici disattivati sono identici ai valori dei campi corrispondenti forniti 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.

NOTE: 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.

Conferma della ricezione del messaggio

La risposta alla notifica prevede lo stato HTTP 200 (OKq) e un testo in formato XML (non codificato Base64), restituito dal Servizio nella stessa sessione HTTP, contenente la conferma della 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

Elemento conferma è utilizzato per comunicare lo stato di verifica dell'autenticità dell'operazione da parte del Servizio. Il valore dell'elemento viene determinato verificando la correttezza dei valori dei parametri. serviceID e clientHash con quelli specificati nel messaggio RPAN all'inizio di un determinato pagamento di inizializzazione e verifica che l'hash calcolato dai parametri del messaggio corrisponda al valore passato 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 hash mismatch - operazione non autentica

NOTE: L'elemento hash (nel messaggio di risposta) è utilizzato per l'autenticazione della 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 hash di tutti i campi del documento (senza tag
) e la chiave condivisa inclusa. Per una descrizione di come calcola l'hash, vedere la sezione Sicurezza delle transazioni.

Se non c'è una risposta corretta alle notifiche inviate, il Sistema farà un altro tentativo di comunicazione dopo un certo tempo. Il Servizio deve eseguire la propria logica aziendale (ad esempio, interrompere il pagamento automatico, l'invio di posta elettronica, ecc.

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

Verifica dell'identità del pagatore

Descrizione della verifica dell'identità del pagatore

La verifica dell'identità del pagatore può essere effettuata sulla base del confronto tra i dati forniti per la verifica nei parametri iniziali della transazione e i dati ottenuti dal pagamento registrato nel Sistema.

I campi del messaggio di avvio della transazione associati a un servizio (descrizione nella sezione Avvio di una transazione con parametri aggiuntivi):

• Nome della verifica,

• Nome della verifica,

• VerificaStreet,

• VerificaStreetHouseNo,

• VerificaStradaSala n,

• VerificaStreetPremiseNo,

• VerificaCodice postale,

• VerificaCittà,

• VerificaNRB

I campi del messaggio ITN associati al servizio (descritti nella sezione Campi aggiuntivi nel messaggio ITN/IPN della transazione in entrata):

• nodo clienteDati

• verificaStato

• nodo motivi della verifica

CONSIGLIO: Istruzioni dettagliate su come interpretare gli stati dei pagamenti e delle verifiche di in questo processo sono contenute nella sezione Campi aggiuntivi nel messaggio ITN/IPN della transazione in entrata.

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

Nodo elenco prodotti deve contenere almeno 1 elemento prodotto, ogni nodo prodotto devono contenere ciascuno un elemento di subImporto i params.

Elemento subImporto deve contenere un importo di prodotto positivo (il separatore decimale è un punto seguito da due cifre da un centesimo). La somma degli importi dei prodotti consecutivi deve essere uguale all'importo indicato nel parametro Importo (l'importo della transazione).

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

Parametri dell'elemento

Elemento params possono essere utilizzati per comunicare 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="Nazwa produktu 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="Nazwa produktu 1" />
		</params>

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

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

• Se il Partner utilizza una struttura estesa (più punti di fatturazione), è tenuto a trasmettere in ogni prodotto l'identificativo del punto di fatturazione (parametro denominato idBalancePoint con tipo integer{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 sono effettuati a livello di prodotto/punto di regolamento (cioè vengono effettuati tanti trasferimenti di regolamento dopo il deposito quanti sono i prodotti nel paniere), e

  • non sono stati impostati dati di fatturazione fissi (o non sono stati impostati tutti i dati di fatturazione 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 di viene stabilito l'utilizzo di conti non polacchi, allora il campo trasferisce IBAN e l'intervallo di dati previsto per il campo cambia in: caratteri alfanumerici latini (min. 15, max. 32 caratteri). Specificando valori in formato IBAN sarà necessario specificare nel prodotto anche i parametri swiftCode, foreignTransferMode.

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

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

Esempio di applicazione dei parametri a un prodotto:

	<params>
		<param name="customerNRB" value="83109010980000000107285707" />
		<param name="title" value="Rozliczenie produktu X" />
		<param name="receiverName" value="Jan Kowalski" />
	</params>

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

Esempio di parametri del carrello:

	<params>
		<param name="idBalancePoint" value="12456" />
		<param name="productName" value="Zasilenie salda dla Autopay" />
	</params>

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

Se durante la discussione del carrello prodotti è stato stabilito che il suo riepilogo deve essere visualizzato nella pagina del Sistema (la schermata di selezione del Canale di pagamento), è possibile specificare le etichette di ogni parametro utilizzato nel carrello. Il sistema può utilizzare l'etichetta predefinita del parametro oppure può accettarla all'inizio della transazione.

Il valore dell'attributo titolo sarà visualizzato prima del valore del parametro prodotto.

Esempio di attributo title

	<params>
		<param name="productName" value="Nazwa produktu 1" title="Nazwa"/>
		<param name="productType" value="ABCD" title="Typ"/>
	</params>

Opzioni di comunicazione online aggiuntive per il partner

Campi aggiuntivi nel messaggio ITN/IPN della transazione in entrata

Descrizione

La notifica immediata di una modifica dello stato di una transazione può contenere campi aggiuntivi (cfr. Schemi di preautorizzazione). La loro presenza è una questione di configurazione di
, determinata durante l'integrazione (per impostazione predefinita, solo il nodo viene inviato
. clienteDati).

Il fatto che si tratti di un messaggio ITN o IPN è determinato unicamente 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.

NOTE: Per il conteggio dei valori di Hash, vengono presi gli attributi valore altri nodi prodotto.params.

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 di pagamento (campo Stato del pagamento) una descrizione dettagliata dello stato (campo pagamentoStatoDettagli). Questa descrizione va considerata come informativa, l'elenco dei valori ammessi è in continua crescita e la comparsa di nuovi valori non può comportare 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 della 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 (estesa solo dal nodo prodotto simile a quello descritto nel capitolo Campi aggiuntivi nel messaggio ITN/IPN della transazione in entrata, integrato solo dalla ripetizione dell'importo subImporto in params). Esempio di IPN nella sottosezione Campi aggiuntivi nel messaggio ITN/IPN della transazione in entrata).

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 durante la determinazione dei requisiti.

Se la comunicazione ISTN viene attivata con successo, il Sistema trasmette immediatamente le notifiche relative all'ordine dell'operazione di regolamento (eventuali prelievi/restituzioni) e alla modifica del suo stato.

https://sklep_nazwa/odbior_informacji_o_rozliczeniu

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 tramite il metodo POST, come parametro HTTP denominato transazioni. Questo parametro è memorizzato utilizzando il meccanismo di codifica di trasporto 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 di 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>

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

Per questo elemento sono previsti due valori:

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

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

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

CONSIGLIO: Vale la pena di dare un'occhiata a Schema di riproduzione 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 lo stato SUCCESSOTuttavia, è possibile una notifica più precisa
. L'opzione completa deve essere notificata durante l'integrazione e comporta il seguente schema di transizioni di stato.

Un ordine per una transazione di regolamento invia uno stato IN ATTESA. In seguito, il sistema fornirà SUCCESSO o FALLIMENTO. Per le transazioni per le quali si è verificato lo status SUCCESSOnon dovrebbe più esserci un cambio di stato in FALLIMENTO. È tuttavia possibile che si verifichi una modifica dello stato di dettaglio (i successivi messaggi di modifica dello stato di dettaglio sono solo informativi e non devono comportare la riesecuzione della 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 a IN ATTESA e di nuovo a SUCCESSO.

Un altro caso particolare può essere lo stato di FALLIMENTO (ad esempio dopo un errore interno del sistema
), poi sostituito dallo stato dell'elemento SUCCESSO.

Servizi aggiuntivi

Interrogazione dell'elenco dei canali di pagamento attualmente disponibili

Descrizione

Per costruire una vista di selezione dei metodi di pagamento nel servizio, il sistema consente di interrogare da remoto l'elenco corrente dei canali di pagamento. Per farlo, chiamare il metodo gatewayList (https://{host_gateway}/gatewayList/v3) con parametri corrispondenti (in formato JSON). Tutti i parametri sono trasmessi utilizzando la tecnologia REST. Il protocollo è sensibile alle maiuscole sia nei nomi dei parametri che nei valori. 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.

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": "Przelew internetowy",
            "shortDescription": "Wybierz bank, z którego chcesz zlecić płatność",
            "description": null,
            "order": 1,
            "iconUrl": null
        },
        {
            "type": "FR",
            "title": "Dane do przelewu",
            "shortDescription": "Zleć przelew wykorzystując podane dane",
            "description": null,
            "order": 2,
            "iconUrl": null
        },
        {
            "type": "BNPL",
            "title": "Kup teraz, zapłać później",
            "shortDescription": "Kup teraz, zapłać później",
            "description": null,
            "order": 3,
            "iconUrl": null
        }
    ],
    "serviceID": "10000",
    "messageID": "2ca19ceb5258ce0aa3bc815e80240000",
    "gatewayList": [
        {
            "gatewayID": 106,
            "name": "Płatność testowa PBL",
            "groupType": "PBL",
            "bankName": "NONE",
            "iconURL": "https://testimages.autopay.eu/pomoc/grafika/106.gif",
            "state": "OK",
            "stateDate": "2023-10-03 14:35:01",
            "description": "Płatność testowa",
            "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": "Płacę"
        },
        {
            "gatewayID": 9,
            "name": "Przelew z innego banku",
            "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>Szybki przelew</b>",
            "shortDescription": "Szybki przelew",
            "descriptionUrl": null,
            "availableFor": "BOTH",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": true,
            "minValidityTime": null,
            "order": 2,
            "currencies": [
                {
                    "currency": "PLN"
                }
            ],
            "buttonTitle": "Wygeneruj dane do przelewu"
        },
		{
            "id": 701,
            "name": "Zapłać później z 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>Dane dotyczące kosztu</h1><p>Zapłać później - jednorazowo do 45 dni (...). Szczegóły oferty na: <a href="?r="https://payka.pl\" target=\"_blank\">Payka.pl</a></p></div>",
            "shortDescription": "Zapłać później - jednorazowo do 45 dni lub w kilku równych ratach",
            "descriptionUrl": null,
            "availableFor": "B2C",
            "requiredParams": [],
            "mcc": null,
            "inBalanceAllowed": false,
            "minValidityTime": 60,
            "order": 3,
            "currencies": [
                {
                    "currency": "PLN",
                    "minAmount": 49.99,
                    "maxAmount": 7000.00
                }
            ],
            "buttonTitle": "Płacę"
        }
    ]
}

NOTE: Il risultato dell'interrogazione del metodo deve essere salvato e aggiornato ogni minuto per verificare la disponibilità del canale. gatewayList nel servizio partner. Una risposta non valida deve essere considerata come una risposta vuota, un timeout o un elenco di nodi vuoto. gatewayGruppi o gatewayList.

Richiesta di un elenco delle autorizzazioni formali attualmente disponibili

Descrizione

Descrizione di un'integrazione che consente l'utilizzo di una lista di pagamento incorporata in un servizio (o in un'applicazione mobile), senza fasi di transizione. In alcuni casi, invece di una fase di transizione, il comportamento standard del sistema prevede il blocco dell'inizio della transazione.

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

Il sistema consente di interrogare a distanza l'elenco corrente degli obblighi e dei relativi contenuti formali. A questo scopo, il metodo dati legali (https://{host_gates}/legalData) con i corrispondenti parametri (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
, la sua posizione nel Servizio, l'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\nZapoznałem się i akceptuję <a id=\"regulations_pdf\" target=\"_blank\" href=https://{host_bramki}/path?params>Regulamin świadczenia usług płatniczych</a> oraz <a class=\"privacy-policy\" href=\"https://{host_bramki}/polityka-prywatnosci.pdf\" target=\"_blank\">Politykę prywatności</a></li><li>\r\nChcę aby usługa została zrealizowana niezwłocznie, a w przypadku odstąpienia od umowy, wiem, że nie otrzymam zwrotu poniesionych kosztów za usługi zrealizowane na moje żądanie do chwili odstąpienia od umowy\r\n</li></ul>",
						"placement": "ABOVE_BUTTON",
						"showCheckbox": true,
						"checkboxRequired": true
					}
				]
			},
			{
				"regulationID": 1,
				"type": "PRIVACY",
				"labelList": [
					{
						"labelID": 1,
						"inputLabel": "Autopay korzysta z plików cookie. Pozostając na tej stronie, wyrażasz zgodę na korzystanie z plików cookie zgodnie z <a class=\"privacy-policy\" href="?r="https://{host_bramki}/polityka-prywatnosci.pdf\" target=\"_blank\">Polityką prywatności Autopay S.A. </a> Możesz samodzielnie zarządzać cookies zmieniając odpowiednio ustawienia swojej przeglądarki lub oprogramowania urządzenia."
						"placement": "BOTTOM_OF_PAGE",
						"showCheckbox": false,
						"checkboxRequired": false
					}
				]
			}
		],
		"hash": "61789013d932e2bc728d6206f7e9222b93e3176f7f07f6aa8cce1ccd65afaf0d",
		"result": "OK",
		"errorStatus": null,
		"description": null
	}

Descrizione della gestione della risposta

Poiché i requisiti formali per il contenuto delle clausole, la loro disposizione e il metodo di accettazione dipendono dal canale di pagamento utilizzato, questo metodo deve essere richiamato ogni volta che viene selezionato (da qui l'obbligatorietà del parametro dell'elemento 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, per rendere l'applicazione veloce, è gradito 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 inserendo nel messaggio di inizio il parametro start del suo identificativo (e quindi il corrispondente valore del parametro regolamentoID).

A seconda del valore del campo tipo regolamenti:

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

a. al parametro DefaultRegulationAcceptanceID dovrebbe andare il suo valore
regolamentoID;

b. al parametro Stato di accettazione della regolamentazione predefinita dovrebbe andare valore ACCETTATO e

c. al parametro Tempo di accettazione del regolamento predefinito deve premere il valore corrispondente al momento dell'accettazione del consenso spuntando la casella e cliccando sul pulsante "Avvia pagamento".

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

a. al parametro RecurringAcceptanceID dovrebbe raggiungere il suo valore regolamentoID;

b. al parametro Stato di accettazione ricorrente dovrebbe raggiungere il valore di ACCETTATO e

c. al parametro Tempo di accettazione ricorrente deve premere il valore corrispondente al momento dell'accettazione del consenso spuntando la casella di controllo e cliccando sul pulsante "Inizia il pagamento".

NOTE: Campi (ad es. serviceModel, url, labelID) e i valori dei campi (ad es. PSD2, RODO, PRIVACY) metodi dati legali non sono necessari per la gestione di
, ma occorre prevedere che si verifichino nella risposta di a una richiesta.

Richiesta di saldo

Descrizione

Per tutti i servizi, è possibile interrogare il saldo corrente. Per questo, il metodo deve essere chiamato. balanceGet https://{host_gates}/webapi/balanceGet 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 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 in formato XML (nella stessa sessione HTTP), contenente una conferma dell'operazione per 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 operazioni di accredito del saldo su futuri rimborsi. A tal fine, è necessario eseguire un avvio di transazione con il parametro Modalità di transazione o valori NESSUNO e Importo indicando l'importo della ricarica.

L'uso di Pre-transazioni consentirà la semplice consegna della transazione conclusa al pagatore (ad esempio, fornendo l'indirizzo dell'ufficio contabile del partner in CustomerEmail).

NOTE: Il servizio deve essere concordato con il custode aziendale. Nel modello Marketplace, sarà inoltre necessario costruire un paniere di prodotti indicando quale BalancePointID deve essere alimentato.

Prelievi dal saldo

Descrizione

Per i servizi che hanno un saldo nel Sistema, è possibile eseguire operazioni di prelievo di tutto o parte del saldo sul conto definito per i regolamenti. A tal fine è necessario richiamare il metodo saldoPagamento (https://{host_gates}/settlementapi/balancePayoff) con i corrispondenti 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 dovrebbero 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.

NOTE: Richiesto uno dei campi ID servizio o Punto di equilibrioID.
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 verifica iniziale rispetto ai campi e ai 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.

NOTE: 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
.

NOTE: Tutte le risposte diverse da quella ipotizzata (cioè con campi non corretti, in particolare campi vuoti o non corretti) sono state inserite in un file di testo. hash). Nel caso in cui il sistema autorizzi il mittente del messaggio di ritorno ma l'operazione fallisca, la risposta seguirà lo schema descritto nella sezione Messaggi di errore. In caso di errore di comunicazione o di saldo insufficiente (ad esempio ON_DEMAND_ERROR), l'ordine può essere rinnovato. 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.

Restituzione delle transazioni

Descrizione

Per i servizi che presentano un saldo nel Sistema, è possibile effettuare operazioni 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 tentativo ripetuto di ordinare il rimborso della stessa transazione, il Sistema restituisce un errore opportunamente descritto). Le restituzioni di parte dell'importo di una transazione possono essere effettuate più volte, purché il loro totale non superi l'importo del deposito.

Per eseguire la restituzione di una transazione, richiamare il metodo transazioneRimborso (https://{host_gates}/settlementapi/transactionRefund) 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

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 effettuare rimborsi per le transazioni pagate è possibile fino a 12 mesi indietro, contando dalla data in cui la transazione è stata avviata. 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.

Queste scadenze si applicano all'elaborazione dei resi tramite il pannello di amministrazione e il pannello di amministrazione
. transazioneRimborsoad esempio tramite gli strumenti amministrativi di
. 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. In altre parole, il Sistema accetta l'ordine e lo elabora in modo asincrono entro un massimo di 30 minuti; in caso di fallimento, l'informazione sull'operazione conclusasi con un errore viene inviata in un report il giorno lavorativo successivo.

In caso di problemi di connessione, che superino il tempo massimo di risposta, la richiesta può essere ripetuta con lo stesso MessageID senza temere una richiesta duplicata. Tutte le risposte diverse da quella ipotizzata (ovvero con campi non validi, in particolare vuoti o non validi 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 con un saldo nel Sistema e che specificano dei prodotti nel carrello, il parametro ID prodottoè possibile eseguire l'operazione di restituzione al Cliente dell'intero o di parte dell'importo pagato per il prodotto indicato. La restituzione dell'intero importo del prodotto può essere effettuata una sola volta (in caso di ripetuti tentativi di ordinare la restituzione dello stesso prodotto, il Sistema restituisce un errore opportunamente descritto). La restituzione di parte dell'importo del prodotto può essere effettuata su esso più volte, purché la loro somma non superi l'importo pagato al prodotto.

Per eseguire una restituzione di prodotto, richiamare il metodo prodottoRimborso (https://{host_gates}/settlementapi/productRefund) con i corrispondenti parametri
. Tutti i parametri sono 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 di 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 (nella stessa sessione HTTP) un testo in formato XML, contenente una conferma dell'operazione o una descrizione dell'errore (descritto di seguito).

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 effettuare rimborsi per le transazioni pagate è possibile fino a 12 mesi indietro, contando dalla data in cui la transazione è stata avviata. 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.

Queste scadenze si applicano all'elaborazione dei resi tramite il pannello di amministrazione e il pannello di amministrazione
. prodottoRimborsoad esempio tramite i propri strumenti di amministrazione
. 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. In altre parole, il Sistema accetta l'ordine e lo elabora in modo asincrono entro un massimo di 30 minuti; in caso di fallimento, l'informazione sull'operazione conclusasi con un errore viene inviata in un report il giorno lavorativo successivo.

In caso di problemi di connessione, che superino il tempo massimo di risposta, la richiesta può essere ripetuta con lo stesso MessageID senza temere una richiesta duplicata. Tutte le risposte diverse da quella ipotizzata (ovvero con campi non validi, in particolare vuoti o non validi hash). Se il sistema autorizza il mittente del messaggio di ritorno
, ma l'operazione non riesce, viene restituito in risposta un messaggio di errore (vedere. Messaggi 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 in quale stato si trova la transazione di regolamento e quale identificativo le è stato assegnato dal Sistema di pagamento online. A tal fine, richiamare il metodo dettagli (https://{host_gates}/settlementapi/outDetails) con i corrispondenti 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 dovrebbero 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.

NOTE: Richiesto uno dei campi ID servizio o Punto di equilibrioID.
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 tale scopo, il Partner può creare collegamenti di attivazione con i parametri pertinenti del metodo
. conferma (https://{host_gates}/web/conferma/pagamento). Tutti i parametri vengono passati con il metodo GET. Il protocollo è sensibile alle maiuscole e alle minuscole sia nei nomi che nei valori dei parametri. 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 parametri corretti comporterà la visualizzazione di un riepilogo della transazione (con contenuti che dipendono dal suo stato) o l'informazione della sua assenza (se il Sistema non la trova).

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

NOTE: Il servizio deve essere attivato previo accordo con il mentore aziendale. È possibile modificare il contenuto dei messaggi o adattarne il layout (questi sono soggetti a un accordo in forma operativa durante l'integrazione).

Richiesta di informazioni sullo stato di una transazione

Descrizione

Per tutti i servizi, è possibile interrogare lo stato della transazione. Per questo, il metodo dovrebbe essere chiamato Stato della transazione (https://{host_gateway}/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 dovrebbero 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.