# Third Party Payment Backends

Als Third Party Payment Backend können Sie Zahlungen von Kunden empfangen und abwickeln.

Ein Payment Backend ist eindeutig durch einen backend_type identifiziert. Ein Payment Backend kann unterschiedliche Zahlungsmittel unterstützen. Diese unterschiedlichen Zahlungsmittel werden source_type genannt. Zum Beispiel unterstützt das eingebaute Zahlungsbackend backend_type=stripe die Zahlungsmittel SEPA Lastschrift (source_type=sepa) und Kreditkarte (source_type=credit).

# Zahlungsablauf

Nachdem eine Zahlung (Payment) erstellt wird, ist sie im status pending. Das bedeutet das System wartet darauf, dass Ihr Zahlungsbackend die Zahlung abarbeitet. Der Zustand einer Zahlung kann nicht direkt geändert werden, sondern es müssen alle Zustandsänderungen durch das Anlegen von PaymentLog Objekten gemacht werden.

Ein Eintrag im PaymentLog trägt immer einen Grund mit sich, wodurch die Änderung zustandegekommen ist. Diese Grund ist im Feld reason angegeben.

no_payment_method Dieser Grund wird automatisch von der Platform gesetzt, falls der Kunde kein Zahlungsmittel hinterlegt hat. Die Zahlung schlägt dadurch Fehl.
requires_user_action Diese Grund gibt an, dass der Benutzer etwas tun muss um die Zahlung abzuschließen. Dies wird zurzeit nur für SCA (opens new window) bei Kreditkarten verwendet. Der Zustand der Zahlung bleibt auf pending.
processing Die Zahlung ist in Bearbeitung. Der Zustand der Zahlung bleibt auf pending.
failed Die Zahlung ist Fehlgeschlagen. Der Zustand der Zahlung geht zu failed. Dieser Grund kann nur angegeben werden wenn das Payment zuvor im Zustand pending war.
canceled Die Zahlung wurde abgebrochen. Der Zustand der Zahlung geht zu failed. Dieser Grund kann nur angegeben werden wenn das Payment zuvor im Zustand pending war.
disputed Die Zahlung wurde Angefochten. Das Payment Backend kann diesen Grund angeben, wenn ein Kunde beim Zahlungsbackend sich über eine Falsche abbuchung beschwert. Für Disputes können beim Backend Kosten anfallen. Diese kosten müssen beim Erstellen vom PaymentLog mitübergeben werden. Zum Beispiel bei SEPA Disputes sind immer 7.5€. Der Zustand der Zahlung geht zu failed. Dieser Grund kann nur angegeben werden wenn das Payment zuvor im Zustand success war.
refunded Die Zahlung wurde Rückerstattet. Der Betrag der Zahlung wird vom Kundenkonto abgezogen. Zurzeit können keine Teil-Rückerstattungen gemacht werden. Der Zustand der Zahlung geht zu failed. Dieser Grund kann nur angegeben werden wenn das Payment zuvor im Zustand success war.
success Die Zahlung ist Erfolgreich. Der Betrag wird auf das Kundenkonto gutgeschrieben. Der Zustand der Zahlung geht zu success. Dieser Grund kann nur angegeben werden wenn das Payment zuvor im Zustand pending war.

# API Objekte

# PaymentBackend

Das Payment Backend verbindet Ihren Mandanten mit einem Zahlungsbackend. Es ist nicht möglich selbst ein PaymentBackend Objekt anzulegen, bitte kontaktieren Sie uns hierfür. Sie können jedoch alle, mit ihrem Konto verbundenen Backends abrufen:

Endpunkte:

GET https://api.parken.arivo.app/payment/payment_backend/
GET https://api.parken.arivo.app/payment/payment_backend/:id/

# $> curl "https://api.parken.arivo.app/payment/payment_backend/" -H "Authorization: APIToken ..."

{
  "count": 1,
  "results": [
    {
      "id": "93efc3e5-9faf-447a-b848-e9d181264397",
      "provider_id": "77d872ea-5ded-4a3d-98fe-90c5e44d0bcc",
      "name": "",
      "type": "primeo"
    }
  ]
}

# PaymentSource

Das PaymentSource stelle eine Zahlungsart von ihrem Backend dar. Es ist nicht möglich selbst ein PaymentSource Objekt anzulegen, bitte kontaktieren Sie uns hierfür. Sie können jedoch alle, mit ihrem Konto verbundenen sources abrufen:

Endpunkte:

GET https://api.parken.arivo.app/payment/payment_source/
GET https://api.parken.arivo.app/payment/payment_source/:id/

# $> "https://api.parken.arivo.app/payment/payment_source/" -H "Authorization: APIToken ..."

{
  "count": 1,
  "results": [
    {
      "id": "be0b3c24-58bc-4a3f-9270-8a534eb2e651",
      "payment_backend_id": "93efc3e5-9faf-447a-b848-e9d181264397",
      "provider_id": "77d872ea-5ded-4a3d-98fe-90c5e44d0bcc",
      "name": "",
      "type": "salary"
    }
  ]
}

# PaymentMethod

Bei einer Rechnungsadresse ist eine Zahlungsart (PaymentMethod) hinterlegt. Normalerweise ist das ein Objekt welches eine Referenz zur verwendeten Kreditkarte oder zum verwendeten SEPA Lastschrift Konto beinhaltet. Für eigene Zahlungsbackends zeigt das PaymentMethod Objekt auf ihr Zahlungsbackend.

Ein Zahlungsbackend ist eindeutig durch den backend_type und source_type definiert.

Endpunkte:

GET https://api.parken.arivo.app/payment/payment_method/
GET https://api.parken.arivo.app/payment/payment_method/:id/
DELETE https://api.parken.arivo.app/payment/payment_method/:id/

{
    "backend_public_data": {},
    "backend_type": "primeo",
    "created": "2020-11-09T11:20:29.593558+01:00",
    "customer_address_id": "fdac408f-3c0f-477a-b3ec-47e4f2f11ab8",
    "customer_id": "9dd3bfa3-574c-404d-9afa-c9707e74a312",
    "id": "3bab7c91-838c-4436-bb3a-b1c4f66383bb",
    "source_type": "salary"
}

# Payment

Ein Payment Objekt stellt eine Zahlung dar. Es beinhaltet den Betrag (amount und amount_currency), von welchem Kunden es ist (customer_id), und für welche Rechnungsadresse vom Kunden (customer_address_id).

Das state Feld vom Payment Objekt wird durch Anlegen von PaymentLog Objekten automatisch aktualisiert.

Endpunkte:

GET https://api.parken.arivo.app/payment/payment/
GET https://api.parken.arivo.app/payment/payment/:id/

{
    "id": "e82fe4b9-1d9a-489f-bf8f-0f0836186308",
    "amount": "10.00",
    "amount_currency": "CHF",
    "backend_type": "primeo",
    "created": "2020-11-09T11:34:34.958078+01:00",
    "customer_address_id": "c31ca2a6-9e4b-4d7e-86ab-8d9f1541b834",
    "customer_id": "c44fbc0b-b186-44d1-afb1-a5a9ef4528f3",
    "payment_method_id": "e78c3736-98aa-4f24-a6ca-7c372a57586e",
    "source_id": "c31ca2a6-9e4b-4d7e-86ab-8d9f1541b834",
    "source_model": "Backoffice.CustomerAddress",
    "source_type": "salary",
    "state": "success"
}

# PaymentLog

Das PaymentLog Objekt beschreibt eine Änderung vom Zustand einer Zahlung. Zusätzlich kann im comment Feld ein Text übergeben werden, der in der Backoffice Anwendung angezeigt wird.

Das reason Feld gibt den Grund für die Änderung vom Zahlungszustand an. Die Bedeutung der einzelnen Felder ist unter Zahlungsablauf beschrieben.

Endpunkte:

GET https://api.parken.arivo.app/payment/payment_log/
POST https://api.parken.arivo.app/payment/payment_log/
GET https://api.parken.arivo.app/payment/payment_log/:id/

{
      "id": "08774aef-fee4-439b-9ada-89c78adf3a02",
      "payment_id": "e82fe4b9-1d9a-489f-bf8f-0f0836186308",
      "created": "2020-11-09T11:35:25.305214+01:00",
      "backend_info": {},
      "reason": "processing",
      "comment": "Ins SAP eingetragen. Nr 123456"
}

# dispute

Ist der reason auf dispute gesetzt, muss die Höhe der Dispute Fees im Feld backend_info übergeben werden. Die Dispute Fees können auch Null (0.00) sein.

{
  "backend_info": {
    "dispute_fee_amount": "1.00",
    "dispute_fee_currency": "EUR"
  }
}

# success

Ist der reason auf success gesetzt, muss die Höhe der Kosten angegeben werden, welche der ARIVO Platform für das Abwickeln der Zahlung verrechnet werden. Diese Kosten können auch Null (0.00) sein. Es muss nicht sein dass dieser Betrag exact glech dem Parkplatzbetreiber verrechnet wird.

{
  "backend_info": {
    "backend_fee_amount": "1.00",
    "backend_fee_currency": "EUR"
  }
}

# refund

Ist der reason auf refund gesetzt, muss die Höhe der Rückerstattung angegeben werden. Die Rückerstattung muss die selbe Währung angeben, wie die ursprüngliche Zahlung. Zurzeit sind Teil-Rückerstattungen nicht möglich, es muss immder der Volle Betrag rückerstattet werden.

{
  "backend_info": {
    "refunded_amount": "1.00",
    "refunded_currency": "EUR"
  }
}

# SDK

Ein Python SDK und eine Beispielanwendung (opens new window) sind verfügbar.

← Rendering Templates Parksystem Integration →