fetchPayments

Navigation:  WebService Calls > Options for Growth >

fetchPayments

 Previous pageReturn to chapter overviewNext page

Texte ein-/ausblenden

Beschreibung

Abfrage von Zahlungseingängen.

Hinweis zur Implementierung

Die Abfrage der Zahlungen wird in der Regel über Filter nach dem Änderungsdatum der Zahlung realisiert. So werden alle Zahlungen, die seit der letzten Abholung geändert wurden, abgefragt. Dazu muss auf seiten der Warenwirtschaft nur das Datum des letzten Abholzeitpunkts gespeichert werden.

Damit keine Zahlungen doppelt angelegt werden, empfiehlt es sich die payment_id als eindeutiges Kennzeichen (unique key) zu speichern. Bei Daten die spezifisch für einen Bezahldienst ermittelt werden, kann auch dessen ID als eindeutiges Kennzeichen genutzt werden. Bei PayPal wäre dies die Transaction_id. Ist dieses Kennzeichen noch nicht in der Warenwirtschaft bekannt, dann muss der Datensatz neu angelegt werden. Im anderen Fall wird der Zahlungsdatensatz aktualisiert.

Beispiel Request

Code

<request method="fetchPayments" version="1.1.0">

   <filter>

      <mandator_id filter_method="=" filter_value="1" />

      <payment_date from_date="2000-01-01T00:00:00.000+01:00" to_date="2012-09-28T00:00:00.000+02:00" />

      <order_id filter_method="=" filter_value="123456" />

      <!-- 

      <order_number filter_method="=" filter_value="123456" />      

      <external_order_number_1 filter_method="=" filter_value="123456" />

      <external_order_number_2 filter_method="=" filter_value="123456" />

      <depositor filter_method="=" filter_value="Amazon.de" />

      <payment_system_id filter_method="=" filter_value="25" />

      <has_order is="true" />

       -->

   </filter>

   <payments_per_page>10</payments_per_page>

   <page>1</page>

</request>

Feldliste Request

Name

Beschreibung

Anz.

Typ

sonstiges

request

Root-Element der Anfrage

1

Element

method

Attribut von request. Name der Webservice-Methode.

1

string

Fester Wert:

„fetchPayments“

version

Attribut von request. Legt die Version der Anfrage fest.

1

integer

Feste Werte:

„1.0.0“ | „1.1.0"

filter

Legt Parameter fest nach denen die Ergebnismenge eingeschränkt wird. Mehrere Filter werden als ODER-Verknüpfung, Elemente innerhalb des Filters als UND-Verknüpfung behandelt.

1..N

Element

mandator_id

Schränkt die Ergebnismenge der Abfrage auf einen bestimmten Mandanten ein.

1

Element

filter_method

Attribut von mandator_id. Legt das Verhalten des Mandanten-Filters fest.

1

string

Fester Wert:

„=“

filter_value

Attribut von mandator_id. Legt den Filterwert des Mandanten-Filters fest.

1

integer

payment_ids

Schränkt die Ergebnismenge der Abfrage auf bestimmte Zahlungs-IDs ein.

0..1

Element

ab Version 1.1.0

filter_method

Attribut von payment_ids. Legt das Verhalten des Zahlungs-ID-Filters fest.

1

string

Fester Wert: „IN“

filter_values

Element von payment_ids. Fasst ein oder mehrere Zahlungs-IDs zusammen.

1

Element

filter_value

Element von filter_values. Legt die Zahlungs-ID fest nach der gefiltert werden soll. Es kann auch gleichzeitig nach mehreren IDs gefiltert werden. Dafür müssen mehrere filter_value Elemente angegeben werden.

1..N

integer

last_changed

Schränkt die Ergebnismenge der Abfrage nach dem letzten Änderungsdatum ein.

0..1

Element

from_date

Attribut von last_changed. Selektiert alle Daten die ab einschließlich dem angegebenem Datum geändert wurden.

0..1

dateTime

 

 

to_date

Attribut von last_changed. Selektiert alle Daten die bis einschließlich dem angegebenen Datum geändert wurden.

0..1

dateTime


created_at

Schränkt die Ergebnismenge der Abfrage nach dem Erstellungsdatum ein.

0..1

Element

from_date

Attribut von created_at. Selektiert alle Daten die ab einschließlich dem angegebenem Datum erstellt wurden.

0..1

dateTime


to_date

Attribut von created_at. Selektiert alle Daten die bis einschließlich dem angegebenen Datum erstellt wurden.

0..1

dateTime


payment_date

Schränkt die Ergebnismenge der Abfrage nach dem Zahlungsdatum ein.

0..1

Element

from_date

Attribut von payment_date. Selektiert alle Daten die ab einschließlich dem angegebenem Datum bezahlt wurden.

0..1

dateTime


to_date

Attribut von payment_date. Selektiert alle Daten die bis einschließlich dem angegebenen Datum bezahlt wurden.

0..1

dateTime


order_id

Schränkt die Ergebnismenge der zurückgegebenen Zahlungseingänge nach einer Auftrags-ID ein.

0..1

Element

filter_method

Attribut von order_id. Legt das Verhalten des Filters fest.

1

string

Fester Wert:

„=“

filter_value

Attribut von order_id. Legt den Filterwert des Filters fest.

1

integer

order_number_prefix

Schränkt die Ergebnismenge der zurückgegebenen Zahlungseingänge nach dem Präfix der Auftragsnummer ein.

0..1

Element

Ab Version 1.1.0

filter_method

Attribut von order_number_prefix. Legt das Verhalten des Filters fest.

1

string

Fester Wert: „=“

filter_value

Attribut von order_number_prefix. Legt den Filterwert des Filters fest.

1

string

Länge: 1-4 Zeichen

order_number

Schränkt die Ergebnismenge der zurückgegebenen Zahlungseingänge nach einer Auftragsnummer ein.

0..1

Element

filter_method

Attribut von order_number. Legt das Verhalten des Filters fest.

1

string

Fester Wert: „=“

filter_value

Attribut von order_number. Legt den Filterwert des Filters fest.

1

integer

external_order_number_1

Schränkt die Ergebnismenge der Zahlungseingänge nach der externen Auftragsnummer 1 ein.

0..1

Element

filter_method

Attribut von external_order_number_1. Legt das Verhalten des Filters fest.

1

string

Fester Wert:

„=“

filter_value

Attribut von external_order_number_1. Legt den Filterwert des Filters fest.

1

integer

external_order_number_2

Schränkt die Ergebnismenge der Zahlungseingänge nach der externen Auftragsnummer 2 ein.

0..1

Element

filter_method

Attribut von external_order_number_2. Legt das Verhalten des Filters fest.

1

string

Fester Wert:

„=“

filter_value

Attribut von external_order_number_2. Legt den Filterwert des Filters fest.

1

integer

payment_system_id

Schränkt die Ergebnismenge der Zahlungseingänge nach dem Zahlungssystem ein.

0..1

Element

Feste Werte

filter_method

Attribut von payment_system_id. Legt das Verhalten des Filters fest.

1

string

Fester Wert:

„=“

filter_value

Attribut von payment_system_id. Legt den Filterwert des Filters fest.

1

integer

depositor

Schränkt die Ergebnismenge der Zahlungseingänge nach dem Kontoinhaber ein. Hinweis: Handelt es sich um eine Amazon-Zahlung so ist der Marktplatz hinterlegt. Z. B.: „Amazon.de“

0..1

Element

filter_method

Attribut von depositor. Legt das Verhalten des Filters fest.

1

string

Fester Wert:

„=“

filter_value

Attribut von depositor. Legt den Filterwert des Filters fest.

1

string

import_identifier

Schränkt die Ergebnismenge der Zahlungseingänge nach dem Zahlungsimport ein.

0..1

Element

filter_method

Attribut von import_identifier. Legt das Verhalten des Filters fest.

1

string

Fester Wert:

„=“

filter_value

Attribut von import_identifier. Legt den Filterwert des Filters fest.

1

string

has_order

Schränkt die Ergebnismenge der Zahlungseingänge nach zugewiesenen Aufträgen ein.

0..1

Element

is

Attribut von has_order. Legt den Filterwert des Filters fest.

1

boolean

payments_per_page

Anzahl der Zahlungseingänge, die pro Seite zurückgegeben werden sollen.

0..1

integer

Muss zusammen mit „page“ genutzt werden.

page

Die Seitennummer, von der die Zahlungseingänge zurückgegeben werden sollen. Wird „payments_per_page“ und „page“ weggelassen, so werden alle Zahlungseingänge zurückgegeben.

0..1

integer

Muss zusammen mit „payments_per_

page“ genutzt werden.

Beispiel Response

Code

<response method="fetchPayments" version="1.0.0">

   <report return_code="0" />

   <payment>

      <payment_id>1484160</payment_id>

      <mandator_id>1</mandator_id>

      <external_payment_id>4UV16854C0732721F</external_payment_id>

      <order_data>

         <order_id>217363</order_id>

         <order_number_prefix>BAY</order_number_prefix>

         <order_number>2010005504</order_number>

         <external_order_number_1>___000010</external_order_number_1>

         <external_order_number_2></external_order_number_2>

         <marketplace_order_id>123456789-123456789</marketplace_order_id>

      </order_data>

      <amount>288.9000</amount>

      <pay_date>2015-05-09T11:40:19.000+02:00</pay_date>

      <note>Art.-Nr.:110098719645</note>

      <cancel_date>2015-06-02T12:02:55.000+02:00</cancel_date>

      <depositor>Test User</depositor>

      <bank_account_number>123456789</bank_account_number>

      <bank_name>Sparkasse Oberpfalz Nord</bank_name>

      <bank_code>75350000</bank_code>

      <iban_code>DE21700519950000007229</iban_code>

      <swift_code>GENODEF1WEO</swift_code>

      <created_by>Server</created_by>

      <payment_system_id>20</payment_system_id>

      <fee currency="EUR">5.8400</fee>

      <reference_number>123456789</reference_number>

      <last_changed>2015-09-17T15:53:21.140+02:00</last_changed>

      <last_changed_by>Server</last_changed_by>

      <anonymized_by>AnonymizationJob</anonymized_by>

      <anonymized_at>2021-05-06T15:44:42.000+02:00</anonymized_at>

   </payment>

   <total_number_of_pages>10</total_number_of_pages>

   <total_number_of_entries>123</total_number_of_entries>

</response>

Feldliste Response

Name

Beschreibung        

Anz.

Typ

sonstiges

response

Root-Element der Antwort

1

Element

method

Attribut von response. Name der Webservice-Methode.

1

string

Fester Wert:

„fetchPayments“

version

Attribut von response. Legt die Version der Anfrage fest.

1

integer

Feste Werte: „1.0.0“ | "1.1.0"

report

Information über die ausgeführte Operation.

1

Element

return_code

Attribut von report. Gibt an ob in der durchgeführten Operation Fehler aufgetreten sind.

1

integer

0 = OK.

< 0 = Fehler

error_

description

Fehlerbeschreibung falls bei der Durchführung der Operation Fehler aufgetreten sind.

0..1

string

payment

Wrapper-Element, das die Daten eines Zahlungseinganges zusammenfasst

0..N

Element

payment_id

ID des Zahlungseingangs

1

integer

mandator_id

Mandant-ID

1

integer

external_payment_id

Externe Zahlungs ID

0..1

string

Länge:

0-50 Zeichen

order_data

Wrapper-Element, das Daten des zu der Zahlung gehörenden Auftrags zusammenfasst.

0..1

Element

order_id

Element von order. ID des Auftrags

1

integer

order_number_prefix

Element von order. Prefix der Auftragsnummer

0..1

string

Länge:

0-4 Zeichen

order_number

Element von order. Auftragsnummer

1

integer

external_order_number_1

Element von order. Externe Auftragsnummer 1

0..1

string

Länge:

0-100 Zeichen

external_order_number_2

Element von order. Externe Auftragsnummer 2

0..1

string

Länge:

0-100 Zeichen

marketplace_order_id

Marktplatzauftragsnummer

0..1

string

amount

Betrag des Zahlungseingangs

1

decimal

pay_date

Datum des Zahlungseingangs

1

dateTime

note

Bemerkung, Verwendungszweck

0..1

string

Länge:

0-255 Zeichen

cancel_date

Datum der Stornierung des Zahlungseingangs

0..1

dateTime

depositor

Kontoinhaber

0..1

string

Länge:

0-150 Zeichen

bank_account_number

Kontonummer

0..1

string

Länge:

0-20 Zeichen

bank_code

Bankleitzahl

0..1

string

Länge:

0-20 Zeichen

bank_name

Bank

0..1

string

Länge:

0-150 Zeichen

iban_code

IBAN des Kontoinhabers

0..1

string

Länge: 0-100 Zeichen

swift_code

SWIFT-Code (BIC) der Bank

0..1

string

Länge: 0-20 Zeichen

created_by

Benutzer der Zahlungseingang angelegt hat

0..1

string

payment_system_id

Gibt an, um was für einen Zahlungstyp es sich handelt

0..1

integer

Feste Werte

fee

Gibt die Gebühr der Transaktion an

0..1

decimal

currency

Attribut von fee. Gibt die Währung an, mit der die Gebühr verrechnet wurde.

1

string

Länge:

0-3 Zeichen

ISO 4217

account_id

Zahlungsaccount-ID.

0..1

integer

Ab Version 1.1.0

reference_number

Referenz-Nummer (End-to-End-ID), die bei der Transaktion angegeben wurde.

0..1

string

Länge: 0-50 Zeichen

last_changed

Datum der letzten Änderung am Zahlungseingang.

1

datetime

Ab Version 1.1.0

last_changed_by

Bezeichnung des letzten Bearbeiters des Zahlungseinganges.

1

string

Ab Version 1.1.0

anonymized_by

Bezeichnung des Anonymisierenden

0..1

string

anonymized_at

Zeitpunkt der letzten Daten-Anonymisierung

0..1

dateTime

specific_payment_data

Wrapper-Element, das plattform-spezifische Daten für die Zahlung zusammenfasst.

0..1

Element

total_number_of_pages

Gibt an, wie viele Seiten es insgesamt gibt.

1

integer

total_number_of_entries

Gibt an, wie viele Zahlungseingänge es insgesamt sind.

1

integer

Wertetabelle(n)

Aufgeführte Werte gelten für das Feld payment_system_id. Hinter den Bezahlsystemen 50 (Otto) und 55 (OTTO Market) verbergen sich Dummy-Zahlungseingänge. Diese sind nötig, da manche externe Systeme zwingend einen Zahlungseingang brauchen um Aufträge weiterverarbeiten zu können.

Wert

Beschreibung

5

Manuelle Zahlung

10

CSV-Import

15

MT940/MT942-Import

20

PayPal-Import

25

Amazon-Zahlung

30

HBCI-Import

35

BillSAFE (deprecated)

40

Klarna

45

eBay

50

Otto

55

OTTO Market

Verwandte Themen

Link

Bemerkung

Spezifische Zahlungseingangsdaten für PayPal

Handelt es sich um einen Zahlungseingang via PayPal werden zusätzlich spezifische Daten in den Response integriert.

 

Änderungsübersicht

Version

Änderungsbeschreibung

3.2.5.155

Redaktionelle Überarbeitung

3.3.2.90

Erweiterung der Response-Daten um Marktplatzauftragsnummer

3.4.9.1

Erweiterung der Response-Daten um IBAN, SWIFT-Code und Referenz-Nummer

3.4.9.1

Erweiterung des Requests um has_order Filter.

3.4.42.1

Erweiterung des Calls um eine Pagination-Funktionalität.

3.5.37

Erweiterung des Resonse um last_changed und last_changed_by.

3.6.3

Erweiterung des Requests um order_number_prefix.

4.9.49

Tabelle mit Bezahlsystemen um neuen Wert (Otto - ID: 50) erweitert.

4.10.51

Tabelle mit Bezahlsystemen um neuen Wert (OTTO Market - ID: 55) erweitert.

4.11.18

Erweiterung des Response um anonymized_at und anonymized_by.