Integration Types
Altre funzionalità
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
Se si è effettuata l'integrazione al gateway tramite DirectAPI, è possibile usare operazioni DirectAPI per elaborare le transazioni, recuperare i dettagli della transazione, memorizzare i dettagli della carta, ecc. Per eseguire un'operazione, è necessario disporre del privilegio richiesto sul profilo dell'esercente sul gateway. Per verificare quali operazioni sono disponibili per l'utilizzo, contattare il your payment service provider.
In questa sezione sono descritte le operazioni che è possibile utilizzare per avviare una transazione.
L'operazione Authorize verifica i dettagli della carta di credito del pagante, controlla che il pagante abbia a disposizione fondi sufficienti rispetto alla sua linea di credito e prova a riservare i fondi richiesti. Il limite di credito del pagante viene ridotto dell'importo autorizzato e i fondi vengono riservati per un intervallo di tempo prestabilito (nella maggior parte dei casi 5-8 giorni), in base a quanto stabilito dal circuito della carta di credito e dalle regole di emissione della carta del pagante.
L'autorizzazione non addebita fondi dal conto del pagante ma riserva l'importo totale dell'ordine per consentire all'operazione Capture di addebitare la carta e trasferire i fondi sul proprio conto. Nell'estratto conto del pagante non vengono visualizzate le transazioni Authorize, al contrario di quanto accade per le transazioni Capture.
Per un'autorizzazione eseguita correttamente, il gateway restituisce il risultato=SUCCESS nella risposta della transazione. È possibile eseguire Authorize come operazione successiva solo se la transazione iniziale è Verify e i dettagli della carta di credito nella richiesta Authorize e nella transazione Verify corrispondono.
L'operazione Authorize è nota anche come "Aut", "autorizzazione".
È possibile indicare un livello di certezza sull'importo dell'autorizzazione che verrà acquisito specificando il campo order.certainty
nella richiesta Authorize. A tale fine, il privilegio "Change Order Certainty" deve essere abilitato sul profilo dell'esercente dal your payment service provider. È possibile impostare i campi su uno dei seguenti valori:
La richiesta viene rifiutata se non si dispone del privilegio per modificare il livello di certezza dell'ordine e il valore fornito in questo campo non corrisponde al livello di certezza predefinito configurato nel profilo dell'esercente.
Riferimento API per Authorize [REST][NVP]
Il gateway può revocare gli importi di autorizzazione in sospeso per autorizzazioni non acquisite, parzialmente acquisite o scadute, se supportato per l'acquirer. Ciò consente di soddisfare i requisiti del circuito della carta per le revoche complete e parziali.
Se non si desidera riscuotere l'importo autorizzato dopo aver inviato una richiesta Authorize, è necessario annullare la propria autorizzazione inviando una richiesta VOID. Fornire l'ID della transazione per l'annullamento dell'autorizzazione nel campo transaction.targetTransactionId
.
Quando si inoltra una richiesta Capture per un ordine, è possibile fornire un importo di acquisizione inferiore all'importo autorizzato per l'ordine (order.AuthorizedAmount
). Se non si intende acquisire l'importo autorizzato rimanente, è possibile annullare l'Importo autorizzato in sospeso, se supportato per l'acquirer.
È possibile tentare di annullare/revocare l'importo dell'autorizzazione in sospeso in due modi:
transaction.targetTransactionId
.order.expectedNumberOfCaptures
nella richiesta Capture o tramite Merchant Administration. Nel caso in cui il numero complessivo di acquisizioni per l'ordine (inclusa l'attuale acquisizione) superi o sia pari al numero complessivo previsto di richieste Capture, il gateway automaticamente attiverà un annullamento dell'importo autorizzato in sospeso, laddove tale funzionalità sia supportata per l'acquirer. A tal fine, il privilegio "Revoca automaticamente gli importi delle autorizzazioni in sospeso" deve essere abilitato sul profilo dell'esercente dal your payment service provider.order.expectedNumberOfCaptures
=2 nella prima richiesta Capture, il gateway inverte automaticamente l'importo autorizzato rimanente durante l'elaborazione della seconda richiesta Capture.order.expectedNumberOfCaptures
=1 nella seconda richiesta Capture, il gateway revoca automaticamente l'importo autorizzato rimanente durante l'elaborazione della seconda richiesta Capture. Ciò avviene perché 2 (il numero totale di acquisizioni per l'ordine, inclusa l'acquisizione corrente) supera 1 (il numero previsto di acquisizioni). Tuttavia, se si incrementa il numero previsto di acquisizioni nelle successive richieste Capture, ad es. aggiornamento order.expectedNumberOfCaptures
=3 nella seconda richiesta Capture, il gateway non revocherà l'importo in sospeso fino alla ricezione della terza richiesta Capture.order.expectedNumberOfCaptures
può essere inviato solo a partire dalla versione 44 di DirectAPI.Le autorizzazioni hanno un periodo di validità oltre il quale scadono. Il periodo di validità dell'autorizzazione può essere configurato nel gateway per un acquirer, un tipo di carta e una combinazione di certezza dell'ordine.
Quando si invia una richiesta Authorize al gateway, il gateway determina la data e ora di scadenza in base al periodo di validità dell'autorizzazione configurato (utilizzando la combinazione di acquirer, tipo di carta e certezza dell'ordine). Se supportata per l'acquirer, la scadenza dell'autorizzazione viene restituita nel campo authorizationResponse.autoExpiry
nella risposta dell'operazione Retrieve Transaction
. Il campo contiene la data e l'ora in cui il gateway farà scadere automaticamente l'autorizzazione.
Dopo la scadenza del periodo di autorizzazione, il gateway:
Se l'ordine è stato parzialmente acquisito e se l'acquirer supporta l'annullamento delle autorizzazioni per acquisizioni parziali, il gateway cercherà di annullare/revocare l'importo con autorizzazione in sospeso.
Il gateway consente di estendere il periodo di autorizzazione e, facoltativamente, aumentare o diminuire l'importo dell'autorizzazione per le autorizzazioni valide, ove supportato per l'acquirer. A tale fine, il privilegio "Update Authorization" deve essere abilitato sul profilo dell'esercente dal your payment service provider. Per ulteriori informazioni, vedere Update Authorization
Il gateway consente di rinviare un'autorizzazione se non è possibile inviare una transazione Authorize o Pay nel momento in cui è stata completata con il pagante. L'errore potrebbe essere dovuto a problemi di connettività o di sistema o ad altre limitazioni che richiedono di posticipare l'invio fino a quando il sistema non è tornato online. L'identificazione delle autorizzazioni differite è obbligatoria per soddisfare i requisiti del circuito Visa.
Di seguito sono elencati alcuni scenari in cui è necessario indicare l'autorizzazione come autorizzazione differita per i pagamenti con carta Visa:
Per rinviare un'autorizzazione, fornire il campo transaction.deferredAuthorization
nella richiesta Authorize, Pay o Standalone Capture e impostare il relativo valore su TRUE. Se non si fornisce questo campo, il valore predefinito sarà impostato su FALSE.
Per gli esercenti di trasporto, l'autorizzazione inviata per l'importo aggregato alla fine del periodo di viaggio per tutti i pagamenti entro un periodo di viaggio, deve essere contrassegnata come differita. Per ulteriori informazioni, vedere Pagamenti aggregati di tariffe di trasporto.
Per acquisire un importo più elevato di quello autorizzato per un ordine, il profilo dell'esercente sul gateway deve essere abilitato per il privilegio di acquisizione in eccesso. Vedere Acquisizioni in eccesso
Sì, questa richiesta è chiamata Standalone Capture e, se supportata per l'acquirer, è sufficiente inviare una richiesta Capture con il codice dell'autorizzazione restituito dall'acquirer (nella risposta di autorizzazione).
L'operazione Pay combina in modo efficace un'operazione Authorize e un'operazione Capture in un unico messaggio. Una singola transazione autorizza il pagamento e trasferisce i fondi dal conto del pagante a quello dell'esercente.
Se si desidera inviare Pay come operazione successiva, è necessario disporre di una transazione di verifica effettuata correttamente e che i dettagli della carta di credito nella richiesta Pay e nella transazione Verify corrispondano.
Il livello di certezza dell'ordine per una transazione Pay è impostato su FINAL. Per ulteriori informazioni, vedere Certezza dell'ordine.
Pay è nota anche come "Vendita", "Acquisto".
Initiate Browser Payment
. Per ulteriori informazioni, vedere Implementazione dell'integrazione dei pagamenti tramite browser.Riferimento API per Pay [REST][NVP]
Auto-capture è una variante dell'operazione Pay che consente a un esercente con un privilegio per eseguire una transazione "Pay" e utilizzando un acquirer che supporta solo la modalità di transazione Authorize/Capture di eseguire un'operazione Authorize seguita da un'operazione Capture attivata automaticamente. Con questo tipo di transazione, una richiesta Pay viene trasformata in operazioni Authorize e Capture.
Questa operazione può essere eseguita utilizzando i modelli di integrazione Direct Payment, Hosted Session o Batch.
L'identificativo di transazione per entrambe le richieste, Authorize e Capture, sarà l'identificativo di transazione fornito dall'esercente nella richiesta Pay originale. Nella risposta Pay, il campo transaction.type
indicherà l'ultimo tentativo di transazione eseguito per soddisfare la richiesta, ad esempio Authorize o Capture.
È possibile utilizzare l'operazione Retrieve per recuperare i risultati di un'operazione Auto-capture. Vengono restituiti i risultati dell'ultimo tentativo di transazione eseguito per soddisfare la richiesta.
È possibile annullare una transazione Pay acquisita automaticamente utilizzando l'operazione Void Pay. Quando si esegue questa operazione, il Mastercard Gateway:
È possibile fornire un indicatore nella richiesta Pay per posticipare l'autorizzazione. Per ulteriori informazioni, vedere Autorizzazioni differite.
L'operazione Verify consente di verificare i dettagli del conto del pagante prima di eseguire una transazione Pay o Authorize. Essa verifica i dettagli di pagamento utilizzando il metodo di verifica supportato dall'acquirer. Ad esempio se l'acquirer supporta il servizio AVS (Address Verification Service), Verify invia una transazione AVS Only con importo zero e i dettagli dell'indirizzo del pagante.
Una transazione di Standalone Capture è una transazione Capture in cui l'autorizzazione è stata eseguita esternamente al gateway. Quando si invia Standalone Capture al gateway, è necessario fornire il codice di autorizzazione generato esternamente nel campo transaction.authorizationCode
e gli altri campi obbligatori.
È possibile inviare Standalone Capture se si dispone del privilegio Capture abilitato sul proprio profilo dell'esercente.
Riferimento API per Standalone Capture [REST][NVP]
È possibile fornire un indicatore nella richiesta Standalone Capture per posticipare l'autorizzazione. Per ulteriori informazioni, vedere Autorizzazioni differite.
Una transazione Standalone Refund è una transazione Refund che consente di trasferire fondi dal proprio conto a quello del pagante, senza un acquisto precedente. È possibile effettuare un rimborso autonomo quando si desidera procedere a un accredito sul conto del pagante senza associare il credito a una transazione precedente.
L'operazione di esborso consente di inviare fondi sul conto della carta di un pagante quando richiesto, ad esempio per giochi o vincite di scommesse o quando si paga l'importo della carta di credito di un pagante. Quando si esegue un esborso, i dettagli di fatturazione e spedizione del pagante non sono richiesti e la validazione del codice di sicurezza della carta (CSC) non è applicabile. Un esborso può essere eseguito senza transazioni precedenti o dopo aver verificato i dettagli del conto del pagante.
In questa sezione sono descritte le operazioni che è possibile eseguire sulle transazioni iniziali, Authorize o Pay.
Per verificare quali operazioni sono configurate sul proprio profilo dell'esercente contattare il your payment service provider.
L'operazione Update Authorization consente di:
Se si desidera solo estendere il periodo di autorizzazione, non inviare transaction.amount
nella richiesta. La data di scadenza dell'autorizzazione aggiornata viene restituita nel campo authorizationResponse.autoExpiry
nella risposta Retrieve Transaction
. Si consiglia di inviare la richiesta Update Authorization
entro il periodo di validità dell'autorizzazione originale.
Se l'importo della transazione fornito è superiore all'importo dell'autorizzazione esistente, l'importo dell'autorizzazione viene aggiornato al nuovo importo. Ad esempio, se l'importo dell'autorizzazione esistente è di 100 USD e si fornisce un importo di transazione per l'ordine di 120 USD nella richiesta Update Authorization
, allora il nuovo importo dell'autorizzazione disponibile per l'acquisizione sarà di 120 USD.
Se l'importo della transazione fornito è inferiore all'importo dell'autorizzazione esistente, l'importo dell'autorizzazione viene aggiornato al nuovo importo. Ad esempio, se l'importo dell'autorizzazione esistente è di 100 USD e si fornisce un importo di transazione per l'ordine di 80 USD nella richiesta Update Authorization, allora il nuovo importo dell'autorizzazione disponibile per l'acquisizione sarà di 80 USD. Il gateway elabora automaticamente una richiesta di revoca per l'importo rimanente con autorizzazione di 20 USD (se supportata per l'acquirer).
Nota: il gateway può aggiornare un'autorizzazione esistente solo se sono soddisfatte le condizioni seguenti:
Dopo una richiesta Update Authorization con esito positivo (per una carta o PayPal), l'importo dell'ordine (order.amount
) e l'importo totale autorizzato (order.totalAuthorizedAmount
) vengono aggiornati all'importo della transazione (transaction.amount
) Update Authorization. E questo vale indipendentemente dal fatto che la transazione Update Authorization sia stata inviata all'acquirer o approvata automaticamente dal gateway (response.gatewayCode=APPROVED_AUTO
). Tuttavia, se si decide di evitare l'aggiornamento dell'autorizzazione per una richiesta di acquisizione in eccesso (inviando transaction.authorizationAdjustmentActions=NO_ACTION
, vedere Acquisizioni in eccesso) e il gateway invia un'acquisizione in eccesso all'acquirer, i totali dell'ordine NON vengono aggiornati.
response.gatewayCode=APPROVED_AUTO
) è applicabile solo quando l'importo fornito è superiore all'importo dell'autorizzazione esistente. È possibile fornire i seguenti totali parziali nella richiesta Update Authorization per i pagamenti con carta di credito o PayPal:
order.itemAmount
order.shippingAndHandlingAmount
order.taxAmount
order.discount.amount
(solo pagamenti con carta di credito)order.gratuityAmount
(solo pagamenti con carta di credito)order.cashbackAmount
nella richiesta Update Authorization non è supportato.Il gateway NON convalida se gli importi del subtotale si sommano al transaction.amount
(cioè,order.amount
); tuttavia, è necessario accertarsene per i pagamenti PayPal.
È possibile aggiornare un importo dell'addizionale nella richiesta Update Authorization utilizzando uno dei seguenti campi:
order.surchargeAmount
: utilizzare questo campo se si fornisce un importo dell'addizionale pre-calcolato.order.netAmount
: utilizzare questo campo se il gateway calcola l'importo dell'addizionale (in base alle regole di applicazione dell'addizionale).order.surchargeAmount
non è supportato e le richieste con questo campo verranno rifiutate. Se si fornisce order.netAmount
su un pagamento PayPal, la transazione verrà elaborata senza applicare un'addizionale.L'operazione Capture usa l'autorizzazione ottenuta dopo la transazione Authorize iniziale per trasferire i fondi dal conto del pagante a quello dell'esercente. L'operazione Capture deve essere sempre preceduta da un'autorizzazione eseguita correttamente e con la richiesta Capture deve essere inviato almeno l'ID di autorizzazione. La valuta utilizzata quando si acquisisce un importo deve corrispondere alla valuta utilizzata nella transazione di autorizzazione.
Le acquisizioni vengono di solito raggruppate dal gateway o dall'host dell'acquirer, pertanto i fondi non vengono trasferiti in modo efficace fino a quando il batch non è chiuso e non si verifica il trasferimento dei fondi.
Capture è nota anche come "Bill", "Complete".
L'importo totale acquisito può superare l'importo originale autorizzato, se per il proprio profilo dell'esercente è abilitato il privilegio di acquisizione in eccesso.
Acquisizione in eccesso è una variante dell'acquisizione che consente all'esercente di eseguire acquisizioni per importi superiori all'importo autorizzato. L'eccesso consentito è specificato come percentuale dell'importo autorizzato originale ed è determinato dal your payment service provider
Quando si invia una richiesta di acquisizione in eccesso, il gateway cerca di aggiornare automaticamente l'importo dell'autorizzazione all'importo che si desidera acquisire. Se l'acquirer supporta l'aggiornamento delle autorizzazioni, il gateway invia la richiesta Update Authorization all'acquirer. In caso contrario, il gateway cerca di approvare automaticamente un aggiornamento dell'autorizzazione (fino al limite di acquisizione in eccesso configurato per il profilo dell'esercente).
Inviare transaction.authorizationAjustmentAction=NO_ACTION
nella richiesta Capture se non si desidera che Il gateway cerchi di aggiornare l'autorizzazione prima di inviare la richiesta Capture all'acquirer. Nota: se il valore dell'autorizzazione non corrisponde all'acquisizione, l'ordine potrebbe non beneficiare della protezione chargeback.
Se si desidera acquisire parzialmente un'autorizzazione e per altre informazioni correlate, vedere le Domande frequenti.
Refund consente di riaccreditare fondi sul conto del pagante per un ordine esistente. Questa operazione può essere eseguita solo quando è stato completato un trasferimento di fondi attraverso un'operazione Pay o Capture. È possibile eseguire un numero qualsiasi di transazioni di rimborso sulla transazione originale, ma non è possibile rimborsare più del totale ottenuto mediante tutte le transazioni di acquisto o acquisizione associate all'ordine.
I rimborsi vengono eseguiti per molti motivi, ad esempio per la restituzione di merce indesiderata, non corretta o difettosa.
Prima di inviare la richiesta di rimborso all'acquirer per la compensazione e il trasferimento fondi, per impostazione predefinita, il gateway tenta automaticamente di autorizzare il rimborso con l'issuer (se supportato dall'acquirer). Ciò consente agli issuer di verificare i dettagli della carta forniti nella richiesta di rimborso per garantire che il rimborso vada a buon fine.
L'autorizzazione al rimborso viene eseguita online e restituisce una risposta in tempo reale. Questo ha molti vantaggi:
Se non si desidera che il gateway invii una richiesta di autorizzazione per i rimborsi, è necessario essere abilitati per il privilegio "Abilita rimborsi senza autorizzazioni". Anche quando questo privilegio è abilitato, è possibile richiedere l'autorizzazione sui rimborsi impostando il campo action.refundAuthorization
= true
nella richiesta API per Refund.
Se l'autorizzazione al rimborso ha esito positivo, il server di pagamento procede al rimborso, altrimenti il rimborso viene rifiutato. L'esito della transazione di rimborso viene restituito nella risposta di transazione. Verrà visualizzato il codice di autorizzazione ricevuto dall'issuer Merchant Administration.
L'importo totale rimborsato per un ordine può superare l'importo acquisito se per il proprio profilo dell'esercente è abilitato il privilegio di rimborso in eccesso.
L'eccesso consentito rispetto all'importo acquisito per le transazioni DirectAPI può essere configurato in base alla valuta nelle Impostazioni di integrazione in Merchant Administration. Se non si imposta un limite di rimborso in eccesso per una valuta, i rimborsi in eccesso per gli ordini in questa valuta vengono rifiutati.
Quando si invia un rimborso, l'importo totale rimborsato per l'ordine (comprensivo del rimborso tentato) non deve superare l'importo totale acquisito per l'ordine di un valore superiore all'eccesso massimo consentito. Se ad esempio si invia un rimborso in eccesso mediante DirectAPI per un ordine in cui l'importo totale acquisito è $100 USD e il limite di rimborso in eccesso per le transazioni DirectAPI è impostato su $20 USD, è possibile rimborsare fino a $120 USD.
L'operazione di esborso consente di inviare fondi sul conto della carta di un pagante quando richiesto, ad esempio per giochi o vincite di scommesse o quando si paga l'importo della carta di credito di un pagante. Quando si esegue un esborso, i dettagli di fatturazione e spedizione del pagante non sono richiesti e la validazione del codice di sicurezza della carta (CSC) non è applicabile. Un esborso può essere eseguito senza transazioni precedenti o dopo aver verificato i dettagli del conto del pagante.
Retrieve Transaction consente di recuperare i dettagli di una transazione utilizzando l'ID ordine e l'ID transazione. Sono richiesti entrambi, in quanto l'ID transazione identifica una transazione in un ordine.
Retrieve Order consente di recuperare i dettagli di un ordine e di tutte le transazioni associate.
Void prova a eliminare/revocare immediatamente una richiesta di transazione. Gli annullamenti possono essere eseguiti solo sulle transazioni che non sono state ancora inviate alla banca dall'acquirer per essere elaborate a fine giornata. Dopo che una transazione è stata inviata dall'acquirer per l'elaborazione, è necessario eseguire un'operazione Refund anziché un'operazione Void.
È possibile annullare una transazione Authorize, Capture, Pay o Refund. Un annullamento eseguito su un'operazione Authorize rilascerà immediatamente i fondi riservati. In tutti gli altri tipi di transazione, l'annullamento impedirà il trasferimento fondi.
L'operazione Referral invia nuovamente una transazione iniziale segnalata (transazione di autorizzazione o Pay che ha ricevuto una risposta dell'acquirer "Refer to Issuer") come nuova transazione Authorization o Pay con un codice di autorizzazione ottenuto dall'issuer.
È possibile che venga richiesto al pagante di fornire informazioni aggiuntive per consentire all'issuer di approvare la transazione e fornire un codice di autorizzazione o un ID di autorizzazione manuale.
Un chargeback avviene quando un pagante contesta un pagamento ad un esercente, Ad esempio, la merce non è stata ricevuta o il pagante non ha autorizzato il pagamento all'esercente. Il Your payment service provider potrebbe scegliere di importare i dettagli delle transazioni di chargeback nel gateway in modo che siano disponibili per scopi di ricerca e creazione di report. Il Your payment service provider può scegliere di registrare ogni transazione di riaddebito rispetto all'ordine originale o creare un nuovo ordine con una transazione di chargeback autonoma.
Il gateway può creare più transazioni chargeback per un singolo ordine. È possibile eseguire transazioni successive su un ordine contenente una transazione chargeback, ad esempio annullamenti e rimborsi.
Una transazione chargeback registrata correttamente restituirà i seguenti campi nella risposta Retrieve Transaction
/Retrieve Order
:
order.status
=CHARGEBACK_PROCESSED
oppure DISPUTED
: quando viene creata una transazione di chargeback, lo stato dell'ordine corrispondente viene aggiornato per indicare che il pagante ha sollevato una contestazione.
order.status
=DISPUTED
indica che è stata sollevata una contestazione ma non è stato ancora effettuato alcun trasferimento fondi.order.status
=CHARGEBACK_PROCESSED
indica che è stato elaborata una contestazione di chargeback e che i fondi verranno trasferiti dal o al conto dell'esercente.order.chargeback.amount
order.chargeback.currency
transaction.dispute
: gruppo di parametri: informazioni sulla contestazione di chargeback, ad esempio evento oggetto della contestazione, data, ecc. transaction.type
=CHARGEBACK
transaction.source
=SERVICE_PROVIDER
gatewayEntryPoint
=SERVICE_PROVIDER_API