API > POST /orders/build | Payment Gateway

POST/orders/build

PROD

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

TEST

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

Crea un ordine e avvia il pagamento tramite la soluzione XPay Build.

ATTENZIONE: per il corretto funzionamento della soluzione XPay Build è necessario che il browser utilizzato consenta l’utilizzo dei cookie di terze parti.

PARAM HEADER

NOME

DESCRIZIONE

FORMATO

		X-Api-Key	Chiave API d'autenticazione.	String Formato: uuid
		Correlation-Id	Identificatore univoco della richiesta.	String Formato: uuid

PARAM PATH

NOME

DESCRIZIONE

FORMATO

No param path

PARAM QUERY

NOME

DESCRIZIONE

FORMATO

No param query

PARAM BODY

NOME

DESCRIZIONE

FORMATO

merchantUrl

Indirizzo del sito ecommerce che ospiterà gli iframe per la raccolta dati carta restituiti da XPay.
Il valore del campo:
- Deve iniziare con “http://” o “https://”.
- Devono essere utilizzate le porte standard 80 o 443.
- Non deve terminare con uno slash "/".
- Deve essere composto solo da protocollo di comunicazione (https://) e dominio del sito web.
- Non deve contenere né parametri né indicazione del percorso verso la risorsa.
L'errata valorizzazione di questo parametro si traduce nel malfunzionamento dei campi destinati alla raccolta dei dati di carta.

Esempio di indirizzo corretto:
- https://merchanturl.it

Esempi di indirizzi errati:
- merchanturl.it
- https://merchanturl.it/
- https://merchanturl.it/xyz
- https://merchanturl.it/xyz?p=1

String

order

Oggetto contenente il dettaglio dell'ordine.

Object

orderId

ID ordine esercente, univoco nel dominio esercente.

String
Lunghezza max: 18
Esempio: btid2384983

amount

Importo della transazione nell'unità monetaria più piccola. 50 EUR sono rappresentati come 5000 (2 decimali) 50 JPY sono rappresentati come 50 (0 decimali).

String
Esempio: 3545

currency

Valuta della transazione nel codice ISO 4217.

String
Esempio: EUR

customerId

ID cliente per questa transazione.

String
Lunghezza max: 27
Esempio: mcid97295873

description

Descrizione della transazione.

String
Lunghezza max: 255
Esempio: TV 3423

customField

Descrizione addizionale transazione.

String
Lunghezza max: 255
Esempio: weekend promotion

customerInfo

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

Object

cardHolderName

Nome e cognome del titolare della carta.

String
Lunghezza max: 255
Esempio: Mauro Morandi

cardHolderEmail

Email del titolare della carta.

String
Lunghezza max: 255
Esempio: mauro.morandi@nexi.it

billingAddress

Oggetto contenente il dettaglio dell'indirizzo del cliente.

Object

name	Nome e cognome.	String Lunghezza max: 50 Esempio: Mario Rossi
street	Indirizzo completo.	String Lunghezza max: 50 Esempio: Piazza Maggiore, 1
additionalInfo	Informazioni aggiuntive sull'indirizzo, per esempio il piano.	String Lunghezza max: 50 Esempio: Quinto Piano, Scala B
city	Città.	String Lunghezza min: 1 Lunghezza max: 40 Esempio: Bologna
postCode	Codice postale.	String Lunghezza max: 16 Esempio: 40124
province	Codice della provincia.	String Lunghezza max: 3 Esempio: BO
country	Stato secondo il codice ISO 3166-1 alpha-3. Il parametro è obbligatorio con i seguenti metodi di pagamento alternativi: - Bancontact: valorizzare "country" con "BEL". - Giropay: valorizzare "country" con "DEU". - Multibanco: valorizzare "country" con "PRT".	String Lunghezza min: 3 Lunghezza max: 3 Esempio: ITA

shippingAddress

Oggetto contenente il dettaglio dell'indirizzo del cliente.

Object

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

mobilePhoneCountryCode

Prefisso del numero di telefono.

String
Lunghezza max: 4
Esempio: +39

mobilePhone

Numero di cellulare.

String
Lunghezza max: 15
Esempio: 3280987654

homePhone

Telefono di casa fornito dal titolare carta.

String
Lunghezza max: 18
Esempio: +391231234567

workPhone

Numero di telefono lavorativo fornito dal titolare carta.

String
Lunghezza max: 18
Esempio: 391231234567

cardHolderAcctInfo

Oggetto contenente informazioni relative all'account dell'acquirente.

Object

chAccDate	Data di attivazione dell'account sul sito dell'esercente.	String Esempio: 2019-02-11
chAccAgeIndicator	Indicatore dell'anzianità dell'account sul sito dell'esercente: 01 = Nessun account 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 dell'esercente, incluso l'indirizzo di fatturazione o spedizione, nuovo metodi di pagamento o l'aggiunta di nuovi utenti.	String Esempio: 2019-02-11
chAccChangeIndicator	Tempo trascorso dall'ultima modifica delle informazioni sull'account dell'acquirente sul sito dell'esercente, incluso l'indirizzo di fatturazione o spedizione, nuovo metodo 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
chAccPwChangeDate	Data di ultimo cambio password dell'account (incluso reset password).	String Esempio: 2019-02-11
chAccPwChangeIndicator	Tempo trascorso da quando l'account dell'acquirente ha eseguito una modifica della password o il ripristino dell'account: 01 = Nessun account 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
nbPurchaseAccount	Numero di acquisti di questo account negli ultimi 6 mesi.	Number Esempio: 0
destinationAddressUsageDate	Data di ultimo utilizzo di questo indirizzo di consegna.	String Esempio: 2019-02-11
destinationAddressUsageIndicator	Indica quando l'indirizzo di spedizione utilizzato per questa transazione è stato utilizzato per la prima volta: 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 dell'account identico al nome dell'indirizzo di spedizione. 02 = Nome dell'account diverso dal nome dell'indirizzo di spedizione.	String Esempio: 01
txnActivityDay	Numero di transazioni (riuscite e abbandonate) per questo account nelle 24 ore precedenti.	Number Esempio: 0
txnActivityYear	Numero di transazioni (riuscite e abbandonate) per questo account nell'anno precedente.	Number Esempio: 0
provisionAttemptsDay	Numero di tentativi di aggiunta nuova carta nelle ultime 24 ore.	Number Esempio: 0
suspiciousAccActivity	Indica se l'esercente ha rilevato attività sospette (incluse precedenti frodi) sull'account dell'acquirente. 01 = Nessun attività sospetta verificata. 02 = Rilevate attività sospette.	String Esempio: 01
paymentAccAgeDate	Data di attivazione dell'account di pagamento.	String Esempio: 2019-02-11
paymentAccIndicator	Indica quando l'acquirente ha inserito l'account di pagamento sul sito del merchant: 0 = Nessun account 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: 0

merchantRiskIndicator

Oggetto contenente informazioni relative all'acquisto effettuato.

Object

deliveryEmail

Nel caso di acquisto di prodotti virtuali/digitali: indirizzo mail verso 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 nello stesso giorno.
03 = Consegna notturna.
04 = Consegna in due o più giorni.

String
Esempio: 01

giftCardAmount

Oggetto contenente informazioni relative all'importo delle carte regalo o buoni.

Object

		value	Valore della carta regalo o prepagata utilizzata per la transazione. L'importo deve essere espresso in centesimi.	Number Esempio: 100
		currency	Valuta della transazione nel codice ISO 4217.	String Esempio: EUR

giftCardCount

Totale delle singole carte/codici prepagate o regalo acquistati.

Number
Esempio: 2

preOrderDate

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

String
Esempio: 2019-02-11

preOrderPurchaseIndicator

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

String
Esempio: 01

reorderItemsIndicator

Indica se l'acquirente sta riordinando merce acquistata in precedenza:
01 = Primo ordine.
02 = Merce già acquistata in precedenza.

String
Esempio: 01

shipIndicator

Indicatore sulla tipologia di consegna:
01 = Spedizione all'indirizzo di fatturazione.
02 = Spedizione ad un altro indirizzo verificato dal merchant.
03 = Spedizione ad un indirizzo differente da quello di fatturazione.
04 = Spedizione o ritiro al negozio (l'indirizzo del negozio deve essere indicato nei campi di destinazione).
05 = Beni virtuali/digitali, inclusi servizi online, buoni regalo elettronici, codici di riscossione.
06 = Biglietti di viaggi ed eventi (non spediti).
07 = Altro: per esempio giochi, servizi digitali non spediti, abbonamenti a media elettronici.

String
Esempio: 01

transactionSummary

Array contenente il riepilogo della transazione.

Array

language

Lingua usata nel dettaglio del riepilogo della transazione, ISO 639-2.

String
Esempio: eng

summaryList

Array contenente il riepilogo della lista.

Array

		label	Etichetta del campo.	String Lunghezza max: 50 Esempio: Number of people
		value	Valore.	String Esempio: 4

termsAndConditionsIds

Array di identificativi dei T&C della struttura. Inserimento termini e condizioni

Array

paymentSession

Oggetto contenente il dettaglio del pagamento.

Object

actionType

Indica la tipologia di operazione:
* PAY - esegue un'operazione di pagamento
* VERIFY - esegue un'operazione di verifica, senza nessun addebito, con il solo scopo di confermare la validità dei dati carta inseriti dal cliente
* PREAUTH - esegue un'operazione di preautorizzazione

String
Esempio: PAY

amount

Importo del primo pagamento che può essere inferiore o uguale all'importo dell'ordine. 50 EUR sono rappresentati come 5000 (2 decimali) 50 JPY sono rappresentati come 50 (0 decimali).

String
Esempio: 3545

recurrence

Oggetto contenente il dettaglio della ricorrenza.

Object

action	Definisce il tipo di contratto da usare per il pagamento: * NO_RECURRING - senza contratto * SUBSEQUENT_PAYMENT - utilizzo di un contratto già creato * CONTRACT_CREATION - creazione contratto * CARD_SUBSTITUTION -	String Esempio: NO_RECURRING
contractId	ID contratto.	String Lunghezza min: 1 Lunghezza max: 18 Esempio: C2834987
contractType	* MIT_UNSCHEDULED - una volta tokenizzata la carta, l'esercente eseguirà gli addebiti successivi con cadenza non definita * MIT_SCHEDULED - una volta tokenizzata la carta, l'esercente eseguirà gli addebiti successivi con cadenza definita (es. primo di ogni mese) * CIT - la carta viene tokenizzata per permettere al titolare di eseguire pagamenti successivi più rapidi. A differenza delle transazioni MIT l'esercente non avrà la possibilità di eseguire addebiti diretti su queste carte tokenizzate, in quanto il pagamento successivo CIT è sottoposto ad autenticazione (SCA) da parte del titolare carta	String Esempio: MIT_UNSCHEDULED
contractExpiryDate	Utilizzato con contractType MIT_SCHEDULED.	String Esempio: 2023-03-16
contractFrequency	Utilizzato con contractType MIT_SCHEDULED. Numero di giorni.	String Lunghezza max: 4 Esempio: 120

captureType

Sovrascrive il metodo di conferma predefinito del terminale, per solo carte di pagamento:
* IMPLICIT - conferma automatica
* EXPLICIT - solo autorizzazione

Il valore predefinito dipende dalla configurazione del terminale:
    1. Terminale impostato su ESPLICITO:
        a. se il captureType è EXPLICIT l'acquisizione sarà esplicita
        b. se il captureType è nullo l'acquisizione sarà ESPLICITA
        c. se il captureType è IMPLICIT l'acquisizione sarà implicita

    2. Terminale impostato su IMPLICITO:
        a. se il captureType è EXPLICIT l'acquisizione restituirà un errore
        b. se il captureType è nullo l'acquisizione sarà implicita
        c. se il captureType è IMPLICIT l'acquisizione sarà implicita

String
Esempio: EXPLICIT

exemptions

NO_PREFERENCE, CHALLENGE_REQUESTED

String
Default: NO_PREFERENCE
Esempio: NO_PREFERENCE

language

Lingua da utilizzare nella pagina di pagamento. ISO 639-2.

String
Default: ita
Esempio: ita

paymentService

Se presente, la pagina di pagamento viene mostrata consentendo all'utente di effettuare il pagamento solo con i circuiti o le modalità di pagamento indicate. I possibili valori sono indicati nella tabella Codifica paymentService.

String

resultUrl

URL esercente verso cui il titolare della carta viene reindirizzato una volta completato il pagamento.
Il valore del campo:
- Deve iniziare con “http://” o “https://”.
- Devono essere utilizzate le porte standard 80 o 443.
- Non deve terminare con uno slash "/".

Per una corretta gestione dell'esito, questo indirizzo deve contenere al suo interno il riferimento dell'ordine (valore del parametro "orderId"):

{
...
"resultUrl":"https://merchant_result_url.com/orderId"
...
}

In questo modo, al termine della transazione, il cliente verrà reindirizzato verso l'URL sopra riportato con l'identificativo dell'ordine: sarà così possibile per il sito ecommerce richiamare l'api GET /orders/{orderId} per verificare l'esito della transazione.

È consigliato evitare di impostare i parametri "notificationUrl" e "resultUrl" con lo stesso valore poiché sono destinati a scopi diversi: il primo indirizzo viene interpretato da un webhook, mentre il secondo viene gestito dal browser tramite redirect. Queste due destinazioni hanno scopi distinti e possono interpretare le risposte in modo diverso.

String
Lunghezza max: 2048
Esempio: https://{merchant_result_url}

cancelUrl

URL esercente a cui il titolare della carta viene reindirizzato una volta abbandonato il pagamento.
Il valore del campo:
- Deve iniziare con “http://” o “https://”.
- Devono essere utilizzate le porte standard 80 o 443.
- Non deve terminare con uno slash "/".

String
Lunghezza max: 2048
Esempio: https://{merchant_cancel_url}

notificationUrl

Indirizzo verso cui viene inviato l'esito della transazione con relativi parametri, in modalità server to server con metodo POST.
Il valore del campo:
- Deve iniziare con “http://” o “https://”.
- Devono essere utilizzate le porte standard 80 o 443.
- Non deve terminare con uno slash "/".
- Deve essere utilizzato un certificato pubblico.
- Non deve essere protetto da autenticazione.

Il contenuto della notifica viene dettagliato nella sezione Notifica.

È consigliato evitare di impostare i parametri "notificationUrl" e "resultUrl" con lo stesso valore poiché sono destinati a scopi diversi: il primo indirizzo viene interpretato da un webhook, mentre il secondo viene gestito dal browser tramite redirect. Queste due destinazioni hanno scopi distinti e possono interpretare le risposte in modo diverso.

String
Lunghezza max: 2048
Esempio: https://{merchant_notification_url}

RESPONSE 200

La chiamata restituisce un oggetto, contenente gli iframe corrispondenti al metodo di pagamento tramite carta e agli APM attivi sul terminale dell'esercente - Nessun header per questa risposta

BODY

NOME

DESCRIZIONE

FORMATO

sessionId

Identificativo sessione.

String
Esempio: sessionId

securityToken

Token di sicurezza per la transazione.

String
Esempio: security token

fields

Array di oggetti contenenti gli iframe corrispondenti ai metodi di pagamento attivi sul terminale dell'esercente.

Array

type	Tipologia del campo, valori possibili: - ACTION: campo che necessità di un'azione da parte del titolare carta sull'iframe, in questo caso il click sul componente.	String Esempio: ACTION
class	Classe del campo, valori possibili: - APM - CARD	String Esempio: CARD
id	Identificativo del campo.	String Esempio: PAY_WITH_CARD
src	URL iframe dedicato al metodo di pagamento.	String Esempio: https:///field.html?id=CARDHOLDER_NAME&sid=052211e8-54c8-4e0a-8402-e10bcb8ff264

state

Stato della transazione. Valori possibili:
- CARD_DATA_COLLECTION: il cliente ha scelto il pagamento tramite carta. Viene restituito l'oggetto "fieldSet" contenenti gli iframe per la raccolta dei dati carta.
- PAYMENT_METHOD_SELECTION: il cliente deve procedere con la scelta del metodo di pagamento. Viene restituito l'oggetto "fieldSet" contenenti gli iframe dei metodi di pagamento.
- READY_FOR_PAYMENT: pagamento pronto per essere eseguito, è necessario richiamare l'API POST /build/finalize_payment.
- REDIRECTED_TO_EXTERNAL_DOMAIN: è stato fornito l'url per eseguire l'autenticazione 3D Secure. Viene restituito il parametro "url".
- PAYMENT_COMPLETE: il pagamento è stato completato. Viene restituito l'oggetto "operation".
- GDI_VERIFICATION: solo con versione 2 di XPay Build. La richiesta GET build/state è stata invocata durante la verifica GDI. È necessario mostrare una pagina contenente il frame interno nascosto.

String

url

Indirizzo per fase 3D Secure.

String
Esempio: https:apm_url.it

RESPONSE 400

Dati della richiesta non validi - Nessun header per questa risposta

BODY

NOME

DESCRIZIONE

FORMATO

errors

Array contenente la lista degli errori. I valori possibili sono riportati nella tabella Codici errore.

Array

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

RESPONSE 401

Non autorizzato - Nessun header e body per questa risposta

RESPONSE 500

Internal Server Error - Nessun header per questa risposta

BODY

NOME

DESCRIZIONE

FORMATO

errors

Array contenente la lista degli errori. I valori possibili sono riportati nella tabella Codici errore.

Array

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