Nessun risultato trovato

POST/orders/hpp

PROD
https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/hpp
TEST
https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/orders/hpp

Avvio del pagamento tramite la soluzione Hosted Payment Page, l'API restituisce l'url verso cui reindirizzare il cliente per effettuare la transazione. Per maggiori informazioni fare riferimento alla pagina dedicata Hosted Payment Page.

PARAM HEADER
NOME DESCRIZIONE FORMATO
X-Api-Key Chiave API d'autenticazione. String
Formato: uuid
Esempio: 625b4884-38f8-11ed-a261-0242ac120002
Correlation-Id Identificatore univoco della richiesta. String
Formato: uuid
Esempio: 4935e818-38e0-11ed-a261-0242ac120002
PARAM PATH
NOME DESCRIZIONE FORMATO
No param path
PARAM QUERY
NOME DESCRIZIONE FORMATO
No param query
PARAM BODY

NOME DESCRIZIONE FORMATO
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}
Arrow RESPONSE 200
Pagamento avviato con successo - Nessun header per questa risposta
BODY
NOME DESCRIZIONE FORMATO
hostedPage URL della pagina di pagamento. Reindirizza il flusso di pagamento a questo URL. String
Esempio: https://{gateway_hosted_page}
securityToken Token che può essere utilizzato per convalidare le notifiche relative a questo pagamento. String
Esempio: 2f0ea5059b41414ca3744fe672327d85
Arrow 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
Arrow RESPONSE 401
Non autorizzato - Nessun header e body per questa risposta
Arrow 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