Per gestire una carta di pagamento a garanzia con PayPal, le funzionalità principali che puoi utilizzare sono:
Panoramica della Soluzione:
A seconda del tuo caso d'uso specifico, potresti scegliere uno di questi approcci o una combinazione.
Un esempio di come utilizzare la funzionalità di Autorizzazione e Acquisizione con le API di PayPal con PHP. Tieni presente che questo è un esempio semplificato per illustrare il concetto. L'implementazione reale richiederà l'installazione della libreria SDK di PayPal per PHP e una gestione degli errori più robusta.
Panoramica:
L'esempio che ti mostrerò simula i seguenti passaggi:
Prerequisiti:
composer require paypal/rest-api-sdk-php<?php
require 'vendor/autoload.php';
// *** CONFIGURAZIONE ***
$clientId = 'IL_TUO_CLIENT_ID'; // Sostituisci con il tuo Client ID
$clientSecret = 'IL_TUO_CLIENT_SECRET'; // Sostituisci con il tuo Client Secret
// Imposta l'ambiente (sandbox o live)
$apiContext = new \PayPal\Rest\ApiContext(
new \PayPal\Auth\OAuthTokenCredential(
$clientId,
$clientSecret
)
);
// Per l'ambiente Sandbox, imposta:
$apiContext->setConfig(
array(
'mode' => 'sandbox'
)
);
// Per l'ambiente Live, rimuovi o commenta la riga sopra.
// *** CREAZIONE DELL'AUTORIZZAZIONE ***
$payer = new \PayPal\Api\Payer();
$payer->setPaymentMethod("paypal"); // Puoi usare "credit_card" se hai i dettagli della carta
$amount = new \PayPal\Api\Amount();
$amount->setCurrency("EUR") // Sostituisci con la tua valuta
->setTotal("25.00"); // L'importo da autorizzare
$transaction = new \PayPal\Api\Transaction();
$transaction->setAmount($amount)
->setDescription("Autorizzazione per un ordine.");
$redirectUrls = new \PayPal\Api\RedirectUrls();
$redirectUrls->setReturnUrl("http://localhost:8000/execute-payment.php?success=true") // URL di ritorno dopo l'approvazione
->setCancelUrl("http://localhost:8000/execute-payment.php?success=false"); // URL di cancellazione
$payment = new \PayPal\Api\Payment();
$payment->setIntent("authorize") // Imposta l'intent su "authorize"
->setPayer($payer)
->setRedirectUrls($redirectUrls)
->setTransactions(array($transaction));
try {
$payment->create($apiContext);
$approvalUrl = $payment->getApprovalLink();
echo "Per favore, approva il pagamento a questo URL: <a href='" . $approvalUrl . "'>" . $approvalUrl . "</a>\n";
// Reindirizza l'utente a $approvalUrl per autorizzare il pagamento.
// Dopo l'approvazione o la cancellazione, PayPal reindirizzerà agli URL specificati in $redirectUrls.
} catch (\PayPal\Exception\PayPalConnectionException $ex) {
echo $ex->getData();
die($ex);
} catch (\Exception $ex) {
die($ex);
}
// execute-payment.php (file separato per gestire il ritorno da PayPal)
<?php
require 'vendor/autoload.php';
// *** CONFIGURAZIONE (come nel file precedente) ***
$clientId = 'IL_TUO_CLIENT_ID';
$clientSecret = 'IL_TUO_CLIENT_SECRET';
$apiContext = new \PayPal\Rest\ApiContext(
new \PayPal\Auth\OAuthTokenCredential(
$clientId,
$clientSecret
)
);
$apiContext->setConfig(
array(
'mode' => 'sandbox'
)
);
if (isset($_GET['success']) && $_GET['success'] == 'true' && isset($_GET['paymentId']) && isset($_GET['token']) && isset($_GET['PayerID'])) {
$paymentId = $_GET['paymentId'];
$payment = \PayPal\Api\Payment::get($paymentId, $apiContext);
$execution = new \PayPal\Api\PaymentExecution();
$execution->setPayerId($_GET['PayerID']);
try {
$result = $payment->execute($execution, $apiContext);
// Ora il pagamento è stato approvato. Puoi procedere con l'acquisizione.
$payment = \PayPal\Api\Payment::get($paymentId, $apiContext);
$transactions = $payment->getTransactions();
$authorization = $transactions[0]->getRelatedResources()[0]->getAuthorization();
$authorizationId = $authorization->getId();
// *** ACQUISIZIONE DELL'AUTORIZZAZIONE ***
$amount = new \PayPal\Api\Amount();
$amount->setCurrency("EUR") // Assicurati che sia la stessa valuta dell'autorizzazione
->setTotal("25.00"); // L'importo da acquisire (può essere inferiore all'autorizzazione)
$capture = new \PayPal\Api\Capture();
$capture->setAmount($amount);
try {
$capture = $authorization->capture($capture, $apiContext);
echo "Autorizzazione acquisita con successo. ID Acquisizione: " . $capture->getId() . "\n";
// Qui puoi salvare l'ID di acquisizione nel tuo database e completare l'ordine.
} catch (\PayPal\Exception\PayPalConnectionException $ex) {
echo $ex->getData();
die($ex);
} catch (\Exception $ex) {
die($ex);
}
} catch (\PayPal\Exception\PayPalConnectionException $ex) {
echo $ex->getData();
die($ex);
} catch (\Exception $ex) {
die($ex);
}
} else {
echo "L'autorizzazione è stata annullata.\n";
}
?>Spiegazione dei Passaggi:
Client ID e Client Secret di PayPal.ApiContext che contiene le tue credenziali e specifica l'ambiente (sandbox per i test).Payer e impostiamo il metodo di pagamento su "paypal" (per reindirizzare l'utente al suo conto PayPal). Se avessi i dettagli della carta di credito, potresti utilizzare "credit_card" e fornire i dettagli.Amount da autorizzare, specificando la valuta e l'importo totale.Transaction che include l'importo e una descrizione (opzionale).RedirectUrls:
ReturnUrl: L'URL a cui PayPal reindirizzerà l'utente dopo aver approvato il pagamento.CancelUrl: L'URL a cui PayPal reindirizzerà l'utente se annulla il pagamento.Payment e impostiamo l'intent su "authorize". Questo indica a PayPal che vogliamo solo autorizzare i fondi, non addebitarli immediatamente.create() sull'oggetto $payment per inviare la richiesta a PayPal.approvalUrl da cui l'utente deve essere reindirizzato per accedere al suo conto PayPal e approvare l'autorizzazione.execute-payment.php):
ReturnUrl.success, paymentId, token e PayerID siano presenti nella query string.paymentId.PaymentExecution e impostiamo il PayerID.execute(). Questo completa la parte di "approvazione" del flusso.Authorization correlato.authorizationId dall'oggetto Authorization.Amount per specificare l'importo da acquisire (potrebbe essere lo stesso dell'autorizzazione o un importo inferiore).Capture e impostiamo l'importo.capture() sull'oggetto $authorization per addebitare effettivamente i fondi.ID Acquisizione. Questo ID è importante per tracciare la transazione.Come Utilizzare Questo Esempio:
'IL_TUO_CLIENT_ID' e 'IL_TUO_CLIENT_SECRET' con le tue credenziali API di PayPal Sandbox.$redirectUrls in modo che corrispondano agli URL del tuo server di sviluppo.authorize-payment.php) e il secondo blocco come execute-payment.php nella stessa directory (o configura il tuo server web di conseguenza).php -S localhost:8000 nella directory contenente i file).http://localhost:8000/authorize-payment.php).ReturnUrl o CancelUrl. Se l'approvazione ha successo, lo script execute-payment.php tenterà di acquisire l'autorizzazione.Punti Importanti:
try...catch. In un'applicazione reale, dovresti implementare una gestione degli errori più dettagliata e registrare le informazioni rilevanti.Spero che questo esempio ti sia utile per capire come utilizzare la funzionalità di Autorizzazione e Acquisizione con le API di PayPal e PHP! Se hai domande su passaggi specifici o su come adattare questo esempio al tuo progetto, non esitare a chiedere.
Gestire un "no-show" utilizzando le funzionalità di PayPal che abbiamo discusso (Autorizzazione e Acquisizione, Accordi di Fatturazione) richiede un approccio leggermente diverso a seconda di come hai impostato il processo di prenotazione o servizio. Ecco alcune strategie e come potresti implementarle:
Scenario 1: Utilizzo dell'Autorizzazione e Acquisizione
Se al momento della prenotazione hai autorizzato un importo sulla carta del cliente, hai diverse opzioni per gestire un "no-show":
authorizationId associato alla prenotazione del cliente che non si è presentato.Amount con l'importo del "no-show".Capture e imposta l'importo.capture() sull'oggetto $authorization utilizzando l'authorizationId precedentemente salvato.<?php
// ... (configurazione API come prima) ...
$authorizationId = 'ID_AUTORIZZAZIONE_DEL_CLIENTE_NO_SHOW'; // Recupera l'ID dal tuo database
$importoNoShow = '15.00'; // Importo da addebitare per il no-show
$valuta = 'EUR'; // La valuta dell'autorizzazione
$amount = new \PayPal\Api\Amount();
$amount->setCurrency($valuta)
->setTotal($importoNoShow);
$capture = new \PayPal\Api\Capture();
$capture->setAmount($amount);
try {
$authorization = new \PayPal\Api\Authorization();
$authorization->setId($authorizationId);
$capturedPayment = $authorization->capture($capture, $apiContext);
echo "Addebito per no-show effettuato con ID Acquisizione: " . $capturedPayment->getId() . "\n";
// Aggiorna il tuo database per riflettere l'addebito per il no-show.
} catch (\PayPal\Exception\PayPalConnectionException $ex) {
echo $ex->getData();
die($ex);
} catch (\Exception $ex) {
die($ex);
}
?>2. Nessuna Acquisizione (e potenziale addebito successivo):
Scenario 2: Utilizzo degli Accordi di Fatturazione
Se hai impostato un Accordo di Fatturazione con il cliente, hai più flessibilità per gestire i "no-show":
<?php
// ... (configurazione API come prima) ...
$billingAgreementId = 'ID_ACCORDO_DI_FATTURAZIONE_DEL_CLIENTE_NO_SHOW'; // Recupera l'ID dal tuo database
$importoNoShow = '20.00'; // Importo da addebitare per il no-show
$descrizione = 'Addebito per no-show.';
$valuta = 'EUR';
$agreement = new \PayPal\Api\BillingAgreement();
$agreement->setId($billingAgreementId);
$chargeModel = new \PayPal\Api\ChargeModel();
$chargeModel->setType('STANDALONE')
->setAmount(new \PayPal\Api\Currency(array('value' => $importoNoShow, 'currency' => $valuta)));
$billingInfo = new \PayPal\Api\BillingInfo();
$billingInfo->setOutstandingBalance(new \PayPal\Api\Currency(array('value' => $importoNoShow, 'currency' => $valuta)))
->setNextPaymentDate(date('Y-m-d\TH:i:s\Z', time())); // Puoi impostare una data futura o attuale
$payment = new \PayPal\Api\Payment();
$payment->setIntent('sale') // L'intent 'sale' esegue direttamente l'addebito
->setPayer(new \PayPal\Api\Payer())
->setTransactions(array((new \PayPal\Api\Transaction())
->setAmount(new \PayPal\Api\Amount()
->setCurrency($valuta)
->setTotal($importoNoShow))
->setDescription($descrizione)))
->setBillingAgreementId($billingAgreementId);
try {
$payment->create($apiContext);
echo "Addebito per no-show effettuato con ID Transazione: " . $payment->getId() . "\n";
// Aggiorna il tuo database.
} catch (\PayPal\Exception\PayPalConnectionException $ex) {
echo $ex->getData();
die($ex);
} catch (\Exception $ex) {
die($ex);
}
?>Considerazioni Importanti per la Gestione dei "No-Show":