Integration Types
Altre funzionalità
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
PayPal è una delle modalità di pagamento tramite browser supportate nel Mastercard Gateway. Questa pagina riporta i dettagli di integrazione specifici di PayPal, tra cui come configurare il conto business PayPal per accettare i pagamenti tramite il gateway, i requisiti del marchio e così via. Leggere le Linee guida per l'integrazione per il pagamento tramite browser prima di creare un'integrazione PayPal.
Se si è effettuata l'integrazione per utilizzare PayPal prima della versione 50 di DirectAPI, fare clic qui.
Per utilizzare PayPal come modalità di pagamento tramite il Mastercard Gateway, è necessario disporre di un conto business PayPal configurato per il gateway. Per informazioni dettagliate, vedere Configurazione del conto business PayPal.
Per effettuare l'iscrizione al conto business PayPal, fare clic qui.
Nelle sezioni che seguono viene illustrato come scegliere l'esperienza di checkout PayPal più adatta al sito Web dell'esercente.
PayPal consente ai paganti di eseguire il checkout nel sito Web dell'esercente in modo rapido e sicuro, permettendo loro di utilizzare il conto PayPal per il pagamento e, se lo desiderano, di fornire informazioni sulla spedizione. Con PayPal, i paganti iniziano e completano il processo di checkout nel sito Web dell'esercente.
Il gateway supporta due tipi di flussi di checkout PayPal — Checkout con PayPal e Paga con PayPal.
Il flusso di Checkout con PayPal consente di reindirizzare un pagante dal sito Web dell'esercente a PayPal tramite Checkout con PayPal.
Il diagramma riportato di seguito descrive il flusso di Checkout con PayPal in cui il pagante utilizza l'indirizzo di spedizione archiviato da PayPal. Il pagante rivede e conferma il pagamento nel sito Web dell'esercente.
Il flusso di checkout è il seguente:
Initiate Browser Payment
al gateway e il pagante viene reindirizzato all'URL di PayPal restituito nella risposta.Retrieve Transaction
. Confirm Browser Payment
di conferma pagamento tramite browser al gateway.
{ "apiOperation":"INITIATE_BROWSER_PAYMENT", "browserPayment":{ "operation":"AUTHORIZE", "paypal":{ "paymentConfirmation":"CONFIRM_AT_MERCHANT" }, "returnUrl":"Https://test.com" }, "order":{ "amount":"4.20", "currency":"USD" }, "sourceOfFunds":{ "type":"PAYPAL" } }
Il flusso Paga con PayPal consente al pagante di procedere con il normale flusso di checkout, immettendo le informazioni di fatturazione e di spedizione nel sito Web dell'esercente. Quando gli viene richiesto di scegliere una modalità di pagamento, il pagante sceglie l'opzione PayPal che si trova nella pagina di fatturazione del sito Web dell'esercente insieme alle altre opzioni di pagamento. A differenza di quanto accade per una transazione Checkout con PayPal, il sito Web dell'esercente fornisce l'indirizzo di spedizione del pagante a PayPal. Per impostazione predefinita, è possibile scegliere di non mostrare l'indirizzo di spedizione e/o di disabilitare le modifiche in PayPal. Vedere Mostra/Ignora indirizzo di spedizione di seguito per informazioni su come implementare questa opzione nell'integrazione PayPal. Il pulsante "Paga adesso" consente al pagante di confermare il pagamento in PayPal prima di essere reindirizzato al sito Web dell'esercente. Questa opzione permette di offrire un'esperienza di checkout più rapida al pagante, dal momento che il pagamento viene completato nel sito Web PayPal.
Il diagramma riportato di seguito descrive il flusso Paga con PayPal in cui il pagante verifica e conferma il pagamento in PayPal.
Il flusso di checkout è il seguente:
Initiate Browser Payment
al gateway e il pagante viene reindirizzato all'URL di PayPal restituito nella risposta.{ "apiOperation":"INITIATE_BROWSER_PAYMENT", "browserPayment":{ "operation":"PAY", "paypal":{ "paymentConfirmation":"CONFIRM_AT_PROVIDER" }, "returnUrl":"Https://test.com" }, "order":{ "amount":"4.20", "currency":"USD" }, "sourceOfFunds":{ "type":"PAYPAL" } }
Con entrambi i flussi Checkout con PayPal e Paga con PayPal, è possibile scegliere di visualizzare il pulsante "Paga adesso" o un pulsante "Continua" sul sito Web di PayPal.
Il pulsante "Paga adesso" consente al pagante di confermare il pagamento in PayPal prima di essere reindirizzato al sito Web dell'esercente. Questa opzione permette di offrire un'esperienza di checkout più rapida al pagante, dal momento che il pagamento viene completato nel sito Web PayPal.
Il pulsante "Continua" reindirizza il pagante al sito Web dell'esercente, dove potrà confermare il pagamento dopo avere esaminato tutti i dettagli dell'ordine. Questa opzione consente di modificare l'ordine, se necessario, prima di accettare il pagamento (ad esempio aggiungendo i costi di spedizione e trasporto in base all'indirizzo restituito da PayPal). Si possono anche includere altri passaggi di checkout, ad esempio l'upselling, nella pagina Conferma ordine.
Vedere Conferma di pagamento di seguito per i dettagli su come implementare questa opzione nell'integrazione PayPal.
A seconda del flusso di checkout, Checkout con PayPal o Paga con PayPal, è possibile scegliere di acquisire l'indirizzo di spedizione del pagante rispettivamente nel sito Web dell'esercente o in PayPal. Per impostazione predefinita, PayPal acquisisce l'indirizzo di spedizione dal pagante in PayPal dove, se necessario, il pagante può aggiungere un altro indirizzo o modificare quello esistente. È possibile scegliere di non visualizzare l'indirizzo di spedizione e/o di disabilitare le modifiche. Vedere Mostra/Ignora indirizzo di spedizione di seguito per informazioni su come implementare questa opzione nell'integrazione PayPal.
Se si sta usando la pagina di pagamento del Mastercard Gateway (Hosted Checkout) PayPal verrà automaticamente offerto come opzione di checkout ai paganti se il your payment service provider ha configurato il collegamento all'acquirer PayPal sul proprio profilo esercente. Per ulteriori dettagli, vedere Pagamenti tramite browser mediante integrazione Hosted Checkout.
Se si utilizza la versione API 50-59 per inviare la richiesta Create Checkout Session, il pagante verrà reindirizzato dal sito Web dell'esercente a PayPal per accedere e completare i dettagli di pagamento.
È possibile aggiungere PayPal come opzione di checkout sulla propria pagina di pagamento se si è effettuata l'integrazione alla versione API 50 o a una versione superiore. È necessario inviare la richiesta Initiate Browser Payment
dall'applicazione lato server per avviare l'interazione PayPal.
Il pagante viene reindirizzato dal sito Web dell'esercente a PayPal per accedere e completare i dettagli di pagamento. Per i dettagli, vedere PayPal tramite Direct Payment.
I campi riportati di seguito nella richiesta Initiate Browser Payment sono specifici di PayPal o hanno un uso specifico nell'integrazione di PayPal. Per ulteriori dettagli, vedere Pagamenti tramite browser mediante integrazione di pagamenti diretti.
sourceOfFunds.type = PAYPAL
browserPayment.operation
= AUTHORIZE
o PAY
Con PayPal, i fondi possono essere trattenuti per tre giorni (periodo d'onore) a partire da quando è avvenuta l'autorizzazione. Se si desidera ancora acquisire i fondi dopo 3 giorni, è possibile utilizzare l'operazione Update Authorization oppure avviare l'acquisizione mediante Merchant Administration.
browserPayment.paypal.paymentConfirmation
Quando si avvia un pagamento PayPal, è necessario specificare se si desidera che il pagante confermi il pagamento in PayPal o nel sito Web dell'esercente.
Riferimento API per il campo Conferma di pagamento [REST][NVP]
Se la conferma viene effettuata presso il provider (PayPal), in PayPal viene visualizzato il pulsante "Paga adesso" che consente al pagante di confermare il pagamento in PayPal prima di essere reindirizzato al sito Web dell'esercente. È necessario inviare una richiesta Retrieve Transaction
al Mastercard Gateway per stabilire se il pagamento è riuscito.
Se la conferma viene effettuata nel sito Web dell'esercente, in PayPal viene visualizzato il pulsante "Continua" che consente al pagante di essere reindirizzato al sito Web dell'esercente dove potrà confermare il pagamento. È necessario inviare una richiesta Retrieve Transaction
al gateway per recuperare i dettagli relativi all'eventuale prosecuzione del pagamento. Se il pagante continua con il pagamento nel sito Web dell'esercente, è necessario inviare una chiamata Confirm Browser Payment
per confermare il pagamento con PayPal. La risposta Confirm Browser Payment
conterrà informazioni sull'esito del pagamento.
Riferimento API per Confirm Browser Payment [REST][NVP]
In entrambi i casi, se il pagamento riesce, Retrieve Transaction restituisce:
{ "apiOperation":"CONFIRM_BROWSER_PAYMENT", "order":{ "amount":"4.20", "currency":"USD" } }
È possibile gestire il modo in cui il pagante fornisce l'indirizzo di spedizione utilizzando due campi:
browserPayment.paypal.displayShippingAddress
— se impostato su true (valore predefinito), l'indirizzo di spedizione viene visualizzato in PayPal.
Riferimento API campo Mostra indirizzo di spedizione [REST][NVP]
browserPayment.paypal.overrideShippingAddress
— se impostato su true (valore predefinito), il pagante può modificare l'indirizzo di spedizione in PayPal.
Riferimento API per il campo Ignora indirizzo di spedizione [REST][NVP]
Per impostazione predefinita, PayPal acquisisce automaticamente per l'esercente l'indirizzo di spedizione del pagante in PayPal. Se si sceglie di acquisire l'indirizzo di spedizione dal pagante nel sito Web dell'esercente e non si desidera che PayPal visualizzi l'indirizzo di spedizione al pagante, è necessario impostare browserPayment.paypal.displayShippingAddress
su false. Questo vale anche quando non è richiesto un indirizzo di spedizione per un ordine (ad esempio solo i prodotti digitali).
Il gateway restituirà sempre l'indirizzo di spedizione nella risposta Retrieve Transaction
se l'indirizzo è stato fornito nella richiesta Initiate Browser Payment
o se browserPayment.paypal.displayShippingAddress
è impostato su true.
Vedere la tabella di seguito per i vari scenari che potrebbero essere applicabili all'integrazione. È possibile scegliere uno scenario diverso per ciascun pagamento.
Initiate Browser Payment | PayPal | ||||||
---|---|---|---|---|---|---|---|
Mostra indirizzo di spedizione | Ignora indirizzo di spedizione | L'indirizzo di spedizione è richiesto? | L'indirizzo di spedizione è fornito? | L'indirizzo di spedizione è valido? | L'indirizzo di spedizione è visibile al pagante? | Origine dell'indirizzo di spedizione visualizzato | Il pagante può modificare l'indirizzo di spedizione? |
true (predefinito) | true (predefinito) | facoltativo | no | NA | sì | PayPal acquisisce l'indirizzo di spedizione. | sì |
true (predefinito) | true (predefinito) | facoltativo | sì | sì | sì | PayPal visualizza l'indirizzo di spedizione fornito nella richiesta in PayPal. | sì |
true (predefinito) | true (predefinito) | facoltativo | sì | no | sì | PayPal ignora l'indirizzo di spedizione fornito dall'esercente nella richiesta anziché acquisirlo in PayPal. | sì |
true (predefinito) | false | obbligatorio | sì | sì | sì | PayPal visualizza l'indirizzo di spedizione fornito nella richiesta in PayPal. | no |
true (predefinito) | false | obbligatorio | sì | no | no | PayPal rifiuta la richiesta. | Non applicabile |
false | Non applicabile | Non applicabile | sì | sì | no | PayPal ignora l'indirizzo di spedizione fornito nella richiesta. | no |
false | Non applicabile | Non applicabile | Non applicabile | Non applicabile | no | PayPal non ha un indirizzo di spedizione da visualizzare. | Non applicabile |
È possibile specificare i dettagli sulle voci nella richiesta Initiate Browser Payment
per fornire ai paganti tutti i dettagli dell'ordine prima di confermare il pagamento. Una ricerca di mercato ha rilevato che gli acquirenti sono più portati a completare gli acquisti se hanno l'opportunità di rivedere le singole voci e gli altri dettagli di un ordine durante il checkout PayPal. Pertanto è consigliabile fornire informazioni sull'ordine quando si avvia un checkout PayPal per incoraggiare i paganti a procedere con il pagamento anziché rinunciare all'acquisto.
Si considerano fornite le voci di cui sono specificati il nome o il prezzo per unità. Per ulteriori informazioni sui dettagli delle voci, vedere Dati voci.
Nella tabella che segue sono illustrati i possibili scenari per i codici di risposta di transazione restituiti dopo l'avvio di un pagamento tramite browser.
Risposta Initiate Browser Payment |
Cosa significa... |
---|---|
response.gatewayCode=SUBMITTED result=SUCCESS |
Reindirizzare il pagante utilizzando l'URL fornito nella risposta. |
response.gatewayCode=SUBMITTED result=FAILURE or PENDING or UNKNOWN |
Inviare un'altra richiesta INITIATE_BROWSER_PAYMENT . |
Risposta di Retrieve Transaction/Retrieve Order |
Cosa significa... |
response.gatewayCode=APPROVED result=SUCCESS |
Il pagamento è avvenuto correttamente. |
response.gatewayCode= PENDING result=PENDING |
Il pagamento attende una verifica nel sistema PayPal. Vedere Pagamenti in sospeso. |
response.gatewayCode= CANCELLED result=FAILURE |
Il pagante ha annullato l'interazione per il pagamento. Offrire al pagante la possibilità di provare ad utilizzare un'altra modalità di pagamento. |
response.gatewayCode= DECLINED or INSUFFICIENT_FUNDS or NOT_SUPPORTED result=FAILURE |
Il pagamento è stato rifiutato da PayPal. |
response.gatewayCode= ACQUIRER_SYSTEM_ERROR result=FAILURE |
L'acquirer non è riuscito a elaborare la transazione. È possibile richiedere all'acquirer il motivo dell'esito negativo del pagamento, oppure riprovare RETRIEVE_TRANSACTION . In alternativa, è possibile offrire al pagante la possibilità di provare ad utilizzare un'altra modalità di pagamento. |
response.gatewayCode= SYSTEM_ERROR result=FAILURE |
Il gateway non è riuscito a elaborare la transazione. |
response.gatewayCode=TIMED_OUT result=FAILURE |
L'interazione tra il pagante e il sistema PayPal non è stata completata correttamente, ad esempio nel caso in cui il gateway non ha ricevuto un reindirizzamento del browser del pagante dall'esercente entro 24 ore o se il gateway non è riuscito a richiamare i dettagli dell'interazione tra il pagante e il sistema PayPal e pertanto il pagamento non è stato completato. |
response.gatewayCode=UNKNOWN result=UNKNOWN |
Il gateway non è riuscito a verificare l'esito del pagamento. |
È possibile aggiornare il periodo d'onore dell'autorizzazione e/o incrementare gli importi dell'autorizzazione per transazioni di autorizzazione PayPal valide utilizzando l'operazione Update Authorization o tramite Merchant Administration. 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.
È consigliabile aggiornare un'autorizzazione dopo i primi tre giorni (periodo d'onore) per assicurarsi che i fondi siano ancora disponibili Il pagamento ri-autorizzato ora ha un nuovo periodo d'onore di 3 giorni. Il periodo d'onore di 3 giorni può essere aggiornato al massimo una volta entro il periodo di validità di 29 giorni.
È possibile aggiornare l'autorizzazione una sola volta fino ad un massimo del 115% o di USD $75 dell'importo autorizzato originariamente.
Per i pagamenti PayPal, è possibile acquisire l'importo autorizzato in parte o completamente rispetto all'importo autorizzato originariamente utilizzando l'operazione Capture o tramite Merchant Administration.
È possibile rimborsare completamente o parzialmente le transazioni Pay e Capture elaborate mediante PayPal. È possibile inviare richieste Refund utilizzando l'operazione Refund o tramite Merchant Administration.
È possibile annullare una transazione di autorizzazione aperta se i tentativi di acquisizione non sono riusciti oppure è possibile annullare una transazione Pay per annullare il pagamento. È possibile inviare una richiesta di annullamento utilizzando l'operazione Void o tramite Merchant Administration.
Il gateway può restituire lo stato PENDING nella risposta della transazione. È il caso ad esempio di una transazione attualmente sottoposta alla stima del rischio da parte di PayPal. Se lo stato è in sospeso e se sono stati configurati filtri di gestione delle frodi personalizzati, è necessario accedere al proprio conto business PayPal e rivedere il pagamento. PayPal notificherà al gateway quando lo stato di una transazione in sospeso verrà aggiornato da PayPal.
Se non si desidera effettuare una verifica e si desidera rifiutare i pagamenti in sospeso, è possibile avviare un rimborso. È possibile recuperare il risultato della transazione aggiornata utilizzando l'operazione Retrieve Transaction
.
Utilizzando Checkout con PayPal o Paga con PayPal, è possibile impostare un accordo di fatturazione con un pagante che consente di avviare una transazione di riferimento (pagamenti di sottoscrizione/periodici o su richiesta) associati all'accordo di fatturazione senza ulteriori consensi da parte del pagante. Per ulteriori informazioni, vedere Accordo di fatturazione e pagamenti periodici.
Questa sezione descrive come configurare l'integrazione di PayPal con il Mastercard Gateway. Una volta creato il conto PayPal, è necessario fornire i dati del conto (ID del conto PayPal) al provider di servizi di pagamento per consentire l'impostazione del profilo dell'esercente sul gateway di pagamento per PayPal.
Le organizzazioni di servizi agli esercenti possono configurare più collegamenti all'acquirer per l'esercente tramite il portale di Merchant Manager, nella sezione Dettagli del collegamento all'acquirer.
Per elaborare le transazioni tramite PayPal, è necessario accedere a Merchant Administration e concedere le autorizzazioni al Mastercard Gateway per le chiamate API specifiche che il Mastercard Gateway deve eseguire per conto dell'esercente.
Una volta sulla pagina Configurazione PayPal, è possibile visualizzare i link all'acquirer PayPal che l'organizzazione di servizi agli esercenti ha configurato per l'esercente. Se l'autorizzazione di terze parti non viene concessa per un collegamento all'acquirer, il campo ID conto sarà vuoto.
Per concedere autorizzazioni di terze parti per le API PayPal con un nuovo account e-mail:
La pagina di conferma della registrazione mostra le istruzioni per attivare il conto PayPal.
Vengono concesse le autorizzazioni di terze parti necessarie per lo specifico collegamento all'acquirer PayPal. Lo stato viene abilitato e viene visualizzato l'ID del conto PayPal.
Se, a causa di qualsiasi problema, l'autorizzazione di terze parti non riesce, viene visualizzato un messaggio di errore.
Per concedere autorizzazioni di terze parti per le API PayPal con un account e-mail registrato:
La registrazione e l'integrazione PayPal con il sito Web di prova della società TNS sono avvenute correttamente.
Vengono concesse le autorizzazioni di terze parti necessarie per lo specifico collegamento all'acquirer PayPal. Lo stato viene abilitato e viene visualizzato l'ID del conto PayPal.
Se, a causa di qualsiasi problema, l'autorizzazione di terze parti non riesce, viene visualizzato un messaggio di errore.
È possibile inviare ulteriori dati del pagante nel file Initiate Browser Payment
e nelle successive richieste Pay o Authorize dopo l'esecuzione di Tokenize Browser Payment
per consentire a PayPal di eseguire la stima del rischio della transazione prima che la transazione venga elaborata.
I dati nei seguenti campi sono utilizzati da PayPal per eseguire una valutazione della gestione del rischio pre-transazione:
device.fingerprint
: Un identificativo univoco per il dispositivo che può essere generato utilizzando la libreria JavaScript FraudNet di PayPal. Ciò consente a PayPal di eseguire la stima del rischio della transazione. risk.custom
: è possibile fornire ulteriori dati sul pagamento in questo campo. È necessario aver siglato un accordo con PayPal sui valori che si desidera fornire. Ad esempio, risk.custom.headOfficeLocation
= Londra, Regno Unito.sourceOfFunds.token
: l'ID del token dell'accordo che identifica i dettagli dell'accordo di fatturazione (ricevuti da PayPal) sul gateway. È possibile utilizzare questo ID del token per pagamenti singoli o periodici. Per ulteriori informazioni, vedere Accordo di fatturazione e pagamenti periodici.I rimborsi in eccesso devono essere abilitati sul sito PayPal. È possibile acquisire l'importo autorizzato in eccesso tramite la richiesta Capture o Merchant Administration.
È possibile effettuare un'acquisizione in eccesso fino ad un massimo del 115% della transazione autorizzata originariamente. È possibile rimborsare i pagamenti in eccesso per le transazioni Pay e Capture elaborate mediante PayPal.
È possibile inviare richieste Refund utilizzando l'operazione Refund o tramite Merchant Administration.
Per un rimborso in eccesso, includere un importo in eccesso rispetto all'importo originale della transazione. Per effettuare un rimborso in eccesso rispetto all'importo acquisito, verificare di essere abilitati per i rimborsi in eccesso sul profilo dell'esercente PayPal.
Se il proprio profilo PayPal è abilitato per i rimborsi in eccesso, assicurarsi di configurare il proprio Mastercard Gateway profilo dell'esercente per tale opzione.
Per informazioni sulle procedure ottimali per la sicurezza, fare clic qui.
Il Mastercard Gateway fornisce un simulatore PayPal che consente di verificare l'integrazione per l'utilizzo della funzionalità PayPal tramite il gateway.