Benutzerdefinierte Zahlungsintegration

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

Thema in diesem Dokument:

Drittanbieter-Zahlungsabwicklung in Monetization
Asynchrone Zahlungsabwicklung
- Rechnungen exportieren
  - Exportauftrag – CSV-Datei zu SFTP
  - Benachrichtigung - Webhook-Methode
- Zahlungen importieren
  - CSV-Datei-Import über SFTP
  - Import über API-Aufruf
    - Authentifizierung
    - Zahlungsimportanfrage
Synchrone Zahlungsabwicklung

Drittanbieter-Zahlungsabwicklung in Monetization

Die Zahlungsabwicklung durch Drittanbieter ist durch 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 Monetization kombiniert und die Zahlungen zu einem späteren Zeitpunkt importiert.

Information:

Typischerweise bestimmt Ihr Anwendungsfall, welche Verarbeitungsmethode optimal ist.

Asynchrone Zahlungsabwicklung

Für die asynchrone Zahlungsabwicklung exportieren Sie Rechnungen aus Monetization, und die Zahlungen werden vollständig außerhalb von Monetization verarbeitet. Wenn Sie die Ergebnisse der Zahlungsabwicklung haben, importieren Sie diese über CSV-Dateien oder die Monetization API.

Exportieren von Rechnungen

Sie können Rechnungen aus Monetization exportieren, indem Sie einen Rechnungs-Export-Mapper konfigurieren und einen Exportauftrag planen, der die Dateien an einen SFTP-Standort exportiert, oder indem Sie sich für die Erstellung von Rechnungen über Webhook anmelden, was eine Rechnungsanforderung an die angegebene URL-Adresse auslöst, wann immer eine neue Rechnung erstellt wird.

Exportauftrag – CSV-Datei zu SFTP

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

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

Rechnungsexporte werden über Exporting Jobs geplant, die einmalige Aufgaben oder automatisierte Abläufe für bestimmte Zeiträume sein können. Der Exportauftrag speichert die exportierte CSV-Datei im jeweiligen SFTP-Standort storage/invoice/folder_name/file_name.csv.

Beispiel für den Rechnungs-Exportauftrag
Abbildung 2: Beispiel eines Rechnungsexportjobs

Benachrichtigung - Webhook-Methode

Der Export von Rechnungen über Webhooks ermöglicht es Ihnen, Rechnungen sofort nach ihrer Erstellung zu erhalten. Dies wird erreicht, indem eine Rechnungsbenachrichtigungsregel konfiguriert wird, die jede erstellte Rechnung als JSON-Body-Anfrage an die angegebene URL-Adresse sendet, zusammen mit allen vorkonfigurierten Header-Optionen.

Abbildung 3: Beispiel der Konfiguration eines Webhooks zur Rechnungserstellung

Zahlungen importieren

Sie können Zahlungstransaktionen in Monetization importieren, indem Sie einen Zahlungsimport-Mapper konfigurieren und die Zahlungs-CSV-Dateien an den SFTP-Eingangsstandort hochladen oder die REST-API von Monetization nutzen.

CSV-Dateiimport über SFTP

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

Der Zahlungsmapper ermöglicht das Mapping von CSV-Spalten auf Parameter von Zahlungstransaktionen und die Definition eines Dateiprefixes, der 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.

Abbildung 4: Beispiel der Konfiguration eines Zahlungsimport-Mappers

Import über API-Aufruf

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

Hinweis:

Ein Benutzer muss zuerst authentifiziert werden, um mit der Monetization API zu kommunizieren.

Authentifizierung

Die Monetization API verwendet die Bearer-Token-Authentifizierung:

Führen Sie die Authentifizierungsanfrage mit Benutzername, Passwort und spezifischem Standortcode aus.
Ernten Sie das token aus der Antwort.
Setzen Sie den Authorization-Header auf Bearer <token> in den kommenden Anfragen.
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"
}

Zahlungsimportanfrage

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

Synchronisierte Zahlungsabwicklung

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

Sie konfigurieren Monetization, um anzugeben, wohin die mit der Zahlungsabwicklung verbundenen Anfragen gesendet werden sollen, und Monetization hat vordefinierte Antworten, die es im Gegenzug erwartet. Diese Verarbeitungsmethode ermöglicht die Speicherung von Zahlungsreferenzen bei den Kunden und unterstützt automatisierte Zahlungsabholprozesse.

Für Monetization ist der Integrationsprozess praktisch derselbe wie eine sofort einsatzbereite Integration 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
Autorisieren
Erfassen
Belasten

Einrichtung des Drittanbieter-Zahlungsanbieters

Um eine Integration eines Drittanbieter-Zahlungsanbieters einzurichten, konfigurieren Sie ein Profil für das Drittanbieter-Zahlungsgateway und geben Sie die URL an, an die Monetization Anfragen senden soll.

Dies kann über die Benutzeroberfläche unter Systemkonfiguration Zahlungsgateways oder durch Erstellen eines Zahlungsgateway-Profils über die Monetization REST-API erreicht werden.

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 zu Ihrem Zahlungsgateway"
    }
}

Kundenoperationen

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

Kunde erstellen (ohne Karte)

Erstellt einen Kunden als Objekt im Zahlungsanbieterdienst.

Anfrage, die von Monetization gesendet wird:

{
    "action": "create_customer",
    "content": {
        "customer": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Unternehmen",
            "email": "john_anderson@testmail123. HTTP-Status: 201 Erstellt

```json
{
    "customer": {
        "id": "payment_provider_customer_id"
    }
}

Kunde aktualisieren

Aktualisiert ein Kundenobjekt im Zahlungsdienstleister.

Anfrage gesendet von Monetization:

{
    "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 Kein Inhalt

Kein Antwortkörper

Kunde lesen

Liest ein Kundenobjekt vom Zahlungsdienstleister. ```json { “action”: “read_customer”, “content”: { “id”: “payment_provider_customer_id_1” } }


**Erwartete Antwort:**

HTPP-Status: 200 OK

```json
{
    "content": {
        "customer": {
            "id": "payment_provider_customer_id_1",
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Unternehmen",
            "email": "john_anderson@testmail123.com",
            "phone": "003861234335",
            "tax_identifier": "123543569596"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Anderson",
            "company": "Unternehmen",
            "street_address": "Adresse Straße 12",
            "locality": "Name der Stadt",
            "postal_code": "84116",
            "region": "Region",
            "country_code": "SI",
            "country_name": "Slowenien"
        },
        "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"
            }
        ]
    }
}

Kunde löschen

Löscht ein Kundenobjekt aus dem Zahlungsdienstanbieter.

Anfrage gesendet von Monetization:

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

Erwartete Antwort:

HTTP-Status: 204 Kein Inhalt

Kein Antwortkörper

Kartenoperationen

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

Einrichtung (Einrichtungsanfrage für Karte)

Löst einen Prozess aus, bei dem ein Kunde Kreditkartendaten bereitstellen kann, die tokenisiert und in Monetization gespeichert werden. Bei einer Anfrage zur Hinzufügung einer neuen Kreditkarte wird Monetization eine Einrichtungsanfrage an Ihre Integrationskomponente senden. Ihr Integrationskomponente muss jegliche Logik im Zusammenhang mit den Zahlungsanbieter-Diensten verarbeiten und eine Weiterleitungs-URL an Monetization als Antwort zurückgeben. Der Kunde wird dann an die bereitgestellte URL weitergeleitet, wo Ihr vom Zahlungsanbieter gehostetes Formular die Kartendaten des Kunden erfasst und tokenisiert.

Abbildung 5: Kreditkarten-Einrichtung

Anfrage, die von Monetization gesendet wurde:

{
    "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": "Slowenien"
        },
        "custom_attributes": {
            "callback_url": "https://callbackurl.com"
        }
    }
}

Erwartete Antwort:

HTTP-Status: 201 Erstellt

{
    "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 des Kreditkartenreferenz über die Zahlungsanbieter-Dienste zu verarbeiten, und entfernt dann die Referenz von Monetization bei Erfolg. Anfrage gesendet von Monetization:

{
    "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 Antwortkörper

Transaktionsoperationen

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

autorisierung
erfassung
belastung
stornierung
rückerstattung

Autorisierung

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

Anfrage gesendet von Monetization:

{
    "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": "Nachricht vom Anbieter, falls vorhanden",
    "code": "Code vom Anbieter, falls vorhanden"
}

Erfassung

Die Erfassung bezieht sich auf die Sammlung von autorisierten Geldern aus einer vorherigen Autorisierungsanfrage. Der zu sammelnde Betrag kann gleich oder niedriger als der autorisierte Betrag sein.

Alle nicht gesammelten autorisierten Gelder werden vom Zahlungsanbieter-Dienst an den Kunden zurückgegeben. Die folgende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieterdienstes behandeln und eine Antwort zurückgeben sollte. Anfrage gesendet von Monetization:

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

Erwartete Antwort:

HTTP-Status: 202 Akzeptiert

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 10.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Nachricht vom Anbieter, falls vorhanden",
    "code": "Code vom Anbieter, falls vorhanden"
}

charge

Charge autorisiert und erfasst Gelder als eine einzige sofortige Transaktion. Die folgende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieters verarbeiten und eine Antwort zurückgeben sollte.

Anfrage gesendet von Monetization:

{
    "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 Akzeptiert

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Nachricht vom Anbieter, falls vorhanden",
    "code": "Code vom Anbieter, falls vorhanden"
}

void

Die Void-Operation hebt eine Autorisierungs-Transaktion auf und gibt die autorisierten Gelder frei. Die folgende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieters verarbeiten und eine Antwort zurückgeben sollte. Anfrage gesendet von Monetization:

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

Erwartete Antwort:

HTTP-Status: 202 Akzeptiert

{
    "transaction_id": "payment_provider_transaction_id",
    "time": "1650629967000",
    "success": true,
    "message": "Nachricht vom Anbieter, falls vorhanden",
    "code": "Code vom Anbieter, falls vorhanden"
}

Rückerstattung

Die Rückerstattung gibt dem Kunden Geld zurück und verweist auf eine vorherige Charge- oder Capture-Transaktion. Die folgende Anfrage wird an Ihre Integrationskomponente gesendet, die die Logik des Zahlungsanbieterdienstes verarbeiten und eine Antwort zurückgeben sollte.

Anfrage gesendet von Monetization:

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

Erwartete Antwort:

HTTP-Status: 202 Akzeptiert

{
    "transaction_id": "payment_provider_transaction_id",
    "amount": 25.5,
    "currency": "EUR",
    "time": "1650629967000",
    "success": true,
    "message": "Nachricht vom Anbieter, falls vorhanden",
    "code": "Code vom Anbieter, falls vorhanden"
}

Fehlerbehandlung

Falls eine Operation in Ihrer Integrationskomponente nicht erfolgreich ist, geben Sie einen Status außerhalb des Bereichs 200-300 und die Fehlermeldung im Antwortkörper zurück.