Nessun risultato trovato

POST/v3/orders/paybylink

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

Crea un nuovo link di pagamento

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
x-plugin-name Nome del plugin String
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

payByLinkRequest

NOME DESCRIZIONE FORMATO
expirationDate ExpirationDate in formato ISO 8601. Valori accettati: - Solo data: YYYY-MM-DD - Data e ora: YYYY-MM-DDTHH:MM:SSZ
 String
order Oggetto contenente i dettagli dell'ordine.
 Object
amount Importo della transazione nell'unità monetaria più piccola. 50 euro sono rappresentati
come 5000 (2 decimali) 50 JPY è rappresentato come 50 (0 decimali)
 String
Esempio: 3545
currency Valuta della transazione. Codice alfabetico ISO 4217
 String
Esempio: EUR
customField Descrizione aggiuntiva della transazione
 String
Lunghezza max: 255
Esempio: weekend promotion
customerId Identificatore del cliente calcolato dal commerciante per corrispondere al cliente registrato sulla piattaforma di e-commerce.
Utilizzare solo lettere, cifre, trattino basso (_) o trattino (-).
 String
Lunghezza max: 27
Esempio: mcid97295873
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
description Descrizione della transazione
 String
Lunghezza max: 255
Esempio: TV LG 3423
invoiceId L'ID della fattura. Deve contenere solo caratteri supportati: alfanumerici, carattere di sottolineatura (_), meno (-) o più (+) con una lunghezza massima di 30 caratteri.
Questo campo è facoltativo.
[rif. ISOv93 127,98]
 String
Lunghezza max: 30
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
plan Oggetto contenente i dettagli della descrizione del piano.
Puoi visualizzare il piano creato tramite il menu "subscription" nel tuo backoffice.
In base ai diversi valori di `planType`, il piano può essere utilizzato per scopi differenti:
- FIXED: ogni rata ha lo stesso importo e date di scadenza specificate.
- VARIABLE: ogni rata può avere un importo diverso e date di scadenza specificate.
- ACQUIRER_AGREEMENT: gestito dall'accordo con l'acquirer, il numero di rate e l'importo di ciascuna rata sono definiti dall'acquirer.
 Object
contractId Identificatore del contratto.
Il valore deve essere lungo tra 1 e 18 caratteri. Per mantenerlo unico, utilizza un commerciante stabile o un prefisso di canale insieme a una sequenza monotona, un timestamp o un riferimento al contratto della piattaforma, evitando il riutilizzo per diversi contratti ricorrenti.
 String
Lunghezza min: 1
Lunghezza max: 18
Esempio: C2834987
planType Valori possibili:
- FIXED: ogni rata ha lo stesso importo e date di scadenza specificate.
- VARIABLE: ogni rata può avere un importo diverso e date di scadenza specificate.
- ACQUIRER_AGREEMENT: gestito dall'accordo con l'acquirer, il numero di rate e l'importo di ciascuna rata sono definiti dall'acquirer.
 String
status Valori possibili:
- ACTIVE: il piano è attivo e può essere utilizzato per le transazioni.
- INACTIVE: il piano è inattivo e non può essere utilizzato per le transazioni.
- COMPLETED: il piano è stato completato e tutte le rate sono state pagate.
 String
totalAmount Importo totale del piano nell'unità di valuta più piccola.
La valuta applicata è quella dell'ordine.
 String
products Elenco dei prodotti nel carrello (noto anche come carrello degli acquisti) come rappresentazione virtuale degli articoli di un cliente seleziona durante lo shopping in un negozio online.
Nota: per i pagamenti KLARNA, la lista dei prodotti è obbligatoria e l'importo totale dell'ordine deve corrispondere alla somma dei prezzi dei prodotti. 		Array
description Una spiegazione dettagliata del prodotto che fornisce informazioni essenziali per aiutare i clienti e gli elaboratori di pagamento
capire cosa si sta acquistando
 String
Lunghezza max: 255
Esempio: The Nike Air Zoom Pegasus 39 is designed for runners seeking comfort and responsiveness. Featuring a lightweight, breathable mesh upper, these shoes are built to keep your feet cool and dry throughout your run.
itemCategory Diverse categorie di articoli lavorabili:
- PHYSICAL: un oggetto tangibile, come un prodotto o una merce.
- DISCOUNT: Una riduzione del prezzo totale dell'ordine.
- SHIPPING_FEE: il costo associato alla consegna dell'ordine.
- DIGITAL: un bene immateriale, come un e-book o un software.
- GIFT_CARD: Una carta prepagata che può essere utilizzata per acquisti futuri.
- STORE_CREDIT: credito emesso dal negozio, spesso per resi o promozioni.
- SURCHARGE: Un costo aggiuntivo aggiunto all'ordine.
 String
Esempio: DIGITAL
name Il nome del prodotto visualizzato al cliente. Dovrebbe essere chiaro e conciso per aiutare il cliente a capire cosa sta acquistando
 String
Lunghezza max: 255
Esempio: Nike Air Zoom Pegasus 39 Running Shoes
price Il prezzo del prodotto per unità nell'unità monetaria più piccola.
- 50 EUR sono rappresentati come 5000 (2 decimali)
- 50 JPY è rappresentato come 50 (0 decimali)
La valuta del prodotto corrisponde alla valuta specificata nell'ordine.
Il prezzo non è strettamente correlato all'importo dell'ordine 		String
Esempio: 1000
quantity Il numero di unità che il cliente intende acquistare
 Integer
Esempio: 2
sku Unità di custodia delle scorte. È un identificatore o codice univoco assegnato\\ a ciascun prodotto o articolo
venduto da un rivenditore o da un negozio di e-commerce
 String
Lunghezza max: 64
Esempio: RUN-NIK-AZP39-BLK-10
termsAndConditionsIds Matrice di identificatori T&C della struttura. Inserimento di termini e condizioni
 Array
transactionSummary Elenco di riepilogo della transazione, contenente i dettagli della transazione.
 Array
language Lingua nel codice a tre lettere ISO 639-2. String
Lunghezza min: 3
Lunghezza max: 3
Default: ITA
Esempio: ENG
summaryList Matrice contenente l'elenco di riepilogo.
 Array
label Etichetta dei campi.
 String
Lunghezza max: 50
Esempio: Number of people
value Valore.
 String
Lunghezza max: 50
Esempio: 4
payByLinkSettings Impostazioni per il pagamento pay-by-link. Questo oggetto contiene opzioni di configurazione come gli importi predefiniti, la data di scadenza e il tipo di pagamento.
 Object
amountType Il tipo di importo che può essere specificato per il PayByLink. Può essere FIXED, ovvero l'importo è predeterminato e non può essere modificato dal cliente, oppure VARIABLE, ovvero il cliente può scegliere l'importo entro i limiti minimo e massimo specificati.
 String
Default: FIXED
collectCustomerData Configurazione per la raccolta dei campi di dati del cliente con i relativi requisiti e le informative associate Object
fields Più campi di dati del cliente da raccogliere con i relativi requisiti Array
field Campi di dati del cliente disponibili che possono essere raccolti:
* cardHolderName - Nome completo del titolare della carta
* cardHolderEmail - Indirizzo email del titolare della carta
* phoneNumber - Numero di telefono del cliente
* tin - Codice fiscale (Tax Identification Number)
* billingAddress - Dettagli dell'indirizzo di fatturazione
* shippingAddress - Dettagli dell'indirizzo di spedizione
 String
requirement Livello di obbligatorietà per la raccolta dei dati del cliente:
* mandatory - Il campo deve essere fornito dal cliente
* optional - Il campo può essere lasciato vuoto dal cliente
* hidden - Il campo non viene mostrato al cliente
 String
descriptions Un elenco di descrizioni che possono essere visualizzate nella pagina di pagamento. Ogni descrizione può essere fornita in più lingue.
 Array
lang Lingua nel codice a tre lettere ISO 639-2. String
Lunghezza min: 3
Lunghezza max: 3
Default: ITA
Esempio: ENG
title Il titolo della descrizione, che può essere utilizzato per riassumere il contenuto della descrizione.
 String
Lunghezza max: 255
value Un elenco di coppie etichetta-valore che forniscono dettagli sul pagamento. Ogni coppia è composta da un'etichetta (ad esempio, "Numero di persone") e un valore corrispondente (ad esempio, "4").
 String
Lunghezza max: 1000
expirationDateTime La data e l'ora in cui il Pay By Link scadrà. È in formato ISO 8601. Fino a 90 giorni dalla data corrente.
 String
Esempio: 2023-12-31T23:59:59Z
image Un URL di un'immagine che verrà visualizzata nella pagina di pagamento. Può essere utilizzato per scopi di branding, ad esempio per mostrare il logo del commerciante.
 String
Lunghezza max: 700000
imageType Il tipo dell'immagine, ad esempio PNG, JPEG. Questo campo è opzionale e può essere utilizzato per specificare il formato dell'immagine.
 String
maxAmount L'importo massimo consentito per il link di pagamento. Questo valore viene utilizzato per validare l'importo del pagamento inserito dal cliente.
 String
Esempio: 100
maxPayments Il numero massimo di pagamenti consentiti per il link di pagamento. Questo valore viene utilizzato per limitare il numero di volte in cui un cliente può effettuare un pagamento utilizzando il link.
 String
Esempio: 12
minAmount L'importo minimo consentito per il link di pagamento. Questo valore viene utilizzato per validare l'importo del pagamento inserito dal cliente.
 String
Esempio: 10
paymentType Il tipo di pagamento, che può essere un pagamento singolo oppure consentire più pagamenti all'interno dello stesso PayByLink.
 String
Default: ONE_PAYMENT
predefinedAmounts Un elenco di importi predefiniti per il link di pagamento separati da punto e virgola. Ad esempio: "100;200;300".
 String
Esempio: 100;200;300
paymentSession Oggetto contenente i dettagli del pagamento.
 Object
actionType Indica il tipo di operazione:
* PAY - esegue una transazione di pagamento
* VERIFY - effettua un'operazione di verifica, senza alcun addebito, con il solo scopo di confermare la validità dei dati della carta inseriti dal cliente
* PREAUTH - esegue un'operazione di preautorizzazione
 String
Default: PAY
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
cancelUrl URL del commerciante a cui il titolare della carta viene reindirizzato una volta abbandonato il pagamento ospitato.
Il valore del campo:
- Deve iniziare con "https://".
- Può contenere parametri di percorso e stringa di query.
 String
Lunghezza min: 1
Lunghezza max: 2048
Esempio: https://merchant.example.com/cancel?orderId=btid2384983
captureType Sovrascrive il metodo di conferma predefinito del terminale, solo per i pagamenti con carta:
* IMPLICIT - conferma automatica
* EXPLICIT - solo autorizzazione

Il valore predefinito dipende dalla configurazione del terminale.
1. Terminale impostato su EXPLICIT:
a. se captureType è EXPLICIT la cattura sarà EXPLICIT
b. se captureType è nullo la cattura sarà EXPLICIT
c. se captureType è IMPLICIT la cattura sarà IMPLICIT

2. Terminale impostato su IMPLICIT:
a. se captureType è EXPLICIT l'acquisizione sarà un errore
b. se captureType è nullo la cattura sarà IMPLICIT
c. se captureType è IMPLICIT la cattura sarà IMPLICIT
 String
Esempio: EXPLICIT
exemptions NO_PREFERENCE, CHALLENGE_REQUESTED
 String
Esempio: NO_PREFERENCE
fundTransfer Campo opzionale contenente informazioni sul trasferimento di fondi Object
recipient Informazioni sul destinatario/mittente del trasferimento Object
address 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
companyName Ragione sociale del destinatario/mittente del bonifico (obbligatorio se customerType is not INDIVIDUAL) String
Lunghezza max: 100
Esempio: John Doe Inc.
customerType Tipo di destinatario/mittente del bonifico String
Esempio: INDIVIDUAL
dateOfBirth Data di nascita del destinatario/mittente del bonifico secondo ISO 8601 format. String
email Email del destinatario/mittente del trasferimento String
Lunghezza max: 255
Esempio: john.doe@example.com
firstName Nome del destinatario/mittente del bonifico (solo per customerType INDIVIDUAL) String
Lunghezza max: 50
Esempio: John
identityDocument Informazioni relative al documento di identità del destinatario/mittente del bonifico Object
documentNumber Numero del documento di identità String
Lunghezza max: 50
Esempio: 123456789
documentType Tipologia del documento d'identità String
Esempio: PASSPORT
issuingCountry ISO 3166-1 alfa-3 String
Esempio: ITA
lastName Cognome del destinatario/mittente del bonifico (solo per customerType INDIVIDUAL) String
Lunghezza max: 50
Esempio: Doe
paymentInstrumentInfo Informazioni sullo strumento di pagamento String
Esempio: ***6152
phoneNumber Numero di telefono del destinatario/mittente del bonifico String
Lunghezza max: 20
Esempio: +1234567890
sender Informazioni sul destinatario/mittente del trasferimento Object
address 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
companyName Ragione sociale del destinatario/mittente del bonifico (obbligatorio se customerType is not INDIVIDUAL) String
Lunghezza max: 100
Esempio: John Doe Inc.
customerType Tipo di destinatario/mittente del bonifico String
Esempio: INDIVIDUAL
dateOfBirth Data di nascita del destinatario/mittente del bonifico secondo ISO 8601 format. String
email Email del destinatario/mittente del trasferimento String
Lunghezza max: 255
Esempio: john.doe@example.com
firstName Nome del destinatario/mittente del bonifico (solo per customerType INDIVIDUAL) String
Lunghezza max: 50
Esempio: John
identityDocument Informazioni relative al documento di identità del destinatario/mittente del bonifico Object
documentNumber Numero del documento di identità String
Lunghezza max: 50
Esempio: 123456789
documentType Tipologia del documento d'identità String
Esempio: PASSPORT
issuingCountry ISO 3166-1 alfa-3 String
Esempio: ITA
lastName Cognome del destinatario/mittente del bonifico (solo per customerType INDIVIDUAL) String
Lunghezza max: 50
Esempio: Doe
paymentInstrumentInfo Informazioni sullo strumento di pagamento String
Esempio: ***6152
phoneNumber Numero di telefono del destinatario/mittente del bonifico String
Lunghezza max: 20
Esempio: +1234567890
transferType Tipo di trasferimento fondi String
Esempio: AFT
language Lingua nel codice a tre lettere ISO 639-2. String
Lunghezza min: 3
Lunghezza max: 3
Default: ITA
Esempio: ENG
notificationUrl Indirizzo al quale viene inviato l'esito della transazione con relativi parametri, in modalità server to server con metodo POST.
Il valore del campo:
- Deve iniziare con "https://".
- Può contenere parametri di percorso e stringa di query.
- È necessario utilizzare un certificato pubblico.
- Non deve essere autenticato.

Il contenuto della notifica è dettagliato nella sezione Notifica.

Si consiglia di evitare di impostare i parametri "notificationUrl" e "resultUrl" con lo stesso valore in quanto hanno scopi diversi: il primo viene interpretato da un webhook, mentre il secondo viene gestito dal browser tramite reindirizzamento. Queste due destinazioni hanno scopi distinti e possono interpretare le risposte in modo diverso.
 String
Lunghezza min: 1
Lunghezza max: 2048
Esempio: https://merchant.example.com/notification?orderId=btid2384983
paymentService Se presente, viene visualizzata la pagina di pagamento consentendo all'utente di effettuare il pagamento solo con i circuiti o le modalità di pagamento indicati. I valori possibili sono indicati nella tabella codifica PaymentService.
 String
Esempio: GOOGLEPAY
recurrence Oggetto contenente il dettaglio della ricorrenza.
 Object
action Definisce la tipologia di contratto da utilizzare per il pagamento:
* NO_RECURRING - senza contratto
* SUBSEQUENT_PAYMENT - utilizzo di un contratto già creato
* CONTRACT_CREATION - creazione del contratto
* CARD_SUBSTITUTION - sostituzione carta associata ad un contratto
 String
Esempio: CONTRACT_CREATION
contractExpiryDate Utilizzato con contractType MIT_SCHEDULED.
 String
contractFrequency Utilizzato con contractType MIT_SCHEDULED. Numero di giorni.
 String
Lunghezza max: 4
Esempio: 120
contractId Identificatore del contratto.
Il valore deve essere lungo tra 1 e 18 caratteri. Per mantenerlo unico, utilizza un commerciante stabile o un prefisso di canale insieme a una sequenza monotona, un timestamp o un riferimento al contratto della piattaforma, evitando il riutilizzo per diversi contratti ricorrenti.
 String
Lunghezza min: 1
Lunghezza max: 18
Esempio: C2834987
contractType Indica le opzioni disponibili per i pagamenti successivi:
* CIT - il contratto può essere utilizzato solo per i pagamenti successivi disposti dal
* MIT_SCHEDULED - il contratto può essere utilizzato per transazioni programmate avviate dal commerciante. Il numero di giorni tra un pagamento e l'altro deve essere uguale o maggiore del valore di `contractFrequency`
* MIT_UNSCHEDULED - il contratto può essere utilizzato per transazioni non programmate avviate dal commerciante. Il valore contractFrequency non ha alcun effetto in questo caso. 		String
Esempio: CIT
resultUrl URL del commerciante a cui viene reindirizzato il titolare della carta una volta completato il pagamento.
Il valore del campo:
- Deve iniziare con "https://".
- Può contenere parametri di percorso e stringa di query.

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

{
...
"resultUrl": "https://merchant.example.com/orderId"
...
}

In questo modo, al termine della transazione, il cliente verrà reindirizzato al suddetto URL con l'identificativo dell'ordine. Ciò consentirà al sito di e-commerce di chiamare l'API GET /orders/{orderId} per verificare l'esito della transazione.

Si consiglia di evitare di impostare i parametri "notificationUrl" e "resultUrl" con lo stesso valore in quanto hanno scopi diversi: il primo viene interpretato da un webhook, mentre il secondo viene gestito dal browser tramite reindirizzamento. Queste due destinazioni hanno scopi distinti e possono interpretare le risposte in modo diverso.
 String
Lunghezza min: 1
Lunghezza max: 2048
Esempio: https://merchant.example.com/result?orderId=btid2384983
Arrow RESPONSE 200
OK - Nessun header per questa risposta
BODY
NOME DESCRIZIONE FORMATO
paymentLink Un data transfer object che rappresenta i dettagli di un PayByLink. Include l'identificativo univoco del link, l'URL per effettuare il pagamento, l'importo e la data di scadenza del link. Object
amount L'importo associato al PayByLink. Questo valore rappresenta l'importo totale che il cliente dovrà pagare utilizzando il link.
 String
expirationDate La data e l'ora in cui il Pay By Link scadrà. È in formato ISO 8601. Fino a 90 giorni dalla data corrente.
 String
Esempio: 2023-12-31T23:59:59Z
link L'URL che il cliente può utilizzare per effettuare il pagamento. Questo link è univoco per il PayByLink e dovrebbe essere condiviso con il cliente per completare il pagamento.
 String
linkId L'identificativo univoco del PayByLink. Questo ID viene utilizzato per fare riferimento allo specifico link di pagamento nel sistema.
 String
paidByOperationId Se disponibile, l'identificativo univoco dell'operazione utilizzata per effettuare il pagamento. Questo ID viene utilizzato per tracciare la transazione di pagamento associata al PayByLink.
 String
status Lo stato del Pay By Link. Può essere ACTIVE, INACTIVE o DELETED. ACTIVE significa che il link è attivo e può essere utilizzato per i pagamenti, INACTIVE significa che il link non è attivo e non può essere utilizzato per i pagamenti, DELETED significa che il link è stato eliminato.
 String
securityToken Token di sicurezza utilizzato dal commerciante per convalidare la fonte of the notification. String
Esempio: f3b2c1d4e5a6b7c8d9e0f1a2b3c4d5e6
warnings Un elenco di avvisi che possono essersi verificati durante la creazione del PayByLink. Ogni avviso include un codice e un messaggio che descrive l'avviso. Array
code Codice di avviso. String
Esempio: TRA001
description Descrizione dell'avviso. String
Esempio: 3DS warning
Arrow RESPONSE 401
Non autorizzato - Nessun header e body per questa risposta
Arrow RESPONSE 403
Vietato - Nessun header e body per questa risposta
Arrow RESPONSE 404
Non trovato - Nessun header e body per questa risposta