Zum Hauptinhalt gehen

wallee SDK - Transaktionen verwalten und auslesen / Recurring payment

Theodor Spring
  • Aktualisiert

Vorbereitete Transaktion in einer Software an physisches Terminal senden

Wallee bietet neben E-Commerce Transaktionen auch Zahlungsabwicklungen über physische Terminals an. 

 

Mit der SDK ist es auch möglich, dass vorbereitete Transaktionen ans Terminal weitergeleitet werden, wo der Kunde vor Ort bezahlen kann.

Transaktion ans Portal senden

$client = new ApiClient($userAppId, $token)


$transaction = $client->getTransactionService()->create($spaceId, $transactionPayload);

 

Womit der $transactionPayload gefüllt sein muss, ist im anderen Dokument “wallee_SDK_Transaktionen” bereits beschrieben.

Um die Transaktion an ein bestimmtes physisches Terminal zu senden, benötigt man den Terminal Identifier, welcher auf der erstellten Terminal Entität im Portal zu finden ist:

Transaktion ans Terminal senden

$client->getPaymentTerminalTillService()->performTransactionByIdentifier($this->spaceId, $transactionId, $terminalIdentifier, $language = null);

 

Sobald diese Methode ausgeführt wurde, sollte ca. innert 10-15 Sekunden auf dem Terminal die Zahlungsaufforderung erscheinen, mit dem Betrag, welcher auf der Transaktion gesetzt wurde.

 

Wichtig dabei, auf der verlinkten Konfiguration des Terminals im Portal muss das “Cloud API” Interface aktiviert sein, sonst funktioniert die Interaktion mit der wallee API nicht.




 

Feedback vom Terminal verarbeiten

Nachdem der Kunde bezahlt hat, kommt ca. innert 1.5 Minuten ein Feedback vom Wallee Portal, ob die Zahlung erfolgreich war.

 

Hier ein Beispiel, wie dieses Feedback Management in der Shop Applikation aussehen könnte:

try {

  $terminalResult = $walleePaymentGateway->payViaTerminalById($transactionId, $terminalIdentifier);

         if ($terminalResult->getState() == "SUCCESSFUL" ||
                $terminalResult->getState() == "AUTHORIZED") {

             header("Location: " . $terminalResult->getSuccessUrl());

           } else {

             header("Location: " . $terminalResult->getFailedUrl());

               }

     } catch (Exception $e) {

         if ($e instanceof Wallee\Sdk\ApiException) {

             if (stripos($e->getMessage(), "Terminal transaction canceled.")) {

                 header("Location: https://your-shop.com?terminal_canceled=true&txId=" . $_SESSION['tx_id']);

             } else {

                 header("Location: https://your-shop.com?transaction_failed=true&txId=" . $_SESSION['tx_id']);

                 $_SESSION['exception'] = $e->getMessage();

             }

         }

  }

 

Transaktionsänderungen nach Terminalzahlungen synchron erhalten

Um die Transaktion Stati synchron zu erhalten, gilt wieder dasselbe Konzept mit den Webhooks, wie im Dokument “wallee_SDK_Transaktionen” erklärt.  

 

 

Wiederkehrende Zahlungen über Tokens realisieren

Bei einer Transaktion kann über ein Token Zahlungsinformationen von Kunden abgespeichert werden, damit so benutzerlos eine Transaktion erstellt und verbucht werden kann.

 

Dies ist bei Abo-Produkten hilfreich.

 

Als Grundlage dafür muss das Charge Flow Feature im Portal aktiviert sein, sowie ein Charge Flow im Charge Flow Menü angelegt worden sein.

Neuer Token anlegen

Als erstes, damit Zahlungsinformationen erfasst werden können wird ein leerer Token (ohne Zahlungsinformationen angelegt und im Portal abgespeichert):

$tokenPayload = new TokenCreate();

$tokenPayload->setExternalId("sdk-diagnostic" . rand() . "test");

$tokenPayload->setState('ACTIVE');

$tokenPayload->setEnabledForOneClickPayment(true);

$reference = rand() . '-' . "SDK";

$tokenPayload->setTokenReference($reference);


$token = $this->client->getTokenService()->create($this->spaceId, $tokenPayload);

 

Als nächster Schritt wird dem Transaction Payload die ID des Tokens mitgegeben, bevor diese Transaktion an das Portal gesendet wird:

$transactionPayload->setToken($token->getId());

 

Als nächster Schritt kann die Transaktion bearbeitet, bzw. vom Kunden bezahlt werden. Somit werden nun auch die Zahlungsinformationen des Kunden auf dem Token referenziert.

 

Wie die Transaktionsverarbeitung via SDK funktioniert, ist im Dokument “wallee_SDK_Transaktionen” dargelegt.

Vorhandener Token für benutzerlose Bezahlung verwenden (Recurring payment)

Nach einer gewissen Zeit, ab wann sich das Abo erneuern soll (dies wird z.B. im Business Layer der Merchant Applikation umgesetzt), wird erneut eine Transaktion vorbereitet und ans Portal gesendet. 

 

Dabei wird im Transaction Payload die Token ID des betroffenen Abonnenten verwendet. Diese ID hat der Merchant beispielsweise in seiner Datenbank abgespeichert.

 

$transactionPayload->setToken($tokenIdOfExistingSubscriber);

Nachdem die Transaction so mit “Transaction Create” ans Portal gesendet wurde, existiert dort eine Transaktion mit dem verlinkten Token, der die Zahlungsinformationen des Kunden referenziert.

 

Damit kann nun benutzerlos die Transaktion ausgeführt und verbucht werden.

 

Dies mit folgender SDK Methode:

 

$client->getTransactionService()->
processWithoutUserInteraction($this->spaceId, $transactionId);

 

Damit wurden die referenzierten Zahlungsinformationen für die jetzt verbuchte Transaktion verwendet.

Recurring Payments überwachen

Um fehlgeschlagene Recurring Payments zu überwachen, können die Charge Flows im Portal verwendet werden. Um z.B. dem Kunden eine Mail zu senden, wenn die automatische Zahlung erfolglos war.

 

Alternativ auf dem Business Layer der Merchant Applikation kann auch direkt nach der benutzerlosen Ausführung der Transaktion, der Transaktionsstatus abgefangen werden, um eigene Business Prozesse auszuführen:

 

$result = $client->getTransactionService()->
processWithoutUserInteraction($this->spaceId, $transactionId);


if ($result->getState() == TransactionState::AUTHORIZED || $result->getState() == TransactionState::FULFILL) {
  // Business process for successful subscription renewal
} else {
  // Business process for failed subscription renewal
}



Transaktionen verwalten

Verbuchen

Sobald eine Transaktion im Portal den Status “Authorized” hat, kann der Betrag des Kunden hiermit manuell verbucht werden:

$client->getTransactionCompletionService()->completeOnline($spaceId, $transactionId);

Wichtig, damit der Status auf “Authorized” persistiert, um eine manuelle Verbuchung zu ermöglichen, muss der Zahlungskonnektor im Portal auf “deferred” gestellt werden:

Stornieren

Eine Transaktion kann storniert werden, wenn der Betrag erst autorisiert wurde, aber noch nicht verbucht:

$client->getTransactionVoidService()->voidOnline($space_id, $transactionId);

 

Nach einer Stornierung wird der reservierte Betrag freigegeben und der Kunde kann diesen wieder frei verwenden.

Rückerstatten

Damit eine Transaktion Rückerstattet werden kann, muss der Transaktionsstatus im Portal “Fulfill” sein.

 

Die Refund Methode benötigt einen Refund Payload, quasi äquivalent zur Transaction Create Methode mit dem Transaction Payload:

 

$refund = new RefundCreate();

$refund->setAmount($transaction->getAuthorizationAmount());

$refund->setTransaction($transaction->getId());

$refund->setMerchantReference($transaction->getMerchantReference());

$refund->setExternalId($transaction->getId());

$refund->setType(RefundType::MERCHANT_INITIATED_ONLINE);

Hier kann der rückerstattende Betrag, die betroffene Transaktion, etc. angegeben werden.

 

Wichtig; Der Refund Typ muss “MERCHANT_INITIATED_ONLINE” sein, damit die Rückerstattung beim PSP auch in Auftrag gegeben wird. Ansonsten wird der Refund nur als interne Notiz im Portal entgegengenommen, bzw. der Kunde würde dann keine Rückerstattung erhalten. 

 

Anschliessend kann der Refund mithilfe des Refund Payloads ($refund) ausgeführt werden:

$apiClient->getRefundService()->refund($spaceId, $refund);

Transaktion vorzeitig abbrechen (vor Bezahlung)

Eine Transaktions-Session (Zeitrahmen, in dem ein Kunde eine vorbereitete Transaktion bezahlen kann) kann vorzeitig abgebrochen werden.

 

Dazu benötigt man das Charge Flow Feature, welches in der Feature Liste im Portal aktiviert werden kann.

 

Anschliessen muss im Charge Flow Menü ein solcher angelegt werden.

 

Im Applikationscode, nachdem eine Transaktion vorbereitet wurde (mit Transaction Create) muss anschliessend der erstellte Charge Flow auf diese Transaktion angewendet werden
(ID der vorbereiteten Transaktion benötigt):

$client->getChargeFlowService()->applyFlow($spaceId, $transactionId);

 

Anschliessend je nach Definition der Merchant Applikation kann nach gewünschter Zeitspanne die vorbereitete Transaktion abgebrochen werden:

$client->getChargeFlowService()->cancelChargeFlow($spaceId, $transactionId)

 

Durch den Abbruch des angewendeten Charge Flows auf dieser Transaktion, wird auch die Transaktion selbst abgebrochen.




 

Transaktions- und Zahlungsdaten auslesen

Transaktionsdaten

Die wohl wichtigsten Daten aus einer Transaktion sind:

  • Transaktionsstatus
  • Totalbetrag
  • Artikel
  • Adresse des Kunden
  • und noch einige mehr

 

Spezifische Transaktion auslesen mit den wichtigsten Attributen

$transaction = $client->getTransactionService()->read($spaceId, $transactionId);


echo $transaction->getState();


echo $transaction->getMerchantReference();

// autorisierter Betrag

echo $transaction->getAuthorizationAmount(); 

// erhaltener Betrag

echo $transaction->getTotalSettledAmount();

// Autorisierung Datum

echo $transaction->getAuthorizedOn()->format('Y-m-d-H-i');

// Token ID 

echo $transaction->getToken()->getId()

// Kunden Daten

echo $transaction->getCustomerEmailAddress();

echo $transaction->getBillingAddress()->getGender();

echo $transaction->getBillingAddress()->getGivenName();

echo $transaction->getBillingAddress()->getFamilyName();

echo $transaction->getBillingAddress()->getStreet();

echo $transaction->getBillingAddress()->getPostcode();

echo $transaction->getBillingAddress()->getCity();

echo $transaction->getBillingAddress()->getCountry();

Artikel der Transaktion auslesen

foreach($transaction->getLineItems() as $lineItem) {

     echo $lineItem->getName();

     echo $lineItem->getAmountExcludingTax();

     echo $lineItem->getTaxAmount();

     echo $lineItem->getType();

     echo $lineItem->getSku();

 }



Zahlungsdaten

Zahlungsdaten können über den Charge Attempt ausgelesen werden.

 

Je nach angebundenem PSP können die verfügbaren Zahlungsarten variieren.

 

Die vollständige Kreditkartennummer sowie den CVC Code liefert die Wallee API nicht zurück, bzw. liegen beim PSP.

 

Folgende Zahlungsinformationen liefert die wallee API zurück:

  • Maskierte Kartennummer (letzte 4 Ziffern)
  • Ablaufdatum der Kreditkarte
  • Referenznummer
  • Transaktion ID des PSP (z.B. UPP bei Datatrans)

 

Im Charge Attempt, welcher mit der Transaktion verknüpft ist, enthält die Zahlungsdaten.

Charge Attempt zur Transaktion suchen

// Filter erstellen um Charge Attempt über Transaktion ID zu
// bekommen

$entityQueryFilter = new \Wallee\Sdk\Model\EntityQueryFilter([

'field_name' => 'charge.transaction.id',

  'operator'   => \Wallee\Sdk\Model\CriteriaOperator::CONTAINS,

  'type'   => \Wallee\Sdk\Model\EntityQueryFilterType::LEAF,

'value'  => "119137952" // ihre jeweilige Transaktion ID

    

]);


$entityQuery = new \Wallee\Sdk\Model\EntityQuery(['filter' => $entityQueryFilter]);


$chargeAttempts = $apiClient->getChargeAttemptService()->search($spaceId, $entityQuery);

 

Anschliessend werden alle Charge Attempts zurückgegeben, welche auf dieser Transaktion gemacht wurden.

 

Es kann mehrere Charge Attempts (Zahlungsversuche) geben, falls z.B. der erste Zahlungsversuch fehlgeschlagen ist.

 

Siehe nächste Seite.

Zahlungsinformationen auslesen

$maskedCardNrId = 1456765125779;

$authCodeNrId = 1486972312134;

$uppId = 1486972299781;

$refNoId = 1486972272075;

$expiryDateId = 1456765711187 ;


foreach($chargeAttempts as $chargeAttempt) {

// Status, ob Zahlungsversuch erfolgreich war

echo $chargeAttempt->getState();


foreach ($chargeAttempt->getLabels() as $attempt)  {

if ($attempt->getDescriptor()->getId() == $maskedCardNrId) {

     $maskedCardNr = $attempt->getContentAsString();

     echo "\nPAN No: " . $maskedCardNr . PHP_EOL;

}

if ($attempt->getDescriptor()->getId() == $refNoId) {

     $refNo = $attempt->getContent()[0];

     echo "\nRef No: " . $refNo . PHP_EOL;

}

if ($attempt->getDescriptor()->getId() == $authCodeNrId) {

     $authCodeNr = $attempt->getContent()[0];

     echo "\nAuth code: " . $authCodeNr . PHP_EOL;

}

if ($attempt->getDescriptor()->getId() == $uppId) {

     $upp = $attempt->getContent()[0];

     echo "\nUPP ID: " . $upp . PHP_EOL;

}
    // expiry date

     if ($label->getDescriptor()->getId() == $expiryDateId) {

        expiryDate = $label->getContentAsString();

        echo "\nExpiry date: " . $expiryDate;

            }

     }

}




Verwandte Beiträge

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.