worldline Direct
Sign up

Aktuellste API Basis-URL nutzen

Wir raten Ihnen, immer die aktuellste API Basis-URL zu nutzen, wenn Sie Anfragen an unsere Plattform senden. In unseren ausführlichen Anleitungen finden Sie eine komplette Übersicht:

Für einen reibungslosen Übergang bleiben vorherige API Basis-URLs bis auf weiteres verfügbar.

Zum Erstellen von Zahlungen müssen Sie Ihren Server über einen unserer Integrationsmodi mit unserer Plattform verbinden.
Unsere Python SDK-Bibliothek ist die ideale Lösung zur Verbindung mit unserer Plattform, wenn Sie es vorzugsweise mit Ihrem eigenständigen System in der Sprache Python tun möchten.

Durch Auswahl des Python SDK können Sie:

Damit Sie die Möglichkeiten dieses SDK voll ausschöpfen können, müssen Sie diese Anforderungen erfüllen:

  • Python 2.7 oder Python 3.5 und höher

Installieren Sie die neueste Version des Python SDK mit PIP package manager:

  • Für Python 3.5 (oder höher) führen Sie aus:
    
    pip install onlinepayments-sdk-python3
    


  • Für Python 2.7 führen Sie aus:
    
    pip install onlinepayments-sdk-python2
    


Nähere Einzelheiten erfahren Sie auf GitHub (Python2, Python3). Sehen Sie sich auch alle verfügbaren SDK-Objekte und -Eigenschaften in unserer vollständigen API-Referenz an. Wenn alles bereit ist, lesen Sie bitte die nächsten Kapitel über die Vorbereitung und Verwendung des SDK.

Diese Anleitung gibt einen allgemeinen Überblick über die Funktionen des SDK. Wie sie für die verschiedenen Integrationsmodi genau funktionieren, erfahren Sie in den speziellen Anleitungen, die jeden Schritt mit vollständigen Code-Beispielen erklären:

Damit Sie das SDK zur Verbindung Ihres Systems mit unserer Plattform nutzen können, müssen Sie es zunächst initialisieren.

Zum Initialisieren des SDK müssen Sie:

  • Ein Test- und Live-Konto einrichten
  • Eine Eigenschaftendatei anlegen
    
    [OnlinePaymentsSDK]
    onlinepayments.api.integrator=integrator
    onlinepayments.api.endpoint.host=ApiEndpoint
    ; Die folgenden Schlüssel sind optional und haben den angegebenen Wert als Voreinstellung.
    onlinepayments.api..endpoint.scheme=https
    onlinepayments.api..endpoint.port=-1
    onlinepayments.api.connectTimeout=5
    onlinepayments.api.socketTimeout=300
    onlinepayments.api.maxConnections=10
    onlinepayments.api.authorizationType=v1HMAC
  • Einen API-Schlüssel und ein API-Geheimnis für die PSPID erzeugen, die Sie für die Transaktionsverarbeitung verwenden möchten
  • Eine Instanz von Client / MerchantClient unter Verwendung des API-Schlüssels / API-Geheimnisses initialisieren, um die Verbindung zu unserer Test-/Live-Plattform herzustellen
    
    from onlinepayments.sdk.factory import Factory
    
    client = Factory.create_client_from_file("payments_sdk.prp",  
                                            apiKey,  
                                            apiSecret)
    
    merchant_client = client.merchant(merchantId)
    

    "payments_sdk.prp" ist der Name einer Datei mit Eigenschaften.

Die folgende Tabelle gibt einen Überblick über die Argumente, die von den einzelnen Instanzen akzeptiert werden:

Eigenschaften
  • string merchantId: Ihre PSPID in unserer Test-Umgebung oder Live-Umgebung. Achten Sie darauf, dass Sie den korrekten API-Schlüssel / das korrekte API-Geheimnis zusammen mit der dazugehörigen PSPID für Ihre Transaktionsanfrage verwenden
  • string apiKey: Der API-Schlüssel, den Sie in Ihrer PSPID definiert haben und an den Sie die Transaktionen senden
  • string apiSecret: Das API-Geheimnis, das Sie in Ihrer PSPID definiert haben und an das Sie die Transaktionen senden

    In unserer speziellen Anleitung erfahren Sie alles zum Thema API-Schlüssel / API-Geheimnis

  • string apiEndpoint: Enthält einen Link zu unserer Test- oder Live-Umgebung, an die Ihre Transaktionsanfragen gesendet werden
  • string integrator: Ihr (Firmen-)Name oder eine andere eindeutige Kennung. Wir können den Wert zur Fehlersuche und Nachverfolgung von Anfragen, die Sie an unsere Plattform gesendet haben, verwenden. Darum empfehlen wir dringend, einen Wert zu senden, mit dem wir Ihre Anfragen in unseren Protokollen einfach identifizieren können


Nach der Initialisierung können Sie über Ihre PSPID Anfragen an unsere Plattform senden. Wie Sie das tun, erfahren Sie Im nächsten Kapitel.

As our SDKs always implement the latest version of our API, you can leave out "v2" in your code as shown in the example above.

Remember to pay attention to the environment you get the key set from. API Key and API Secret are different for test and live environments.

The full path of the of API endpoint for test/live environment is

  • https://payment.preprod.direct.worldline-solutions.com/v2/
  • https://payment.direct.worldline-solutions.com/v2/

respectively. If you are ready to switch to the live environment, substitute the endpoint link apiEndpoint = 'https://payment.preprod.direct.worldline-solutions.com/' for the live environment apiEndpoint = 'https://payment.direct.worldline-solutions.com/'

For transactions with no financial impact, use TEST-URL. The transactions will be sent to our test environment, thereby to your test account.

For transactions with a financial impact, use the LIVE-URL. The transactions will be sent to our live environment, thereby to your live account.

Nach der erfolgreichen Initialisierung der Client-Instanz haben Sie vollen Zugang zu unserer RESTful API. Damit können Sie:

  • Anfragen für neue Transaktionen für jeden unserer Server-Integrationsmodi senden
  • den aktuellen Status Ihrer Transaktionen abfragen
  • Wartungsanfragen (z. B. Erfassungen, Gutschriften) für bestehende Transaktionen durchführen

Stellen Sie Sicher, dass die Bezahlmethode, die Sie benutzen wollen, in Ihrem Test-/Livekonto aktiv ist. Überprüfen Sie dies im Back Office via Configuration > Payment methods

Auf GitHub (Python2, Python3) können Sie sich unsere Testfälle mit vollständigen Code-Beispielen ansehen. In unserer vollständigen API-Referenz erfahren Sie, was alles möglich ist.

Nachstehend finden Sie einige der häufigsten Aktionen, die Sie durchführen können:

Neue Transaktionen erstellen

Zum Erstellen einer neuen Transaktion können Sie eine Client- oder MerchantClient-Instanz für einen unserer Integrationsmodi verwenden. Dazu können Sie:

  • die Anfrage an Ihre PSPID auf unserer Plattform (für Client) leiten
  • eine Anfrage für den betreffenden Integrationsmodus erstellen

Die SDK-Instanz speichert nur die Daten, die zu ihrer Initialisierung verwendet wurden. Sie speichert weder aktive Sessions noch frühere Anfragen. Ihr System ist für die Verwaltung von Direct-Sessions und -Zahlungen verantwortlich

Sessions und Zahlungen haben keine Auswirkungen auf andere Sessions und Zahlungen

Nachfolgend finden Sie Code-Beispiele für bestimmte Integrationsmodi:

Hosted Checkout Page

Zum Nutzen dieses Integrationsmodus müssen Sie einen CreateHostedCheckoutRequest-Aufruf erstellen. Er muss mindestens ein Order-Objekt enthalten.


""" Initialisierung... """

order_dict = {
    "order": {"amountOfMoney": {"currencyCode": "EUR", "amount": 123}}
}

hosted_checkout_client = client.merchant(merchantId).hosted_checkout()
hosted_checkout_request = CreateHostedCheckoutRequest()
hosted_checkout_request.from_dictionary(order_dict)

hosted_checkout_response = hosted_checkout_client.create_hosted_checkout(
    hosted_checkout_request
)
Auf Wunsch können Sie eine returnUrl angeben, die dafür verwendet wird, Ihren Kunden wieder zu Ihrer Website weiterzuleiten

Diese Anfrage gibt eine CreateHostedCheckoutResponse-Antwort zurück. Speichern Sie die darin enthaltenen Werte hostedCheckoutId und RETURNMAC sowie alle anderen für Sie relevanten Informationen. Diese Daten brauchen Sie für die in den folgenden Kapiteln beschriebenen Schritte.

Diese Antwort enthält auch eine partialRedirectURL.

Sie müssen die Basis-URL „https://payment.“ mit partialRedirectURL nach folgender Formel verketten:

https://payment. + partialRedirectURL

und Ihren Kunden auf diese URL weiterleiten. Sobald der Kunde die Seite Hosted Checkout Page besucht, wird der Zahlungsvorgang dort fortgesetzt.

Die neueste Version unseres SDKs gibt in redirectURL auch den vollständigen Pfad zurück, daher können Sie die Verkettung der Basis-URL „https://payment.“ mit partialRedirectURL überspringen. Weitere Einzelheiten erfahren Sie in unserer Anleitung zu Hosted Checkout Page

Hosted Tokenization Page

Um diese Integrationsmethode zu verwenden, müssen Sie:


from onlinepayments.sdk.domain.create_hosted_tokenization_request import CreateHostedTokenizationRequest


""" Initialisierung... """

request = CreateHostedTokenizationRequest()
request.from_dictionary(
    {
        "variant": "template.html"
    })
hosted_t_client = client.merchant_client().hosted_tokenization()
response = hosted_t_client.create_hosted_tokenization(request)

Nehmen Sie Sie aus der response hosted_tokenizationId und partial_redirect_url:


t_id = response.hosted_tokenization_id
url = response.partial_redirect_url

Verwenden Sie die partial_redirect_url für den iframe und hosted_tokenizationId oder token_id (siehe Infobox) zum Erstellen der eigentlichen Zahlung über den Integrationsmodus Server-to-server.

In Ihrer CreatePayment-Anfrage können Sie entweder die tokenID oder die hostedTokenizationId senden. Mehr über die Verwendung beider Optionen erfahren Sie in den entsprechenden Kapiteln unserer Anleitung zu Hosted Tokenization Page:

token = hosted_t_client.get_hosted_tokenization(t_id).token.id

# Dictionary mit allen notwendigen Daten für Zahlungsanfrage
payment_dict = {
    "order": {"amountOfMoney": {"currencyCode": "EUR", "amount": 12300}},
    "CardPaymentMethodSpecificInput": {
        "token": token,
    },
}

payment_request = CreatePaymentRequest().from_dictionary(payment_dict)
payment_response = merchant_client.payments().create_payment(payment_request)

Server-to-server

Für eine minimale paymentResponse müssen Sie mindestens ein Order-Objekt und eine Zahlungsmethode festlegen:


""" Initialisierung... """

# Dictionary mit allen notwendigen Daten für Zahlungsanfrage
payment_dict = {
    "order": {"amountOfMoney": {"currencyCode": "EUR", "amount": 125000}},
    "cardPaymentMethodSpecificInput": {
        "card": {
            "cvv": "123",
            "cardNumber": "5300000000000006",
            "expiryDate": "0124",
            "cardholderName": "John Doe"
        },
        "paymentProductId": 3
    },
}

payment_request = CreatePaymentRequest()
payment_request.from_dictionary(payment_dict)
payment_response = merchant_client.payments().create_payment(payment_request)

Für jeden der oben genannten Integrationsmodi haben wir eine eigene Anleitung:

In den Dokumenten erfahren Sie alle wichtigen Einzelheiten, einschließlich vollständiger Transaktionsabläufe, Code-Beispiele und anderer nützlicher Funktionen, damit Sie das Potenzial der Integrationsmodi voll ausschöpfen können

Transaktionsstatus abrufen

Mit unserer RESTful API können Sie den Status einer Transaktion jederzeit mit einem unserer GET-Aufrufe abfragen:

Eine GetPayment-Anfrage sieht so aus:


response = merchant_client.payments().get_payment(payment_id)
Eigenschaften
string payment_id: Die eindeutige Referenz Ihrer Transaktion auf unserer Plattform. Diese Referenz kann abgerufen werden von hosted_checkout_client.create_hosted_checkout()
oder merchant_client.payments().create_payment(payment_request), die im vorherigen Abschnitt erstellt wurden.

Weitere Informationen zum Status finden Sie auf der Dokumentationsseite zum Status.

Wartungsmaßnahmen durchführen

Zum Ausführen von Folgemaßnahmen für bestehende Transaktionen (d. h. Erfassungen oder Gutschriften) verwenden Sie unseren API-Aufruf CapturePayment bzw. RefundPayment:

CapturePayment


from onlinepayments.sdk.domain.capture_payment_request import CapturePaymentRequest

""" Initialisierung... """

#/ Hier erhalten Sie payment_id zur Verwendung im weiteren Code
payment_id = payment_response.payment.id
capture_request = CapturePaymentRequest()
capture_request.from_dictionary({'amount': amount, 'isFinal': True})

merchant_client.payments().capture_payment(payment_id, capture_request)

RefundPayment


from onlinepayments.sdk.domain.refund_request import RefundRequest

 """ Initialisierung... """

payment_id = payment_response.payment.id
refund_dict = {"amountOfMoney": {"currencyCode": "EUR", "amount": 125000}}
refund_request = RefundRequest().from_dictionary(refund_dict)

# Objekt RefundResponse abrufen
response = merchant_client.payments().refund_payment(payment_id, refund_request)
Eigenschaften
string PAYMENT_ID: Die eindeutige Referenz Ihrer Transaktion auf unserer Plattform. Diese Referenz kann von den im vorherigen Abschnitt erstellten directSdk.payments.createPayment() oder directSdk.hostedCheckout.createHostedCheckout() abgerufen werden.

Wenn eine Transaktion abgelehnt wird, gibt unsere Plattform mit einer Exception-Instanz ausführliche Informationen. Auch der zugehörige HTTP-Status-Code hilft Ihnen bei der Fehlersuche.

Es können zwei Arten von Ausnahmen auftreten: Transaktionsausnahmen und HTTP-Ausnahmen.

Transaktionsausnahmen

Ausnahmen dieser Art beziehen sich auf Transaktionsanfragen, die technisch korrekt sind, aber vom Kreditkartenherausgeber Ihres Kunden oder von Ihrem Acquirer abgelehnt wurden. Wenn die Transaktion in der Ausnahme zurückgegeben wird, dann wurde sie in unseren Systemen erstellt, aber nicht erfolgreich verarbeitet. 

Die folgenden Code-Beispiele verwenden implizite Methoden, die als Beispiel angegeben sind. Von Ihnen wird erwartet, dass Sie diese Methoden selbst implementieren oder durch eine vergleichbare Logik ersetzen
  • def is_not_successful(*args, **kwargs) -> bool:  
       """ 
       Anhand der Eigenschaften status_output.status_category 
    und status_output.status_code von PaymentResponse 
    prüfen, ob die Transaktion erfolgreich war. 
    """
    
  • def handle_error(*args, **kwargs) -> None:  
       """
       Die Transaktion je nach ihrem Status verarbeiten 
       """
    
Ausnahmetyp /
HTTP-Statuscode
Code-Beispiel
Abgelehnte Transaktionen / 
Verschiedenes (siehe Objekt PaymentResponse)

from onlinepayments.sdk.declined_payment_exception import DeclinedPaymentException

""" Initialisierung... """

try:
    payment_response = merchant_client.payments().create_payment(payment_request)
    payment_id = payment_response.payment.id
except DeclinedPaymentException as e:
    payment = e.create_payment_result.payment
    payment_id = payment.id
    payment_status = payment.status
    handle_error(payment)

payment_response = merchant_client.payments().get_payment(payment_id)

# Ihr Code zur Prüfung des Transaktionsstatus und zur Fehlerbehandlung. 
if is_not_successful(payment_response):
    handle_error(payment_response) 
Abgelehnte Gutschrift /
Verschiedenes (siehe Objekt PaymentResponse)

from onlinepayments.sdk.declined_refund_exception import DeclinedRefundException

""" Initialisierung... """

payment_response = merchant_client.payments().create_payment(payment_request)
payment_id = payment_response.payment.id

refund_id = None
try:
    refund_request = RefundRequest().from_dictionary(refund_dict)
    refund_response = merchant_client.payments().refund_payment(payment_id, refund_request)
    refund_id = refund_response.id
except DeclinedRefundException as e:
    refund_result = e.refund_result
    handle_error(refund_result)

refund_response = merchant_client.payments().get_refunds(payment_id)

# Ihr Code zur Prüfung des Transaktionsstatus und zur Fehlerbehandlung.
if is_not_successful(refund_response, refund_id):
    handle_error(refund_response)

HTTP-Ausnahmen

Derartige Ausnahmen beziehen sich auf verschiedene Probleme, die auf technische Fehler beim API-Aufruf oder bei der Zahlungsanfrage zurückzuführen sind.

Jedes der folgenden Code-Beispiele können Sie mit dieser CreatePayment-Standardanfrage kombinieren:


import logging as log
from onlinepayments.sdk.api_exception import ApiException
from onlinepayments.sdk.domain.create_payment_request import CreatePaymentRequest

""" Initialisierung... """

payment_dict = {
    "order": {"amountOfMoney": {"currencyCode": "EUR", "amount": 125000}},
    "cardPaymentMethodSpecificInput": {
        "card": {
            "cvv": "123",
            "cardNumber": "5300000000000006",
            "expiryDate": "0124",
            "cardholderName": "Max Mustermann"
        },
        "paymentProductId": 3
    },
}

payment_requests = CreatePaymentRequest()
payment_requests.from_dictionary(payment_dict)
try:
    payment_response = merchant_clients.payments().create_payment(payment_request)
except ApiException as e:
   # Siehe Liste unten, wie spezifische Implementierungen 
   # von ApiException gehandhabt werden können.
Ausnahmetyp / 
HTTP-Statuscode
Code-Beispiel
ValidationException
400
except ValidationException as e:
log.error("Fehler bei Inputvalidierung:")
for error in e.errors:
if error.property_name is not None:
log.error(f"{error.code}: {error.message}")
else:
log.error(f"{error.property_name}: {error.code}: {error.message}")
AuthorizationException / 
403
except AuthorizationException as e:
log.error("Autorisierungsfehler:")
for error in e.errors:
log.error(f"{error.code}: {error.message}")
IdempotenceException
409
except IdempotenceException as e:
log.error("Idempotenz-Fehler:")
for error in e.errors:
log.error(f"{error.code}: {error.message}")}}
ReferenceException
404/409/410
except ReferenceException as e:
log.error("Falsche Objektreferenz:")
for error in e.errors:
log.error(f"{error.code}: {error.message}") }}
DirectException
500/502/503
except ApiException as e:
direct_er = [error for error in e.errors if error.http_status_code in [500, 502, 503]]
if direct_er:
log.error("Fehler bei Direkt oder einem nachgeordneten Partner/Acquirer:")
for error in direct_er:
log.error(f"{error.code}: {error.message}")}}
ApiException /
Sonstige Codes
except ApiException as e:
log.error("Plattformfehler: ")
for error in e.errors:
log.error(f"{error.code}: {error.message}")}}
CommunicationException /
300er-Codes ohne Body oder Nicht-JSON-Antwort
except CommunicationException as e:
log.error(f"Communication exception: {e}")}}

HTTP-Statuscodes 

Alle unsere Ausnahmen sind mit einem oder mehreren HTTP-Statuscodes verbunden, die die Ursache für viele mögliche Fehler angeben.

Statuscode Beschreibung Ausnahmetyp
200

Successful
Unsere Plattform hat Ihre Anfrage korrekt bearbeitet

-

201

Created
Unsere Plattform hat Ihre Anfrage korrekt bearbeitet und eine neue Ressource erstellt. Den URI dieser Ressource geben wir im Header Location der Antwort zurück

-

204

No content
Unsere Plattform hat Ihre Anfrage korrekt bearbeitet

-

Verschiedenes
CreatePaymentResult-Schlüssel ist in der Antwort

Payment Rejected
Unsere Plattform oder einer unserer nachgeordneten Partner/Acquirer hat Ihre Anfrage abgelehnt

DeclinedPaymentException

Verschiedenes
PayoutResult ist in der Antwort vorhanden

Payout Rejected
Ihre Anfrage wurde entweder von der Direct-Plattform oder von einem unserer nachgeordneten Partner/Acquirer abgelehnt

DeclinedPayoutException

Verschiedenes
RefundResult-Schlüssel ist in der Antwort

Refund Rejected
Unsere Plattform oder einer unserer nachgeordneten Partner/Acquirer hat Ihre Anfrage abgelehnt

DeclinedRefundException

400

Bad Request
Ihre Anfrage enthält Fehler, deshalb kann unsere Plattform sie nicht verarbeiten

ValidationException

403

Not Authorised
Sie versuchen, etwas zu tun, was nicht erlaubt ist oder wozu Sie nicht befugt sind

AuthorizationException

404

Not Found
Das Objekt, auf das Sie einen Zugriff versucht haben, konnte auf dem Server nicht gefunden werden

ReferenceException

409

Conflict
Ihre idempotente Anfrage hat zu einem Konflikt geführt, weil entweder: 

  • Die erste Anfrage noch nicht abgeschlossen ist oder
  • Ihre Anfrage zu einem Konflikt geführt hat. Entweder haben Sie eine doppelte Anfrage gestellt oder Sie versuchen, etwas mit einem doppelten Schlüssel zu erstellen

IdempotenceException
ReferenceException

410

Gone
Das Objekt, das Sie zu erreichen versuchen, wurde gelöscht.

ReferenceException

500

Internal Server Error
Auf unserer Plattform ist ein Fehler aufgetreten

ApiException

502 Bad Gateway
Unsere Plattform konnte eine Nachricht von einem nachgeordneten Partner/Acquirer nicht verarbeiten
ApiException
503 Service Unavailable
Der Dienst, den Sie zu erreichen versuchen, ist vorübergehend nicht verfügbar. Bitte versuchen Sie es später noch einmal
ApiException
Sonstiges Unexpected error
Ein unerwarteter Fehler ist aufgetreten
ApiException

Das SDK hat noch viel mehr zu bieten. Sehen Sie sich die folgenden Möglichkeiten an - sie helfen Ihnen beim Entwickeln der perfekten Lösung.

Verfügbare Zahlungsarten abrufen

Bevor Sie den eigentlichen Zahlungsvorgang einleiten, senden Sie eine GetPaymentProducts-Anfrage an unsere Plattform. Die Antwort enthält eine Liste der in Ihrer PSPID verfügbaren Zahlungsarten. Je nach den Vorlieben Ihrer Kunden können Sie mit folgenden CreatePayment-Anfragen eine Auswahl auf unserer Seite Hosted Checkout Page oder in Ihrer eigenen Webshop-Umgebung anbieten.


from onlinepayments.sdk.merchant.products.get_payment_product_params import GetPaymentProductParams

""" Initialisierung... """

product_params = GetPaymentProductParams()
product_params.country_code = "FR"
product_params.currency_code = "EUR"

response = merchant_client.products().get_payment_products(product_params)

Die Antwort ist eine Instanz von GetPaymentsProductsResponse mit einer Liste der verfügbaren Zahlungsprodukte.

Idempotente Anfragen senden

Eines der wichtigsten Merkmale der REST API ist die Fähigkeit, versehentlich doppelt gesendete Anfragen (z. B. Zahlungsanfragen) zu erkennen und zu verhindern. Mit dem SDK können Sie sehr einfach sicherstellen, dass Sie nur einmalige (idempotente) Anfragen an unsere Plattform senden.

Verwenden Sie das zusätzliche Argument context und setzen Sie seine Eigenschaft idempotence_key auf eine CreatePayment Anfrage. Das SDK sendet einen X-GCS-Idempotence-Key-Header mit dem Idempotenz-Schlüssel als Wert.

Wenn Sie auf diese Weise Anfragen an unsere Plattform senden, überprüfen wir Folgendes:

  • Wenn Sie eine weitere Anfrage mit demselben Idempotenz-Schlüssel senden, enthält die Antwort einen X-GCS-Idempotence-Request-Timestamp-Header. Das SDK setzt die Eigenschaft idempotence_request_timestamp des Arguments CallContext
  • Wenn die erste Anfrage noch nicht abgeschlossen ist, gibt die RESTful Server API einen Statuscode 409 zurück. Dann wirft das SDK eine IdempotenceException mit dem ursprünglichen Idempotenz-Schlüssel und dem Zeitstempel der idempotenten Anfrage

from onlinepayments.sdk.call_context import CallContext
from onlinepayments.sdk.idempotence_exception import IdempotenceException

""" Initialisierung... """

context = CallContext(idempotence_key="Ihr_Schlüssel_für_Zahlung")

payment_client = client.merchant_client.payments()
try:
    payment_response = payment_client.create_payment(payment_request, context)
except IdempotenceException as e:
    # Eine Anfrage mit demselben idempotence_key läuft noch, nach einer kurzen Pause noch einmal versuchen
    # e.idempotence_request_timestamp enthält den Wert des
    # Headers X-GCS-Idempotence-Request-Timestamp
    log.info(f"Idempotent request: {e.idempotence_request_timestamp}")
finally:
    idempotence_timestamp = context.idempotence_request_timestamp
    # idempotence_request_timestamp enthält den Wert des
    # Headers X-GCS-Idempotence-Request-Timestamp
    # wenn idempotence_timestamp nicht leer ist, war es nicht die erste Anfrage
Wenn ein Idempotenz-Schlüssel für einen Aufruf gesendet wird, der Idempotenz nicht unterstützt, ignoriert die RESTful Server API den Schlüssel und behandelt die Anfrage als erste Anfrage.


Protokollierung verwenden

Das SDK unterstützt die Protokollierung von Anfragen, Antworten und Aunsahmen. Diese Protokolle können hilfreich bei der Fehlersuche oder der Nachverfolgung einzelner Schritte im Zahlungsablauf sein.

Zum Verwenden dieser Protokollierungsfunktion müssen Sie die Klasse CommunicatorLogger implementieren. Das Python SDK stellt eine Schnittstelle bereit, die auf der Methode print (SysOutCommunicatorLogger) basiert.

Dieses Code-Beispiel zeigt das Hinzufügen eines Loggers:


from onlinepayments.sdk.log.sys_out_communicator_logger import SysOutCommunicatorLogger

""" Initialisierung... """

log_interface = SysOutCommunicatorLogger()
client.enable_logging(log_interface)
# Aufrufe ausführen ...
client.disable_logging()
Sensible Daten verschleiert das SDK im Logger

Verbindungs-Pooling

Ihre Netzwerkressourcen können Sie verwalten, indem Sie die Zahl der möglichen Verbindungen begrenzen, die das SDK aufbaut und aufrechterhält. Client-Instanzen, die wie im Kapitel SDK initialisieren beschrieben erzeugt wurden, haben ihren eigenen Verbindungspool. Mit demselben Communicator-Objekt erzeugte Client-Instanzen teilen sich einen Verbindungspool.

Wenn Sie mehrere Client-Instanzen verwenden, die sich einen einzigen Verbindungspool teilen, müssen Sie die folgenden Schritte ausführen:

  1. Einen gemeinsamen Communicator erzeugen. Dazu können Sie die Klasse Factory verwenden
  2. Mit diesem Communicator Client-Instanzen erzeugen

from onlinepayments.sdk.factory import Factory
# Gemeinsamen Communicator erzeugen.
communicator = Factory.create_communicator_from_file(
    "payments_sdk.prp", apiKey, apiSecret
)
# Einen oder mehrere Client(s) mit dem gemeinsamen Kommunikator erzeugen.
client = Factory.create_client_from_communicator(communicator)

Kommunikation anpassen

Ein Client verwendet einen Communicator zur Kommunikation mit unserer Plattform. Communicator-Implementierungen wandeln ein Anfrageobjekt um in eine HTTP-Anfrage und eine HTTP-Antwort in ein Antwortobjekt. Bei Bedarf können Sie diese Klasse erweitern. Zum Instanziieren eines Client, der Ihre eigene Implementierung von Communicator verwendet, können Sie das folgende Code-Beispiel verwenden:


from onlinepayments.sdk.factory import Factory
communicator = YourCommunicator()
client = Factory.create_client_from_communicator(communicator)

Für die meisten Anpassungen brauchen Sie Communicator jedoch nicht zu erweitern. Die Funktionalität von Communicator baut auf den folgenden Klassen auf: Authenticator, Connection, Marshaller und MetaDataProvider, ihre Implementierung kann einfach erweitert oder ersetzt werden.

Marshaller wird zum Marshalling und Unmarshalling von Anfrage- und Antwortobjekten in und aus JSON verwendet. Wir raten davon ab, dieses Modul zu ändern. Für die Kommunikation mit der Direct Plattform werden außerdem folgende Module benötigt:

  • Connection für eine oder mehrere HTTP-Verbindungen zu unserem Server
  • Authenticator zum Signieren Ihrer Anfragen
  • MetaDataProvider, der den Header mit den Metadaten Ihres Servers erstellt

Zur Vereinfachung für Sie können bei den Methoden Factory.create_communicator_from_configuration und Factory.create_communicator_from_file mit optionalen Argumenten die Module Connection, Authenticator, Marshaller oder MetaDataProvider eingestellt werden. Zum Beispiel können Sie mit dem folgenden Stück Code Ihre eigene Communicator-Implementierung verwenden:


connection = YourConnection()
communicator = Factory.create_communicator_from_file(configuration_file_name,
     api_key_id = "api_key_id",
secret_api_key = "secret_api_key",
connection = connection) client = Factory.create_client_from_communicator(communicator)

Webhooks

Der für Webhooks zuständige Teil des SDK wird als Webhooks-Helper bezeichnet. Es übernimmt in transparenter Weise sowohl die Validierung von Signaturen anhand der vom Webhook-System gesendeten Event-Bodies (einschließlich Ermittlung des geheimen Schlüssels für die Schlüssel-IDs - nicht zu verwechseln mit dem API-Schlüssel und dem API-Geheimnis) als auch das Unmarshalling dieser Bodies in Objekte. So können Sie sich auf das Wesentliche konzentrieren und brauchen nicht alle zusätzlichen Informationen selbst durchzugehen und die gewünschten Informationen zu extrahieren. Mehr über Webhooks erfahren Sie in Sie unserer speziellen Anleitung zu diesem Thema. 

Geheime Schlüssel konfigurieren

„WebhooksKey“ / „WebhooksKeySecret“ und Ihre Server-Webhooks-Endpunkte konfigurieren Sie im Merchant Portal:


key_id = "webhooks_key"
secret_key = "webhooks_key_secret"

Verwenden Sie InMemorySecretKeyStore zum Speichern eines geheimen Schlüssels für eine Schlüssel-ID:


from onlinepayments.sdk.webhooks.in_memory_secret_key_store import InMemorySecretKeyStore

key_store = InMemorySecretKeyStore()
key_store.store_secret_key(key_id, secret_key)

Schlüssel können mit folgenden Funktionen hinzugefügt oder gelöscht werden:

  • Die Schlüssel-ID, für die der geheime Schlüssel zurückgegeben werden soll
  • Einer Callback-Funktion, die entweder einen Fehler als erstes Argument oder den geheimen Schlüssel für die angegebene Schlüssel-ID als zweites Argument entgegennimmt (in diesem Fall muss das erste Argument null sein)

Das SDK stellt eine Implementierung für diese Funktion bereit: webhooks.inMemorySecretKeyStore.getSecretKey. Damit werden geheime Schlüssel aus einem speicherinternen Schlüsselspeicher abgerufen.

Schlüssel können mit folgenden Funktionen hinzugefügt oder gelöscht werden:

  • key_store.get_secret_key(key_id) zum Abrufen des gespeicherten geheimen Schlüssels für eine Schlüssel-ID
  • key_store.remove_secret_key(key_id) zum Löschen des gespeicherten geheimen Schlüssels für eine Schlüssel-ID
  • key_store.clear() zum Löschen aller gespeicherten geheimen Schlüssel

Wenn Sie eine erweiterte Speicherung brauchen, z. B. in einer Datenbank oder einem Dateisystem, empfehlen wir, eine eigene Implementierung zu schreiben.

Webhooks-Helper initialisieren

Zum Einbinden und Initialisieren des Webhooks-Helper gehen Sie wie folgt vor:

from onlinepayments.sdk.webhooks.web_hooks import Webhooks
helper = Webhooks.create_helper(key_store)

Webhooks-Helper verwenden

Sie können einen Webhook-Helper für zum Unmarshalling eingehender Events aufrufen, damit können Sie Daten in Ihrer Anwendung verarbeiten. Der Webhook-Helper nimmt die folgenden Argumente entgegen:

  • Den Body als Bytes. Das muss der rohe Body sein, wie er vom Webhook-System empfangen wird
  • Eine Liste mit Objekten, die die vom Webhooks-System empfangenen Anfrage-Header enthält. Jedes Header-Objekt muss die Eigenschaften name und value haben
try:
    webhook_event = helper.unmarshal(body, headers)
except:
    # Process an exception
# Process event

Was this page helpful?

Do you have any comments?

Thank you for your response.