Integration Types
Altre funzionalità
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
DirectAPI consente di passare dati aggiuntivi nelle transazioni. Possono essere inclusi i dati di settore relativi a compagnie aeree, sanitari o qualsiasi dato correlato alla transazione (Internet, ordini o anche dati personalizzati). I dati integrativi che vengono passati per una transazione vengono archiviati nel Mastercard Gateway associati alla transazione.
I dati della compagnia aerea includono dettagli su (un insieme di) voli, riferimenti di prenotazione, itinerario, passeggeri, biglietti e così via.
È possibile specificare i dettagli relativi a più passeggeri e più tratte associati al biglietto. La numerazione per i dati dei passeggeri e le tratte inizia da 0. Ad esempio, airline.itinerary.leg[0].<fieldname>. È necessario utilizzare numeri consecutivi per le tratte e i dati dei passeggeri senza saltare o ripetere numeri.
I dati della compagnia aerea possono essere applicati alle operazioni Authorize, Capture, Pay e Refund. Se si inviano i dati della compagnia aerea su una transazione iniziale e gli stessi dati della compagnia aerea si applicano alle transazioni successive per l'ordine, è necessario inviare gli stessi dati della compagnia aerea su ciascuna transazione successiva.
Riferimento API per i dati della compagnia aerea [REST][NVP]
I dati Internet includono informazioni sull'origine delle transazioni di e-commerce. Ad esempio email, indirizzo IP, nome host del cliente e così via. In questo modo si semplifica il processo di autorizzazione per le transazioni Card-Not-Present in quanto l'issuer può utilizzarli per stimare il rischio della transazione.
I dati Internet possono essere applicati solo alle operazioni Authorize e Pay.
I dati di ordine e voci includono informazioni sull'ordine e sulle voci in esso contenute che è possibile fornire nella richiesta e scegliere di visualizzare al pagante (mediante Hosted Checkout o pagamenti tramite browser) prima di confermare il pagamento. I dati di determinati ordini e voci forniti in una transazione possono qualificare la transazione per migliori tassi di commissione interbancaria con aziende, organizzazioni commerciali o Titolari di carte d'acquisto. Per ulteriori informazioni, vedere Dati di livello II e livello III.
order.item[n].brand
order.item[n].category
order.item[n].description
order.item[n].name
order.item[n].quantity
order.item[n].unitPrice
, order.item[n].unitTaxAmount
o order.item[n].unitDiscountAmount
) e le posizioni decimali del valore calcolato superano le unità minori della valuta del pagante, il gateway arrotonderà il totale utilizzando l'algoritmo "round half to even". Ad esempio, se moltiplicando 2,555 (quantità) per 3 (prezzo unitario) si ottiene 7,665 e la valuta del pagante (USD) ha 2 unità minori, l'importo arrotondato sarà 7,66.order.item[n].sku
order.item[n].unitPrice
Tale importo viene moltiplicato per order.item[n].quantity
per stabilire l'importo totale per la voce. Se si fornisce un order.itemAmount
, allora la somma dell'importo totale per tutte le voci DEVE essere uguale al valore in order.itemAmount
.
order.item[n].unitTaxAmount
Tale importo viene moltiplicato per order.item[n].quantity
per stabilire l'importo totale delle imposte per la voce. Se si fornisce un order.taxAmount
, allora la somma dell'importo delle imposte totale per tutte le voci DEVE essere uguale al valore in order.taxAmount
.
order.item[n].unitDiscountAmount
Tale importo viene moltiplicato per order.item[n].quantity
per stabilire l'importo dello sconto totale per la voce. Se si fornisce un order.discount.amount
, allora la somma dell'importo dello sconto totale per tutte le voci DEVE essere uguale al valore in order.discount.amount
.
order.item[n].name
, order.item[n].quantity
e order.item[n].unitPrice
per tale voce.order.currency
(obbligatorio):order.id
order.description
order.shippingAndHandlingAmount
order.amount
(obbligatorio)Se non si fornisce questo valore ma si fornisce uno degli importi subtotali (order.itemAmount
, order.shippingAndHandlingAmount
, order.taxAmount
, order.gratuityAmount
, order.cashbackAmount
) e order.discount.amount
allora questo importo viene calcolato come somma degli importi totali dei subtotali meno l'importo dello sconto. Se si forniscono sia il valore del campo che dei subtotali, allora il valore in questo campo DOVRÀ essere uguale al valore calcolato.
order.itemAmount
Se non si fornisce questo valore ma solo i dati delle voci, questo importo viene calcolato come somma degli importi di tutte le voci (order.item[n].unitPrice
x order.item[n].quantity
). Se si forniscono sia questo campo sia i dati delle voci, allora il valore in questo campo DOVRÀ essere uguale al valore calcolato.
order.taxAmount
Se non si fornisce questo valore ma solo i dati delle voci, questo importo viene calcolato come somma degli importi totali delle imposte (order.item[n].unitTaxAmount
x order.item[n].quantity
) per tutte le voci. Se si forniscono sia questo campo sia i dati delle voci, allora il valore in questo campo DOVRÀ essere uguale al valore calcolato.
order.discount.amount
Se non si fornisce questo valore ma solo i dati delle voci, questo importo viene calcolato come somma dell'importo complessivo dello sconto (order.item[n].unitDiscountAmount
x order.item[n].quantity
) per tutte le voci. Se si forniscono sia questo campo sia i dati delle voci, allora il valore in questo campo DOVRÀ essere uguale al valore calcolato.
order.gratuityAmount
: l'importo che il pagante ha deciso di lasciare come mancia oltre all'importo che sta pagando per merci o servizi acquistati dall'utente. L'importo aggiuntivo è incluso nell'importo totale dell'ordine fornito in order.amount
.order.cashbackAmount
: l'importo che il pagante ha deciso di ricevere come contanti oltre all'importo che sta pagando per merci o servizi acquistati dall'utente. L'importo in contanti è incluso nell'importo totale dell'ordine fornito in order.amount
.I dati dell'ordine e delle voci sono applicabili alle richieste Authorize, Pay, Initiate Browser Payment, Confirm Browser Payment, Open Wallet e Hosted Checkout.
order.cashbackAmount e order.gratuityAmount sono applicabili solo alle richieste Authorize e Pay.
I dati personalizzati dell'acquirer includono informazioni aggiuntive richieste dall'acquirer che non possono essere passate utilizzando altri campi dati disponibili. I dati personalizzati vengono archiviati nel database, che può essere utilizzato nella creazione di report esterni a Mastercard Gateway. Questo campo non deve contenere dati sensibili.
I dati personalizzati dell'acquirer possono essere applicati alle operazioni Authorize, Capture, Pay, Refund e Void.
Riferimento API per i dati personalizzati dell'acquirer [REST][NVP]
Vedere Dati di livello II e livello III.
I dati personalizzati sul rischio includono informazioni aggiuntive richieste dai provider di stima del rischio di terze parti che non possono essere trasferite utilizzando altri campi dati disponibili. I nomi dei campi personalizzati sul rischio devono essere immessi in base a quanto concordato con il proprio provider di stima del rischio di terze parti. I campi dei dati personalizzati sul rischio vengono restituiti nella risposta e possono essere utilizzati per la creazione di report e l'analisi in base alle esigenze. In nessuno dei campi dei dati personalizzati sul rischio devono essere inclusi dati sensibili.
I dati personalizzati sul rischio possono essere applicati alle operazioni Authorize, Capture, Pay, Verify.
Riferimento API per i dati personalizzati dell'acquirer [REST][NVP]
I dati personalizzati dell'esercente includono informazioni aggiuntive che interessano l'esercente che non possono essere passate utilizzando altri campi dati disponibili. Ad esempio è possibile passare i dati personalizzati dell'esercente che riguardano un'area di vendita utilizzando order.custom.salesRegion, dove 'salesRegion' può essere qualsiasi campo definito dall'esercente. I campi dei dati personalizzati vengono restituiti nella risposta e possono essere utilizzati per la creazione di report e l'analisi in base alle esigenze.
Questi dati non sono richiesti da Mastercard Gateway o dall'acquirer per elaborare la transazione e non si devono includere dati sensibili in nessuno dei campi dati personalizzati dell'esercente.
I dati personalizzati dell'esercente sono applicabili alle operazioni Authorize, Capture, Pay, Refund, Void, Verify, Referral, Update Authorization, Initiate Browser Payment, Confirm Browser Payment e Hosted Checkout.
Riferimento API per i dati personalizzati dell'esercente [REST][NVP]
È possibile inviare transazioni di debito al gateway se si è stati abilitati per almeno un metodo di finanziamento (CREDITO, DEBITO o ADDEBITO) dal proprio provider di servizi di pagamento. Se il gateway non è in grado di determinare il metodo di finanziamento per un'operazione di rimborso del debito, la transazione verrà rifiutata.
Quando invia un rimborso del debito, l'esercente deve fornire un indicatore del debito e potrebbe inoltre dover fornire ulteriori informazioni sul destinatario del pagamento. I dati del destinatario del pagamento includono informazioni aggiuntive sulla persona che riceve i fondi. Questi dati possono essere inviati all'acquirer e vengono utilizzati per valutare i rischi di pagamento e pertanto ridurre le transazioni fraudolente.
Oltre ai campi standard per una transazione Verify, Authorize o Pay, fornire i seguenti campi per avviare una transazione di rimborso del debito:
order.purchaseType
: Impostare questo campo su DEBT_REPAYMENT. Questo campo è obbligatoriodebtRepayment.paymentRecipient.accountIdentifier
debtRepayment.paymentRecipient.dateOfBirth
debtRepayment.paymentRecipient.lastName
debtRepayment.paymentRecipient.postcodeZip
I dati inviati vengono restituiti nella risposta di transazione — la data di nascita e l'identificativo del conto saranno oscurati.
Riferimento API indicatore di rimborso del debito[REST][NVP]
È possibile fornire dati sanitari come dati di voci per un ordine. I dati sanitari includono i dettagli delle voci relative agli acquisti in ambito medico come le spese oculistiche, odontoiatriche, farmacologiche, o di altro tipo, approvate. Questi dati devono essere forniti solo se applicabili e accettati dall'acquirer.
Se viene richiesto di inviare dati sanitari, è necessario fornire tutte le informazioni seguenti sulla voce sanitaria nella transazione.
Mastercard Gateway invia all'acquirer la somma degli importi per tutte le voci della stessa categoria di settore. L'importo di una voce è: (Item Unit Price + Item Unit Tax Amount) * Item Quantity
. All'acquirer verrà inviato un solo record per ciascuna categoria di settore.
La somma di tutti i valori della categoria di settore verrà inviata come importo delle voci per l'ordine. Se l'importo dell'ordine è diverso dall'importo delle voci, la transazione viene rifiutata.
I dati sanitari possono essere inviati nelle transazioni Authorize, Pay, Capture e Refund.
I dati del descrittore dell'estratto conto, noti anche some dati dinamici del descrittore, includono le informazioni di contatto fornite all'esercente per la stampa sugli estratti conto del pagante. Questi dati vengono inviati all'acquirer e si sovrappongono ai dati del descrittore registrati presso l'acquirer. Se si forniscono dati parziali del descrittore dell'estratto conto in una transazione, l'acquirer li completerà utilizzando i dati del descrittore registrati presso l'acquirer.
Se viene richiesto di inviare dati del descrittore dell'estratto conto, è possibile fornire le informazioni di contatto seguenti relative alla propria azienda nella transazione.
I dati inviati vengono restituiti nella risposta della transazione.
I dati del descrittore dell'estratto conto possono essere inviati solo nelle operazioni Authorize, Pay, Capture, Refund, Verify, Update Session e Pay with Session.
Riferimento API per i dati del descrittore dell'estratto conto[REST][NVP]
I dati di crociera includono informazioni sulla crociera e i passeggeri e possono anche includere dati relativi ad altri settori come la compagnia aerea o il noleggio auto se sono stati acquistati come parte di un pacchetto crociera.
Se viene richiesto di inviare dati di crociera, è possibile fornire le seguenti informazioni sulla crociera nella transazione.
cruise.bookingReference
cruise.company.address.*
campicruise.company.contact.customerServicePhone
cruise.company.contact.companyPhone
cruise.travelAgentCode
cruise.travelAgentName
cruise.travelPackageItems
cruise.departureDate
cruise.returnDate
cruise.shipName
cruise.passenger[n].*
campiI dati di crociera possono essere inviati nelle operazioni Authorize, Pay, Capture, Refund, Create Checkout Session e Update Session.
I dati inviati vengono restituiti nella risposta della transazione.
Se si è un esercente che invia transazioni che comportano l'acquisto di criptovalute o titoli ad alto rischio, è necessario informare l'issuer fornendo determinati indicatori nella richiesta di transazione al gateway.
Oltre ai campi standard per una transazione Verify, Authorize e Pay, fornire il campo order.purchaseType
per indicare una transazione di titoli ad alto rischio o di criptovalute. È possibile impostare i campi su uno dei seguenti valori:
CRYPTOCURRENCY
: Se si è un esercente con MCC 6051 (Quasi Cash—Istituti non finanziari-Valuta estera, Valuta non Fiat) e questa transazione è per l'acquisto di criptovaluta.HIGH_RISK_SECURITIES
: Se si è un esercente con MCC 6211 (Titoli - Brokers/Dealer) e questa transazione è per l'acquisto di titoli ad alto rischio.Riferimento API dei dati degli indicatori relativi a criptovalute e titoli ad alto rischio[REST][NVP]
Le transazioni che comportano l'addebito di denaro da un conto per accreditare un altro conto sono definite come transazioni di finanziamento del conto nel linguaggio del Mastercard Gateway. Il destinatario può essere la stessa persona, un'altra persona o un'organizzazione. Se l'utente è abilitato dall'organizzazione di servizi agli esercenti (MSO) per questa funzionalità, puoi facilitare i seguenti tipi di transazioni di finanziamento del conto per i propri clienti:
I dati sulle transazioni di finanziamento del conto (Account Funding Transaction, AFT) includono informazioni sul tipo di mittente, tipo di destinatario, tipo di conto del destinatario, metodo di finanziamento del conto e scopo del finanziamento. Possono includere anche altri dettagli sul destinatario. Quando viene richiesto di inviare i dati della transazione di finanziamento del conto, a seconda del tipo di transazione che si sta inviando, è necessario fornire alcune o tutte le informazioni sulla transazione indicate di seguito.
accountFunding.senderType:
Questo campo può assumere valori come PERSON, COMMERCIAL_ORGANIZATION, NON_PROFIT_ORGANIZATION e GOVERNMENT.accountFunding.senderIsRecipient:
Definisce se il mittente e il destinatario nella transazione di finanziamento del conto sono uguali o diversi.accountFunding.recipient.account.fundingMethod:
Questo campo può assumere valori come CHARGE, CREDIT e DEBIT. Se non viene fornito alcun valore, questo campo assume il valore predefinito, UNKNOWN.accountFunding.recipient.stateProvinceCode:
Il codice dello stato o della provincia del destinatario. Il valore deve corrispondere alla seconda parte del codice ISO 3166-2. Ad esempio:
accountFunding.recipient.account:
Dettagli sul conto del destinatario che successivamente riceverà i fondi che l'utente addebiterà al mittente in questa transazione.accountFunding.purpose:
Questo campo può assumere valori come CRYPTOCURRENCY_PURCHASE, MERCHANT_SETTLEMENT e PAYROLL. Se non viene fornito alcun valore, assume il valore predefinito, OTHER.accountFunding.recipient:
Dettagli sul destinatario che riceverà i fondi.accountFunding.recipient.account.identifierType:
Questo campo può assumere valori come CARD_NUMBER, BANK_ACCOUNT_NATIONAL, BANK_ACCOUNT_BIC, BANK_ACCOUNT_IBAN, EMAIL_ADDRESS, PHONE_NUMBER, SOCIAL_NETWORK_PROFILE_ID e STAGED_WALLET_USER_ID. Se non viene fornito alcun valore, assume il valore predefinito, OTHER.accountFunding.recipient.account.identifier:
L'identificativo del conto del destinatario del pagamento, ad esempio numero della carta o numero di conto corrente bancario.accountFunding.recipient.firstName:
Nome del destinatario del pagamentoaccountFunding.recipient.lastName:
Cognome del destinatario del pagamento.accountFunding.recipient.country:
Paese del destinatario del pagamento.accountFunding.recipient.postCodeZip:
CAP del destinatario del pagamento.accountFunding.recipient.dateOfBirth:
Data di nascita del destinatario del pagamento nel formato aaaa-mm-gg.accountFunding.reference:
Riferimento per la transazione di finanziamento del conto. Questo riferimento è generato da Mastercard Payment Gateway.I dati sulle transazioni di finanziamento del conto possono essere inviati nelle operazioni Authorize, Pay, Verify, Standalone capture, Standalone refund, Authenticate_Payer, Authorize, Capture, Refund, Create_Checkout_Session e Update Session. I dati inviati vengono restituiti nella risposta della transazione.
Riferimento all'API dei dati sulle transazioni di finanziamento del conto[REST][NVP]