API > POST /build/finalize_payment

POST/build/finalize_payment

PROD

https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/finalize_payment

TEST

https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/build/finalize_payment

Concludi un pagamento utilizzando la soluzione XPay Build.

PARAM HEADER

NOME

DESCRIZIONE

FORMATO

Correlation-Id	Campo obbligatorio nel formato UUID v4. Lo scopo di questo campo è tracciare la richiesta su diversi sistemi, semplificando il debug e il monitoraggio delle richieste.	String Formato: uuid Esempio: 123e4567-e89b-12d3-a456-426614174000
Language	Parametro dell'intestazione della lingua	String Default: ITA
X-Api-Key	Chiave API di autenticazione.	String Formato: uuid Esempio: 625b4884-38f8-11ed-a261-0242ac120002

PARAM PATH

NOME

DESCRIZIONE

FORMATO

No param path

PARAM QUERY

NOME

DESCRIZIONE

FORMATO

No param query

PARAM BODY

sessionRequest

NOME

DESCRIZIONE

FORMATO

sessionId

Identificatore di sessione.

String

RESPONSE 200

Richiesta elaborata con successo Gli stati restituiti possono essere: * PAYMENT_COMPLETE: significa che il flusso di pagamento è giunto al termine, con successo o fallimento. Il campo operazione descrive in dettaglio l'esito del pagamento. * REDIRECTED_TO_EXTERNAL_DOMAIN: è necessario per eseguire l'autenticazione dell'utente su un dominio esterno. Ciò può accadere per una contestazione 3DS di un pagamento con carta o per qualsiasi pagamento effettuato con metodi di pagamento alternativi. In ogni caso, il browser dell'utente verrà reindirizzato all'url indicata nel campo 'url'. - Nessun header per questa risposta

BODY

NOME

DESCRIZIONE

FORMATO

fieldSet

Oggetto contenente gli iframe per la scelta delle modalità di pagamento o per la raccolta dei dati della carta.

Object

fields

Elenco dei campi da visualizzare nella pagina di checkout.

Array

class	Classe del campo, valori possibili: -APM - CARTA	String Esempio: cardData
id	Identificatore del campo.	String Esempio: cardholderName
src	URL iframe dedicato al metodo di pagamento.	String Esempio: https:///field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264
type	Tipo di campo, valori possibili: - AZIONE: campo che richiede un'azione da parte del titolare della carta sull'iframe, in questo caso il click sul componente.	String Esempio: text

securityToken

Token di sicurezza utilizzato dal commerciante per convalidare la fonte of the notification.

String
Esempio: f3b2c1d4e5a6b7c8d9e0f1a2b3c4d5e6

sessionId

Identificatore di sessione.

String
Esempio: sessionId

sriHash

Hash SRI per l'SDK JavaScript XPay Build.

String

state

Indica il flusso adottato per il pagamento in corso. I valori possibili sono:
- SELEZIONE_METODO_PAGAMENTO
-CARD_DATA_COLLECTION
- PRONTO_PER_PAGAMENTO
- REDIRECTED_TO_EXTERNAL_DOMAIN
- PAGAMENTO_COMPLETO

String
Esempio: CARD_DATA_COLLECTION

url

URL per il reindirizzamento al dominio esterno.
Questo parametro\ \ viene restituito se il parametro "state" è impostato su "REDIRECTED_TO_EXTERNAL_DOMAIN"\ .

String
Esempio: https://anyurl.it

warnings

Elenco degli avvisi relativi all'operazione di pagamento.

Array

		code	Codice di avviso.	String Esempio: TRA001
		description	Descrizione dell'avviso.	String Esempio: 3DS warning

operation

Oggetto contenente i dettagli di un'operazione di pagamento.

Object

additionalData

Mappa dei campi aggiuntivi specifici per il metodo di pagamento scelto

Object

cancelledOperationId

L'operazione deve essere annullata

String

channel

Indica il canale di origine:
* ECOMMERCE: il titolare della carta ha avviato l'operazione attraverso un canale online.
* POS: il titolare della carta ha avviato l'operazione tramite un POS fisico.
* BACKOFFICE: operazione avviata dal commerciante. Comprende le operazioni postali e il MIT.

String
Esempio: ECOMMERCE

customerInfo

Oggetto contenente il dettaglio del cliente. L'invio del contenuto di questo oggetto aumenta il livello di sicurezza della transazione, aumentando quindi la probabilità che nel pagamento non venga richiesta l'autenticazione a due fattori.

Object

billingAddress

Oggetto contenente il dettaglio dell'indirizzo del cliente.

Object

additionalInfo	Informazioni aggiuntive sull'indirizzo, ad esempio il piano. Lunghezza massima consigliata: 50 caratteri.	String Esempio: Quinto Piano, Scala B
city	Città. Lunghezza massima consigliata: 40 caratteri.	String Esempio: Bologna
country	Stato nel codice ISO 3166-1 alpha-3. Lunghezza massima consigliata: 3 caratteri.	String Esempio: ITA
name	Nome e cognome. Lunghezza massima consigliata: 50 caratteri.	String Esempio: Mario Rossi
postCode	Codice Postale. Lunghezza massima consigliata: 16 caratteri.	String Esempio: 40124
province	Codice della provincia. Lunghezza massima consigliata: 3 caratteri.	String Esempio: BO
street	Indirizzo completo. Lunghezza massima consigliata: 50 caratteri.	String Esempio: Piazza Maggiore, 1

cardHolderAcctInfo

Oggetto contenente informazioni sull'account dell'acquirente.

Object

chAccAgeIndicator	Indicatore dell'età dell'account sul sito del commerciante: 01 = Nessun conto 02 = Creato durante questa transazione 03 = Creato negli ultimi 30 giorni 04 = Creato tra 30 e 60 giorni fa 05 = Creato prima di 60 giorni fa	String Esempio: 01
chAccChangeDate	Data dell'ultima variazione dell'account sul sito web del commerciante, incluso indirizzo di fatturazione o spedizione, nuovo account di pagamento o nuovi utenti aggiunti.	String Esempio: 2019-02-11T00:00:00.000+0000
chAccChangeIndicator	Tempo trascorso dall'ultima modifica alle informazioni dell'account dell'acquirente sul sito del commerciante, incluso l'indirizzo di fatturazione o di spedizione, il nuovo account di pagamento o l'aggiunta di nuovi utenti. 01 = Creato durante questa transazione 02 = Creato negli ultimi 30 giorni 03 = Creato tra 30 e 60 giorni fa 04 = Creato prima di 60 giorni fa	String Esempio: 01
chAccDate	Data di attivazione dell'account sul sito web del commerciante.	String Esempio: 2019-02-11T00:00:00.000+0000
chAccPwChangeDate	Data dell'ultima modifica della password dell'account (inclusa la reimpostazione della password).	String Esempio: 2019-02-11T00:00:00.000+0000
chAccPwChangeIndicator	Tempo trascorso da quando l'account dell'acquirente ha eseguito una modifica della password o un ripristino dell'account: 01 = Nessun conto 02 = Creato durante questa transazione 03 = Negli ultimi 30 giorni 04 = Tra 30 e 60 giorni fa 05 = Prima di 60 giorni fa	String Esempio: 01
destinationAddressUsageDate	Data dell'ultimo utilizzo di questo indirizzo di consegna.	String Esempio: 2019-02-11T00:00:00.000+0000
destinationAddressUsageIndicator	Indica quando è stato utilizzato per la prima volta l'indirizzo di spedizione utilizzato per questa transazione: 01 = Creato durante questa transazione 02 = Creato negli ultimi 30 giorni 03 = Creato tra 30 e 60 giorni fa 04 = Creato prima di 60 giorni fa	String Esempio: 01
destinationNameIndicator	Indica se il nome associato all'account corrisponde al nome indicato per la spedizione: 01 = Nome account identico al nome dell'indirizzo di spedizione. 02 = Nome account diverso dal nome dell'indirizzo di spedizione	String Esempio: 01
nbPurchaseAccount	Numero di acquisti di questo account negli ultimi 6 mesi.	Integer Esempio: 0
paymentAccAgeDate	Data di attivazione del conto di pagamento.	String Esempio: 2019-02-11T00:00:00.000+0000
paymentAccIndicator	Indica quando l'acquirente ha inserito il Conto di pagamento sul sito del commerciante: 01 = Nessun conto 02 = creato durante questa transazione 03 = Creato negli ultimi 30 giorni 04 = Creato tra 30 e 60 giorni fa 05 = Creato prima di 60 giorni fa	String Esempio: 0
provisionAttemptsDay	Numero di tentativi di aggiungere una nuova carta nelle ultime 24 ore.	Integer Esempio: 0
suspiciousAccActivity	Indica se il commerciante ha rilevato attività sospette (incluse frodi precedenti) sul conto dell'acquirente: 01 = Nessuna attività sospetta verificata. 02 = Rilevata attività sospetta	String Esempio: 01
txnActivityDay	Numero di transazioni (riuscite e abbandonate) per questo account nelle 24 ore precedenti.	Integer Esempio: 0
txnActivityYear	Numero di transazioni (riuscite e abbandonate) per questo conto nell'anno precedente.	Integer Esempio: 0

cardHolderEmail

E-mail del titolare della carta.
Lunghezza massima consigliata: 255 caratteri.

String
Esempio: mauro.morandi@nexi.it

cardHolderName

Nome e cognome del titolare della carta.
Lunghezza massima consigliata: 255 caratteri.

String
Esempio: Mauro Morandi

homePhone

Numero di telefono di casa fornito dal titolare della carta.
Lunghezza massima consigliata: 18 caratteri.

String
Esempio: 391231234567

merchantRiskIndicator

Oggetto contenente informazioni relative all'acquisto effettuato.

Object

deliveryEmail

In caso di acquisto di prodotti virtuali/digitali: indirizzo email a cui viene inviato il prodotto.

String
Esempio: john.doe@email.com

deliveryTimeframe

Indicatore sul periodo di consegna della merce:
01 = Consegna immediata (prodotti virtuali/digitali).
02 = Consegna lo stesso giorno.
03 = Consegna notturna.
04 = Consegna in due o più giorni

String
Esempio: 01

giftCardAmount

Oggetto contenente l'importo totale e la valuta delle carte prepagate o gift card acquistate.

Object

		currency	Per l'acquisto di carte prepagate o regalo, il codice valuta della carta come definito nella norma ISO 4217. EMVCO: GiftCardCurr	String Esempio: EUR
		value	Per l'acquisto di carte prepagate o regalo, l'importo totale dell'acquisto di carte prepagate o regalo in unità principali (ad esempio, 123,45 USD è 123). EMVCO: importo della carta regalo	String Lunghezza max: 18 Esempio: 100

giftCardCount

Numero totale di carte/codici individuali prepagati o regalo acquistati.

Integer
Esempio: 0

preOrderDate

Per un acquisto preordinato, la data prevista in cui la merce sarà disponibile.

String
Esempio: 2019-02-11T00:00:00.000+0000

preOrderPurchaseIndicator

Indica se l'acquirente sta effettuando un ordine per merce con disponibilità futura:
01 = Merci disponibili.
02 = Disponibilità futura.

String
Esempio: 01

reorderItemsIndicator

Indica se il titolare della carta sta riordinando la merce acquistata in precedenza:
01 = Primo ordine.
02 = Merce già acquistata in precedenza.

String
Esempio: 01

shipIndicator

Indicatore sul tipo di consegna:
01 = Spedizione all'indirizzo di fatturazione.
02 = Spedizione ad un altro indirizzo verificato dal commerciante.
03 = Consegna ad un indirizzo diverso da quello di fatturazione.
04 = Spedizione o ritiro presso il negozio (nell'oggetto "destinationAddress" deve essere indicato l'indirizzo del negozio).
05 = Beni virtuali/digitali, compresi servizi online, buoni regalo elettronici, codici di recupero.
06 = Biglietti di viaggio ed eventi (non inviati).
07 = Altro: ad esempio giochi, servizi digitali non inviati, abbonamenti a media elettronici

String
Esempio: 01

mobilePhone

Telefono cellulare.
Lunghezza massima consigliata: 15 caratteri.

String
Esempio: 3280987654

mobilePhoneCountryCode

Prefisso del telefono cellulare.
Lunghezza massima consigliata: 4 caratteri.

String
Esempio: +39

recontactConsent

In alcuni scenari è possibile raccogliere il consenso del pagatore ad essere ricontattato dal commerciante. Questo campo indica se il pagatore ha dato tale consenso.

Boolean

shippingAddress

Oggetto contenente il dettaglio dell'indirizzo del cliente.

Object

additionalInfo	Informazioni aggiuntive sull'indirizzo, ad esempio il piano. Lunghezza massima consigliata: 50 caratteri.	String Esempio: Quinto Piano, Scala B
city	Città. Lunghezza massima consigliata: 40 caratteri.	String Esempio: Bologna
country	Stato nel codice ISO 3166-1 alpha-3. Lunghezza massima consigliata: 3 caratteri.	String Esempio: ITA
name	Nome e cognome. Lunghezza massima consigliata: 50 caratteri.	String Esempio: Mario Rossi
postCode	Codice Postale. Lunghezza massima consigliata: 16 caratteri.	String Esempio: 40124
province	Codice della provincia. Lunghezza massima consigliata: 3 caratteri.	String Esempio: BO
street	Indirizzo completo. Lunghezza massima consigliata: 50 caratteri.	String Esempio: Piazza Maggiore, 1

tin

Il numero di identificazione fiscale viene raccolto in determinati scenari, come le donazioni, per conformarsi alle normative fiscali. È un identificatore utilizzato in molti paesi a fini fiscali.

String
Lunghezza max: 32
Esempio: 12345678901

workPhone

Numero di telefono lavorativo fornito dal titolare della carta.
Lunghezza massima consigliata: 18 caratteri.

String
Esempio: 391231234567

omnichannelId

Identificativo omnichannel. Viene utilizzato per correlare la stessa operazione tra diversi canali.

String

operationAmount

Importo dell'operazione nella valuta del pagamento

String
Esempio: 3545

operationCurrency

Valuta di pagamento

String
Esempio: EUR

operationId

Identificativo univoco dell'operazione

String
Esempio: 852525265182852619

operationResult

Esito dell'operazione:
* AUTORIZZATO - Pagamento autorizzato
* ESEGUITO - Pagamento confermato, verifica eseguita con successo
* DECLINED - Rifiutato dall'Emittente in fase di autorizzazione
* DENIED_BY_RISK - Esito negativo dell'analisi del rischio di transazione
* THREEDS_VALIDATED - Autenticazione 3DS OK o 3DS saltata (pagamento non sicuro)
* THREEDS_FAILED - annullamento o errore di autenticazione durante 3DS
* IN ATTESA - Pagamento in corso. Sono previste notifiche di follow-up
* ANNULLATO - Annullato dal titolare della carta
* ANNULLATO - Storno online dell'intero importo autorizzato
* RIMBORSATO - Importo rimborsato totale o parziale
* FALLITO - Pagamento non riuscito per motivi tecnici

String
Esempio: AUTHORIZED

operationTime

Tempo di funzionamento in formato ISO 8601

String

operationType

Indica lo scopo della richiesta:
- AUTORIZZAZIONE - autorizzazione al pagamento.
- CAPTURE - cattura dell'importo autorizzato.
- VOID - annullamento di un'autorizzazione.
- RIMBORSO - rimborso di un importo catturato.
- ANNULLA - il rollback di una cattura, rimborso.
- CARD_VERIFICATION - verifica il funzionamento, senza alcun addebito, al solo scopo di confermare la validità dei dati della carta inseriti dal cliente.
- NOSHOW - operazione noshow (riservata al servizio Disputeless).
- INCREMENTAL - operazione incrementale (riservata al servizio Disputeless).
- DELAY_CHARGE - operazione di addebito ritardato (riservata al servizio Disputeless).

String
Esempio: CAPTURE

orderId

Identificatore dell'ordine del commerciante, univoco nel dominio del commerciante.
La lunghezza massima è di 27 caratteri. Per rispettare le specifiche del circuito di pagamento, si consiglia vivamente di utilizzare un orderId fino a 18 caratteri.
Una buona strategia di unicità è quella di combinare un commerciante stabile o un prefisso di canale con una sequenza monotona, un timestamp o un riferimento all'ordine della piattaforma, evitando il riutilizzo per pagamenti diversi.

String
Lunghezza max: 27
Esempio: btid2384983

paymentCircuit

Uno dei valori del circuito di pagamento restituiti dal servizio web GET payment_methods.
L'elenco può includere (ma non limitato a) VISA, MC, AMEX, DINERS, GOOGLE_PAY, APPLE_PAY, PAYPAL, BANCONTACT, BANCOMAT_PAY, MYBANK, PIS, AMAZON_PAY, ALIPAY.

String
Esempio: VISA

paymentEndToEndId

Identificativo definito dal circuito per identificare univocamente la transazione.
Necessario per scopi di riconciliazione del circuito.

String
Lunghezza min: 18
Lunghezza max: 35
Esempio: e723hedsdew12345678

paymentInstrumentInfo

Informazioni sullo strumento di pagamento

String
Esempio: ***6152

paymentLinkId

ID PayByLink utilizzato per correlare questa operazione con il collegamento originale.

String
Esempio: 234244353

paymentMethod

* CARD - Qualsiasi circuito di scheda
* APM - Metodo di pagamento alternativo

String
Esempio: CARD

warnings

Elenco degli avvisi relativi all'operazione.

Array

		code	Codice di avviso.	String Esempio: TRA001
		description	Descrizione dell'avviso.	String Esempio: 3DS warning

state

String
Esempio: CARD_DATA_COLLECTION

url

Indirizzo per l'autenticazione 3D Secure. Questo parametro viene restituito se il parametro "state" è impostato su "REDIRECTED_TO_EXTERNAL_DOMAIN".

String
Esempio: https://{3DS-Url}

RESPONSE 201

Creato - Nessun header e body per questa risposta

RESPONSE 400

Dati della richiesta non validi - Nessun header per questa risposta

BODY

NOME

DESCRIZIONE

FORMATO

errors

Array contenente l'elenco degli errori. I possibili valori sono riportati nella tabella Codici errore.

Array

		code	Codice errore.	String Esempio: GW0001
		description	Descrizione dell'errore.	String Esempio: Invalid merchant URL

RESPONSE 401

Non autorizzato - Nessun header e body per questa risposta

RESPONSE 403

Vietato - Nessun header e body per questa risposta

RESPONSE 404

Non trovato - Nessun header e body per questa risposta

RESPONSE 500

Errore interno del server - Nessun header per questa risposta

BODY

NOME

DESCRIZIONE

FORMATO

errors

Array contenente l'elenco degli errori. I possibili valori sono riportati nella tabella Codici errore.

Array

		code	Codice errore.	String Esempio: GW0001
		description	Descrizione dell'errore.	String Esempio: Invalid merchant URL