Benutzerdefinierte Zahlungsintegration

Dieses Dokument erklärt, wie Tridens Monetization die Unterstützung der Zahlungsabwicklung für Drittanbieter ermöglicht, die nicht standardmäßig unterstützt werden, oder für Fälle, in denen Sie entscheiden, die Logik der Zahlungsabwicklung außerhalb von Tridens Monetization über Ihre Integrationsprozesse zu handhaben.
Kategorie:

Themen in diesem Dokument:

Zahlungsabwicklung durch Drittanbieter in Tridens Monetization

Die Zahlungsabwicklung durch Drittanbieter ist über zwei Methoden erreichbar, synchron und asynchron. Die synchrone Methode erfordert sofortige Antworten von Ihrer Zahlungsintegrationskomponente, während die asynchrone Methode das Extrahieren von Rechnungen aus Tridens Monetization und das spätere Importieren der Zahlungen kombiniert.

Asynchrone Zahlungsabwicklung

Für die asynchrone Zahlungsabwicklung exportieren Sie Rechnungen aus Tridens Monetization, und die Zahlungen werden vollständig außerhalb von Tridens Monetization verarbeitet. Sobald Sie Ergebnisse der Zahlungsabwicklung haben, importieren Sie diese über CSV (Comma-Separated Values)-Dateien oder die Tridens Monetization API (Application Programming Interface).

Exportieren von Rechnungen

Sie können Rechnungen aus Tridens Monetization exportieren, indem Sie einen Rechnungsexport-Mapper konfigurieren und einen Export-Job planen, der die Dateien an einen SFTP (Secure File Transfer Protocol)-Speicherort exportiert, oder indem Sie eine Rechnungserstellung über Webhook abonnieren, was bei jeder Erstellung einer neuen Rechnung eine Rechnungsanfrage an die angegebene URL (Uniform Resource Locator)-Adresse auslöst.

Export-Job – CSV-Datei an SFTP

Um Rechnungen als CSV-Dateien zu exportieren, muss ein Rechnungsexport-Mapper konfiguriert werden, um Rechnungsparameter den CSV-Dateispalten zuzuordnen. Die Benutzeroberfläche von Tridens Monetization ermöglicht eine solche Konfiguration unter Business configuration Export Invoice mappers.

Beispiel für die Konfiguration des Rechnungsexport-Mappers Abbildung 1: Beispiel für die Konfiguration des Rechnungsexport-Mappers

Rechnungsexporte werden über Exportjobs geplant, die einmalige Aufgaben sein können oder so automatisiert werden können, dass sie für bestimmte Zeiträume ausgeführt werden. Der Exportjob speichert die exportierte CSV-Datei am jeweiligen SFTP-Speicherort storage/invoice/folder_name/file_name.csv.

Beispiel für einen Rechnungsexport-Job Abbildung 2: Beispiel für einen Rechnungsexport-Job

Benachrichtigung - Webhook-Methode

Das Exportieren von Rechnungen über Webhooks ermöglicht es Ihnen, Rechnungen sofort nach der Erstellung zu erhalten. Dies wird durch die Konfiguration einer Invoice Notification Rule erreicht, die jede erstellte Rechnung als JSON (JavaScript Object Notation)-Body-Anfrage an die angegebene URL-Adresse sendet, zusammen mit allen vorkonfigurierten Header-Optionen.

Beispiel für die Konfiguration des Webhooks zur Rechnungserstellung Abbildung 3: Beispiel für die Konfiguration des Webhooks zur Rechnungserstellung

Importieren von Zahlungen

Sie können Zahlungstransaktionen in Tridens Monetization importieren, indem Sie einen Zahlungsimport-Mapper konfigurieren und die Zahlungs-CSV-Dateien am SFTP-Eingabespeicherort hochladen oder indem Sie die REST (Representational State Transfer)-API von Tridens Monetization nutzen.

CSV-Datei-Import über SFTP

Damit Tridens Monetization Zahlungstransaktionen über CSV-Dateien importieren kann, muss ein Zahlungsimport-Mapper konfiguriert sein. Die Konfiguration ist über die Benutzeroberfläche von Tridens Monetization unter Business configuration Import Payment mappers möglich.

Der Payment Mapper ermöglicht die Zuordnung von CSV-Spalten zu Zahlungstransaktionsparametern und die Definition eines Dateipräfixes, das in den hochgeladenen Dateien vorhanden sein muss.

Dateien werden auf dem SFTP-Server im Ordner edl/input hochgeladen und je nach Verarbeitungsergebnis in die Ordner edl/processed, edl/successful, edl/error und edl/rejected verschoben.

Beispiel für die Konfiguration des Zahlungsimport-Mappers Abbildung 4: Beispiel für die Konfiguration des Zahlungsimport-Mappers

Import über API-Aufruf

Um eine Zahlungstransaktion über die Tridens Monetization API zu importieren, senden Sie eine JSON-Anfrage mit Transaktionsdetails an die Tridens Monetization REST-API.

Authentifizierung

Die Tridens Monetization API verwendet die Bearer-Token-Authentifizierung:

  1. Führen Sie die Authentication-Anfrage mit Benutzernamen, Passwort und spezifischem Standortcode aus.
  2. Entnehmen Sie das token aus der Antwort.
  3. Setzen Sie den Authorization-Header in den kommenden Anfragen auf Bearer <token>.
  4. Das Token läuft nach 5 Minuten ab.
URL: {{api_url}}/authenticate

Headers
Content-Type:application/json

Body
{
    "username": "your_monetization_username",
    "password": "password",
    "site_code": "your_monetization_site_code - subdomain"
}
Zahlungsimport-Anfrage
URL: {{api_url}}/api/v1/import

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}
Data-Type:Payment

Body
{
    "invoice_id": 123,
    "transaction_identifier": "T-1233-cew3-445f-feew3",
    "amount": 150,
    "transaction_time": 1600613169000,
    "currency": "EUR",
    "method": "other",
    "type": "charge",
    "provider": "stripe"
}

Synchrone Zahlungsabwicklung

Die synchrone Zahlungsabwicklung erfordert eine synchrone Kommunikation zwischen Tridens Monetization und Ihrer Zahlungsintegrationskomponente. Diese Abwicklungsmethode ermöglicht Kredit-/Debitkartenautorisierungen und sofortige Zahlungen.

Sie konfigurieren Tridens Monetization, um anzugeben, wohin die Anfragen im Zusammenhang mit der Zahlungsabwicklung gesendet werden sollen, und Tridens Monetization hat vordefinierte Antworten, die es als Rückmeldung erwartet. Diese Abwicklungsmethode ermöglicht die Speicherung von Zahlungsmethodenreferenzen bei den Kunden und unterstützt automatisierte Zahlungseinzugsprozesse.

Für Tridens Monetization ist der Integrationsprozess praktisch derselbe wie eine Standardintegration mit einem bestehenden Anbieter (Stripe, Braintree usw.). Die Kommunikation erfolgt jedoch über eine von Ihnen entwickelte Komponente, die als Gateway zu Ihrem lokalen Zahlungsanbieter fungiert.

Wesentliche Operationen zur Unterstützung der synchronen Zahlungsabwicklung:

  • Setup Intent
  • Authorize
  • Capture
  • Charge

Einrichtung eines Drittanbieters für Zahlungen

Um eine Integration eines Drittanbieters für Zahlungen einzurichten, konfigurieren Sie ein Profil für ein Zahlungs-Gateway eines Drittanbieters und geben Sie die URL an, an die Tridens Monetization Anfragen senden soll.

Dies ist über die Benutzeroberfläche unter System configuration Payment gateways oder durch Erstellen eines Payment Gateway Profile über die Tridens Monetization REST-API erreichbar.

URL: {{api_url}}/api/v1/payment-gateway-profiles

Headers
Content-Type:application/json
Authorization:Bearer {{auth_token}}

Request
{
    "provider": "third-party",
    "headers": {
        "PGW_URL": "URL to your payment gateway"
    }
}

Kundenoperationen

Kundenoperationen gelten nur in Fällen, in denen der Drittanbieter für Zahlungen die Kundenverwaltung unterstützt. Wenn der Zahlungsanbieter die Kundenverwaltung nicht unterstützt, können die Kunden-ids durch einen beliebigen Wert ersetzt werden (z. B. Unix-Zeitstempel der Anfrage).

Kunden erstellen (ohne Karte)

Erstellt einen Kunden als Objekt beim Dienst des Zahlungsanbieters.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Erwartete Antwort:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

Kunden aktualisieren

Aktualisiert ein Kundenobjekt beim Dienst des Zahlungsanbieters.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "update_customer",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
    }
}

Erwartete Antwort:

HTTP Status: 204 No Content

Kein Response Body

Kunden lesen

Liest ein Kundenobjekt vom Dienst des Zahlungsanbieters.

{
    "action": "read_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Erwartete Antwort:

HTPP Status: 200 OK

{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        },
        "credit_cards": [
            {
                "is_default": true,
                "card_holder_name": "John Anderson",
                "expiration_month": "03",
                "expiration_year": "2026",
                "type": "Mastercard",
                "token": "payment_provider_card_token",
                "last_four": "1234"
            }
        ]
    }
}

Kunden löschen

Löscht ein Kundenobjekt vom Dienst des Zahlungsanbieters.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "delete_customer",
    "content": {
        "id": "payment_provider_customer_id_1"
    }
}

Erwartete Antwort:

HTTP Status: 204 No Content

Kein Response Body

Kartenoperationen

Kartenoperationen beziehen sich auf das Einrichten oder Entfernen von Kredit- und Debitkarten.

Einrichtung (Setup Card Request)

Löst einen Prozess aus, bei dem ein Kunde Kreditkartendaten angeben kann, die tokenisiert und in Tridens Monetization gespeichert werden. Auf eine Anfrage zum Hinzufügen einer neuen Kreditkarte sendet Tridens Monetization eine Setup-Anfrage an Ihre Integrationskomponente.

Ihre Integrationskomponente muss jegliche Logik im Zusammenhang mit den Diensten des Zahlungsanbieters verarbeiten und eine Redirect-URL als Antwort an Tridens Monetization zurückgeben. Der Kunde wird dann zur angegebenen URL weitergeleitet, wo Ihr vom Zahlungsanbieter gehostetes Formular die Kartendaten des Kunden erfasst und tokenisiert.

Einrichtung der Kreditkarte Abbildung 5: Einrichtung der Kreditkarte

Von Tridens Monetization gesendete Anfrage:

{
    "action": "setup",
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Company",
            "street_address": "Address street 12",
            "locality": "Name of City",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slovenia "
        }
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

Erwartete Antwort:

HTTP Status: 201 Created

{
    "customer": {
        "id": "payment_provider_customer_id"
    },
    "redirect_url": "https://card-data-collection-form.com"
}

Karte löschen

Sendet eine Anfrage an Ihre Integrationskomponente, um die Logik zur Entfernung der Kreditkartenreferenz über die Dienste des Zahlungsanbieters zu verarbeiten, und entfernt die Referenz bei Erfolg aus Tridens Monetization.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "delete_credit_card",
    "content": {
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Erwartete Antwort:

HTTP Status: 204 No Content

Kein Response Body

Transaktionsoperationen

Transaktionsoperationen beziehen sich auf transaktionale Aktionen, die auf gespeicherten Zahlungsmethoden-Tokens (Kredit-/Debitkarte) ausgeführt werden. Diese Aktionen umfassen:

Autorisierung

Die Autorisierung wird verwendet, um Gelder auf der Zahlungsmethode eines Kunden zu autorisieren (sperren). Autorisierungen können später erfasst (Captured) oder storniert (Voided) werden. Die untenstehende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieter-Dienstes verarbeiten und eine Antwort zurückgeben sollte.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "authorize",
    "content": {
        "amount": 20.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Erwartete Antwort:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Erfassung

Die Erfassung bezieht sich auf den Einzug autorisierter Gelder aus einer vorherigen Authorization-Anfrage. Der einzuziehende Betrag kann gleich oder niedriger als der autorisierte Betrag sein.

Nicht eingezogene autorisierte Gelder werden vom Zahlungsanbieter-Dienst an den Kunden zurückgegeben. Die untenstehende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieter-Dienstes verarbeiten und eine Antwort zurückgeben sollte.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "capture",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Erwartete Antwort:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Belastung

Charge autorisiert und erfasst Gelder in einer einzigen sofortigen Transaktion. Die untenstehende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieter-Dienstes verarbeiten und eine Antwort zurückgeben sollte.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "charge",
    "content": {
        "amount": 25.5,
        "currency": "EUR",
        "customer": {
            "id": "provider_customer_id_34"
        },
        "credit_card": {
            "token": "provider_card_token_x23423532"
        }
    }
}

Erwartete Antwort:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Stornierung

Die Void-Operation storniert eine Authorization-Transaktion und gibt die autorisierten Gelder frei. Die untenstehende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieter-Dienstes verarbeiten und eine Antwort zurückgeben sollte.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "void",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234"
    }
}

Erwartete Antwort:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Rückerstattung

Die Rückerstattung gibt Gelder an den Kunden zurück und bezieht sich auf eine vorherige Charge- oder Capture-Transaktion. Die untenstehende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieter-Dienstes verarbeiten und eine Antwort zurückgeben sollte.

Von Tridens Monetization gesendete Anfrage:

{
    "action": "refund",
    "content": {
        "transaction_id": "provider_transaction_id_t2134234",
        "amount": 10.5
    }
}

Erwartete Antwort:

HTTP Status: 202 Accepted

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Message from provider if given",
    "code": "Code from provider if given"
}

Fehlerbehandlung

Falls eine Operation auf Ihrer Integrationskomponente nicht erfolgreich ist, geben Sie einen Status außerhalb des Bereichs von 200-300 und die Fehlermeldung im Response Body zurück.

Vorherige
Geräte