Ruby SDK

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

Durch Auswahl des Ruby SDK können Sie:

• auf eine kompakte, bequeme und anpassbare Weise auf alle Funktionen unserer RESTful API zugreifen
• alle serverseitigen Integrationsmodi unserer Plattform (Hosted Checkout Page / Hosted Tokenization Page / Server-to-server) nutzen
• alle API-Aufrufe in Verbindung mit der Zahlungsabwicklung ausführen (d. h. CreateHostedCheckout, CreatePayment, RefundPayment und vieles mehr)

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

• Ruby 2.3 oder höher

Mit GEM package manager installieren Sie die neueste Version des Ruby SDK mit dem Befehl:

gem install onlinepayments-sdk-ruby

Nähere Einzelheiten erfahren Sie auf GitHub. 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.

Um das SDK zur Verbindung Ihres Systems mit unserer Plattform zu nutzen, müssen Sie es zunächst initialisieren.

Zum Initialisieren des SDK müssen Sie:

• Ein Test- und Live-Konto einrichten
• Eine Konfigurationsdatei mit Eigenschaften anlegen
  
  

  ---
  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
  

  
  require 'onlinepayments/sdk'
  include OnlinePayments::SDK
  
  client = Factory.create_client_from_file(configuration_file_name, apiKey, apiSecret)
  merchant_client = client.merchant(merchantId)

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

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

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

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 zu dieser URL weiterleiten. Sobald der Kunde die Seite Hosted Checkout Page besucht, wird der Zahlungsvorgang dort fortgesetzt.

Sehen Sie sich unsere Testfälle auf GitHub mit vollständigen Codebeispielen an. 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
• Transaktionsstatus abrufen
• Wartungsmaßnahme durchführen

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

Nachfolgend finden Sie Codebeispiele für bestimmte Integrationsmodi:

• Hosted Checkout Page
• Hosted Tokenization Page
• Server-to-server

Hosted Checkout Page

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

# Initialisierung...

include OnlinePayments::SDK::Domain
 
order_hash = {
  "order" => {"amountOfMoney" => {"currencyCode" => "EUR", "amount" => 123}}
}
 
hosted_checkout_client = merchant_client.hosted_checkout()
hosted_checkout = CreateHostedCheckoutRequest.new()
hosted_checkout.from_hash(order_hash)
response = hosted_checkout_client.create_hosted_checkout(hosted_checkout)

Hosted Tokenization Page

Um diese Integrationsmethode zu verwenden, müssen Sie:

• zunächst eine Vorlage in Ihr Konto hochladen. Für Testzwecke können Sie unsere Testvorlage auf GitHub verwenden.
• eine CreateHostedTokenizationSession-Anfrage erstellen. Sie muss mindestens ein Order-Objekt enthalten.

# Initialisierung...
include OnlinePayments::SDK::Domain
 
request = CreateHostedTokenizationRequest.new()
request.from_hash({"variant" => "template.html"})
hosted_t_client = merchant_client.hosted_tokenization()
response = hosted_t_client.create_hosted_tokenization(request)

From response retrieve hosted_tokenizationId and 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 tokenId (siehe Infobox) zum Erstellen der eigentlichen Zahlung über den Integrationsmodus Server-to-server.

token = hosted_t_client.get_hosted_tokenization(t_id).token.id
# Hash mit allen notwendigen Daten für Zahlungsanfrage
 payment_hash = {
    "order" => {
      "amountOfMoney" => {
        "currencyCode" => "EUR", 
        "amount" => 12300}},
    "CardPaymentMethodSpecificInput" => {
      "token" => token}}
 
payment_request = CreatePaymentRequest.new_from_hash(payment_hash)
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...
include OnlinePayments::SDK::Domain
 
# Hash mit allen notwendigen Daten für Zahlungsanfrage
payment_hash = {
    "order" => {"amountOfMoney" => {"currencyCode" => "EUR", "amount" => 125000}},
    "cardPaymentMethodSpecificInput" => {
        "card" => {
            "cvv" => "123",
            "cardNumber" => "5300000000000006",
            "expiryDate" => "0124",
            "cardholderName" => "John Doe"},
        "paymentProductId" => 3}}
 
payment_request = CreatePaymentRequest.new_from_hash(payment_hash)
payment_response = merchant_client.payments().create_payment(payment_request)

Transaktionsstatus abrufen

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

• GetHostedCheckout
• GetPayment
• GetPaymentDetails
• GetCaptures
• GetRefunds

Eine GetPayment Anfrage sieht so aus:

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

Weitere Informationen über Statuswerte finden Sie auf der Dokumentationsseite zu Statuswerten.

Wartungsmaßnahme 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

# Initialisierung...
include OnlinePayments::SDK::Domain
 
payment_id = payment_response.payment.id
capture_request = CapturePaymentRequest.new()
capture_request.from_hash({"amount" => 125000, "isFinal" => true})
merchant_client.payments().capture_payment(payment_id, capture_request)

RefundPayment

# Initialisierung...
include OnlinePayments::SDK::Domain
 
payment_id = payment_response.payment.id
refund_hash = {"amountOfMoney" => {"currencyCode" => "EUR", "amount" => 125000}}
refund_request = RefundRequest.new_from_hash(refund_hash)
# Objekt RefundResponse abrufen
response = merchant_client.payments().refund_payment(payment_id, refund_request)

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. 

# Initialisierung ...
include OnlinePayments::SDK::Domain
 
begin
    payment_response = merchant_client.payments().create_payment(payment_request)
    payment_id = payment_response.payment.id
rescue DeclinedPaymentException => e
    payment = e.create_payment_result.payment
    payment_id = payment.id
    payment_status = payment.status
    handle_error(payment)
end
 
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)
end 

# Initialisierung ...
include OnlinePayments::SDK::Domain
 
payment_response = merchant_client.payments().create_payment(payment_request)
payment_id = payment_response.payment.id
 
refund_id = nil
begin
  refund_request = RefundRequest.new_from_hash(refund_hash)
  refund_response = merchant_client.payments().refund_payment(payment_id, refund_request)
  refund_id = refund_response.id
rescue DeclinedRefundException => e
  refund_result = e.refund_result
  handle_error(refund_result)
end
 
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)
end

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:

# Initialisierung ...
include OnlinePayments::SDK::Domain
log = Logger.new(STDOUT)

# Hash mit allen notwendigen Daten für Zahlungsanfrage
payment_hash = {
    "order" => {"amountOfMoney" => {"currencyCode" => "EUR", "amount" => 124000}},
    "cardPaymentMethodSpecificInput" => {
        "card" => {
            "cvv" => "123",
            "cardNumber" => "5300000000000006",
            "expiryDate" => "0124",
            "cardholderName" => "Ruby Ruby"},
        "paymentProductId" => 3}}
 
payment_request = CreatePaymentRequest.new_from_hash(payment_hash)
begin
  payment_response = merchant_client.payments().create_payment(payment_request)
rescue ApiException => e
  # Die folgende Liste zeigt, wie spezifische Implementierungen 
  # von ApiException behandelt werden können.
end

rescue ValidationException => e 
  log.error("Fehler bei Inputvalidierung:") 
  e.errors.each do |error|
    if not error.property_name.nil?
      log.error("#{error.code}: #{error.message}")
    else
      log.error("#{error.property_name}: #{error.code}: #{error.message}")
    end
  end
end

rescue AuthorizationException => e
  log.error("Autorisierungsfehler:") 
  e.errors.each do |error|
    log.error("#{error.code}: #{error.message}") 
  end 
end

rescue IdempotenceException => e
  log.error("Idempotenz-Fehler:") 
    e.errors.each do |error|
      log.error("#{error.code}: #{error.message}")
    end
end

rescue ReferenceException => e
  log.error("Falsche Objektreferenz:") 
    e.errors.each do |error| 
      log.error("#{error.code}: #{error.message}")
    end 
end

rescue ApiException => e 
  direct_er = e.errors.select{|error| [500, 502, 503].include? error.http_status_code}
  if not direct_er.empty? 
    log.error("Fehler bei Direkt oder einem nachgeordneten Partner/Acquirer:")
    direct_er.each do |error|
      log.error("#{error.code}: #{error.message}")
    end
  end
end

rescue ApiException => e 
  log.error("Plattformfehler: ") 
  e.errors.each do |error|  
    log.error("#{error.code}: #{error.message}") 
  end 
end

rescue CommunicationException => e
  log.error("Kommunikationsausnahme: #{e}")
end

HTTP-Statuscodes 

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

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

• Verfügbare Zahlungsarten abrufen
• Idempotente Anfragen senden
• Protokollierung verwenden
• Verbindungs-Pooling
• Kommunikation anpassen
• Webhooks

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 eine Auswahl auf unserer Hosted Checkout Page oder in Ihrer eigenen Webshop-Umgebung mit nachfolgenden CreatePayment-Anfragen anbieten.

# Initialisierung...
include OnlinePayments::SDK::Merchant::Products

product_params = GetPaymentProductParams.new
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

# Initialisierung...

context = CallContext.new(idempotence_key="your_key_for_payment") 
payment_client = client.merchant_client(merchantId).payments()

begin
  payment_response = payment_client.create_payment(payment_request, context)
rescue IdempotenceException => e
  # Eine Anfrage mit demselben idempotence_key läuft noch, nach einer kurzen Pause noch einmal versuchen
  # e.idempotence_requesttimestamp enthält den Wert des
  # Headers X-GCS-Idempotence-Request-Timestamp
  log.info("Idempotent request: #{e.idempotence_request_timestamp}")
ensure
  idempotence_timestamp = context.idempotence_request_timestamp
  # idempotence_requesttimestamp enthält den Wert des
  # Headers X-GCS-Idempotence-Request-Timestamp
  # wenn idempotence_request_timestamp nicht leer ist, war dies nicht die erste Anfrage
end

Protokollierung verwenden

Das SDK unterstützt die Protokollierung von Anfragen, Antworten und Exceptions. 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 Ruby SDK bietet zwei Beispielimplementierungen für Protokollierung nach stdout (StdoutCommunicatorLogger) und Protokollierung in einen Logger (RubyCommunicatorLogger).

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

# Initialisierung...
logger = RubyCommunicatorLogger.new(Logger.new('logfile.log'), Logger::INFO)
client.enable_logging(logger)
# Aufrufe ausführen ...
client.disable_logging()

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. Client-Instanzen mit diesem Communicator erzeugen

require 'onlinepayments/sdk'
include OnlinePayments::SDK
# 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:

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 Antwortobjekte in und aus JSON verwendet. Wir raten davon ab, dieses Modul zu ändern. Für die Kommunikation mit der PAYONE E-Payment 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.new
communicator = Factory.create_communicator_from_file(configuration_file_name,
                                           "api_key_id",
                                           "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. Er ü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:

include OnlinePayments::SDK::Webhooks
key_store = InMemorySecretKeyStore.instance
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:

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 string. 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 Methoden name und value haben, die name bzw. value des Headers zurückgeben

begin
  webhook_event = helper.unmarshal(body, headers)
rescue
  # Process an exception
end
# Process event