Paypal Kontostand und Umsätze per C# API abfragen

Nachdem wir kürzlich geschaut haben, wie man Push-Notifications aus C# heraus verschicken kann, soll es heute gleich den nächsten C#-Artikel geben. Dieses mal soll es darum gehen, wie man Kontostand, Umsätze und andere Dinge eines Paypal-Accounts auslesen kann.

Vorab ein paar grundlegende Infos. Auch wenn Paypal ein “Online-Konto” ist, unterscheidet es sich in vielerlei Hinsicht von einem Online-(Giro-)Konto einer “klassischen” Bank. So unterstützt Paypal zum Beispiel nicht den HBCI-Standard (Homebanking Computer Interface), um Kontoinformationen abzurufen oder Zahlungen zu senden. Stattdessen bietet Paypal unterschiedliche APIs (Rest, SOAP, +SDKs, …), die sich nicht nur in Aufbau und Technik, sondern vorallem auch im Funktionsumfang unterscheiden. Für unsere Zwecke werden wir die sogenannte “NVP/SOAP API” nutzen und diese mit C# und Visual Studio Standardmitteln. Spezielle Bibliotheken oder SDKs schenken wir uns.

Vorbereitungen – Paypal API-Keys

Bevor wir mit der Programmierung starten können, benötigen wir noch die Zugangsdaten, die uns den Zugriff per Schnittstelle erlauben. Ein Zugriff mittels Paypal-Adresse und Passwort ist in der SOAP-API nämlich nicht vorgesehen.

Die API-Zugangsdaten könnt ihr über folgende Links beantragen bzw. generieren. Zur Anmeldung auf der Webseite müsst ihr die Zugangsdaten des Paypal-Accounts nutzen, für den ihr später Informationen abrufen wollt. Je nach alter eures Accounts gibt es zwei verschiedene Varianten die API-Schlüssel zu erzeugen.

Variante 1: Paypal SOAP-API Zugangsdaten abrufen
Variante 2: Paypal SOAP-API Zugangsdaten abrufen (neu)

Wenn ihr den Link aus Variante 1 nehmt und auf eine etwas “altbackene” Webseite weitergeleitet werdet, die euch API-Nutzername, Signatur und API-Passwort anzeigt, dann seid ihr bereit durch. Kopiert euch die Werte, die ihr durch einen Klick auf die “Anzeigen”-Links sichtbar machen könnt. Variante 1 entspricht dem Screenshot, der auf der rechten Seite dieses Absatzes angezeigt wird.

Sollte euch der Link nicht zur API-Key-Seite führen, dann wählt bitte den zweiten der beiden Links, die ich weiter oben gepostet habe. In diesem Fall müsst ihr bis zum Ende der Seite scrollen und auf “API-Berechtigung erstellen/verwalten” im Abschnitt “NVP/SOAP-API-Integration (klassisch)” klicken. Die folgenden Screenshots zeigen die Prozedur. (Screenshots zum Vergrößern anklicken.)

Nachdem ihr die Keys angelegt habt, kopiert ihr euch auch bei dieser Variante den API-Benutzer, das API-Passwort sowie die Signatur. Alle drei werden wir für die C#-Programmierung benötigen.

Vorbereitungen – GUI und Webservice-Klassenmodell

Kommen wir nun zur Implementierung in C#. Als Rahmenprogramm habe ich in Visual Studio ein neues WinForms-Projekt angelegt und diesem eine Richtext-Box namens “richTextBoxOutput” sowie einen Button hinzugefügt in dessen Click-Event wir den Paypal-Zugriff ausprogrammieren wollen. Die Applikationsoberfläche entspricht dem Screenshot auf der linken Seite.

Damit wir nun die Paypal-API anprogrammieren können, generieren wir uns mit dem Visual Studio automatisch ein Klassenmodell für den Zugriff auf die API. (Wie Eingangs bereits angekündigt nutzen wir in diesem Artikel nur Bordmittel und keine zusätzlichen Klassen oder Bibliotheken.)

Hierzu machen wir im Projektmappenexplorer des Visual Studios einen Rechtsklick auf den Menüpunkt “Verweise” und wählen die Option “Dienstverweis hinzufügen”.  Im Feld “Adresse:” geben wir die Url zur WSDL der Paypal-SOAP-API an:

https://www.paypalobjects.com/wsdl/PayPalSvc.wsdl

Mit einem Klick auf “Gehe zu” laden wir das API-Modell in das Visual Studio. Anschließend ändern wir den Namespace im gleichnamigen Feld von “ServiceReference1” zu “ServicePaypal”. (Theoretisch könnt ihr jeden beliebigen Namespace wählen. Die Änderung dient lediglich der Übersichtlichkeit beim späteren Coding.) Abschließend lassen wir das (Service-)Klassenmodell mit einem Klick auf den “Ok”-Button generieren.

<endpoint address=

https://api-3t.paypal.com/2.0/
https://api-aa-3t.paypal.com/2.0

Nun, da wir das Klassenmodell erzeugt und die Endpunkte angepasst haben, können wir endlich zur Abfrage der Informationen von Paypal übergehen.

Paypal-API in C# ansprechen

Den folgenden Code habe ich in der Button-Click-Methode der Beispiel-Anwendung geschrieben, die wir zuvor eingerichtet habt. Prinzipiell kann der Code natürlich an jeder Stelle des Programms verwendet werden. Im ersten Schritt wollen wir den Kontostand des Paypal-Accounts abfragen und diesen in der Richtext-Box anzeigen. Den Ablauf des Programms könnt ihr den Code-Kommentaren entnehmen.

var user = "XXXXXXXgooglemail.com";
var pass = "XXXXXXXX";
var signature = "XXXXXXXX";

try
{
	//General init
	var paypalService = new ServicePaypal.PayPalAPIInterfaceClient();

	//Create authentication header
	var securityHeader = new ServicePaypal.CustomSecurityHeaderType();
	var credentials = new ServicePaypal.UserIdPasswordType();
	credentials.Username = user;
	credentials.Password = pass;
	credentials.Signature = signature;

	//Set security header
	securityHeader.Credentials = credentials;

	//Create balance request
	var payloadReqBal = new ServicePaypal.GetBalanceReq()
	{
		GetBalanceRequest = new ServicePaypal.GetBalanceRequestType()
	};
	//Configure balance request
	payloadReqBal.GetBalanceRequest.Version = "204.0";
	payloadReqBal.GetBalanceRequest.ReturnAllCurrencies = "1";

	//Get balance
	var balance = paypalService.GetBalance(ref securityHeader, payloadReqBal);

        //Show balance for each currency
	foreach (var balanceLocal in balance.BalanceHoldings)
	{
		//Show balance (Value = X.XX, currencyID = "EUR", etc.)
		richTextBoxOutput.AppendText($"{balanceLocal.Value} {balanceLocal.currencyID}\r\n");
	}
}
catch (Exception ee)
{
	MessageBox.Show($"Houston, we had a problem: {ee.Message}");
}

Der oben stehende Code fragt den Kontostand ab und gibt diesen in der Form X.XX {Währungskürzel} in der Richtext-Box aus. Die Variablen “user”, “pass” und “signature” müssen dabei durch die API-Zugangsdaten ersetzt werden, die wir im ersten Teil dieses Artikels ermittelt haben. Abgesehen von dem Security-Header ist der Abruf des Kontostandes sonst recht einfach.

Kommen wir nun zum Abruf der Umsätze. Der erste Teil des Codes gleicht jenem für den Kontostand. Das Auslesen der Umsätze selbst, weicht dann jedoch etwas ab. Doch schauen wir einfach erst einmal auf den Code.

var user = "XXXXXXXgooglemail.com";
var pass = "XXXXXXXX";
var signature = "XXXXXXXX";

try
{
	//General init
	var paypalService = new ServicePaypal.PayPalAPIInterfaceClient();

	//Create authentication header
	var securityHeader = new ServicePaypal.CustomSecurityHeaderType();
	var credentials = new ServicePaypal.UserIdPasswordType();
	credentials.Username = user;
	credentials.Password = pass;
	credentials.Signature = signature;

	//Set security header
	securityHeader.Credentials = credentials;

	//Create transaction request
	var payloadReq = new ServicePaypal.TransactionSearchReq()
	{
		TransactionSearchRequest = new ServicePaypal.TransactionSearchRequestType()
	};

	//Set last 15 days as period for the transaction log
	//If you want you can set an optional ".EndDate"
	payloadReq.TransactionSearchRequest.StartDate = DateTime.Now.AddDays(-15);
	payloadReq.TransactionSearchRequest.Version = "204.0";

	//Get the list of transactions
	var transactionList = paypalService.TransactionSearch(ref securityHeader, payloadReq);

	//Check if transactions were transferred
	if (transactionList != null 
		&& transactionList.Ack == ServicePaypal.AckCodeType.Success
		&& transactionList.PaymentTransactions != null)
	{      
		//Show each transaction in richtextBox
		foreach (var trans in transactionList.PaymentTransactions)
		{
			var businessPartner = !string.IsNullOrEmpty(trans.PayerDisplayName) ? trans.PayerDisplayName : trans.Payer;

			var output = $"Amount: {trans.GrossAmount.Value}\r\n";
			output += $"Paypal-Fees: {trans.FeeAmount.Value}\r\n";
			output += $"Transaction type: {trans.Type}\r\n";
			output += $"Time of transaction: {trans.Timestamp.ToShortDateString()}\r\n";
			output += $"Transaction contact: {businessPartner}\r\n\r\n";
		 
			richTextBoxOutput.AppendText(output);
		}                    
	}
}
catch (Exception ee)
{
	MessageBox.Show($"Houston, we had a problem: {ee.Message}");
}

Der oben stehende Code ruft die Transaktionen/Überweisungen der jeweils letzten 15 Tage ab. Wenn gewünscht kann neben dem Startdatum auch ein Enddatum gesetzt werden, sodass nur ein gezielter Ausschnitt der Vergangenheit betrachtet wird. In der foreach-Schleife zum Ende des Snippets wird dann jede einzelne Transaktion ausgegeben. Ich habe als Beispiel ein paar verschiedene Werte zur jeweiligen Transaktion wir den Zahlungsempfänger/-sender (=businessPartner-Variable) oder die Paypalgebühren (=trans.FeeAmount.Value) ausgegeben. Eine vollständige Übersicht der verfügbaren Eigenschaften findet ihr an dieser Stelle in der Paypal-API-Doku.

Fazit

Prinzipiell ist der Zugriff auf Paypal per C# nicht wirklich schwer. Abgesehen von der Authentifizierung ist der Zugriff in wenigen Zeilen geschehen. Was das ganze jedoch recht beschwerlich macht, ist die unübersichtliche Dokumentation der API. Das fängt dabei an, dass man nur auf umständliche Art und Weise an die API-Keys kommt und hört damit auf, dass selbst die Doku-Seite zur Paypal-API (ich habe sie im letzten Absatz verlinkt), nicht wirklich klar strukturiert ist. Eine Übersicht der einzelnen Methoden des Services im Menü der Doku-Webseite fehlt mir persönlich zum Beispiel.

Wie sind eure Erfahrungen mit der Paypal-API? Habt ihr bereits mit der API gearbeitet oder vielleicht auch mit anderen FinTech-APIs? Über einen Erfahrungsaustausch freue ich mich wie immer. (Konstruktive Kritik und Anmerkungen zum Artikel sind natürlich auch gerne gesehen!)