Paypal
1.2 Diagramme zum Prozessablauf
1.2.1 PayPal Prozessablauf aus Händlersicht
1.2.2 PayPal Shortcut-Prozessablauf aus Händlersicht
2.1 PayPal-Geschäftskonto anlegen und konfigurieren
2.3 Einstellungen für den Zahlungsempfang vornehmen
3 1cs Online Bezahlsystem Schnittstelle
3.3 Aufruf der Schnittstelle für Methode “shortcut”
3.4 Aufruf der Schnittstelle für separate Autorisierung
3.5 Aufruf der Schnittstelle für eine Buchung
3.6 Aufruf der Schnittstelle für eine Gutschrift mit Referenz
3.7 Aufruf der Schnittstelle für nicht referenzierte Gutschriften
3.8 Aufruf der Schnittstelle für Stornierungen
3.9 Aufruf der Schnittstelle für Abonnements
3.9.5 Löschen der BillingAgreementID
3.9.6 Zahlungsabwicklung für Abonnements
1 Über PayPal
1.1 Allgemeines zu PayPal
Logo
| Info | Typ |
| Die First Cash Solution wickelt PayPal-Zahlungen ab, die Ihnen weltweiten Verkäuferschutz sowie ein Potenzial von 179 Millionen internationalen Kunden in über 200 Märkten bieten. PayPal gehört zu den beliebtesten Online-Zahlungsmitteln und kann im E- und M-Commerce eingesetzt werden. | Zahlungen per eWallet |
PayPal ist eines der weltweit führenden eWallets für E- und M-Commerce. Etwa 179 Millionen aktive Mitglieder in über 200 Ländern begleichen mittels PayPal ihre Online-Bestellungen. In Deutschland können Kunden per Lastschrift, giropay oder Kreditkarte (American Express, Diners Club, Discover, MasterCard, Visa) bezahlen. PayPal PLUS bietet zudem neben den genannten Zahlarten den Kauf auf Rechnung sowie Ratenkauf an. Mitglieder können sich während eines Checkouts mit ihrer E-Mail-Adresse und einem Passwort an ihrem PayPal-Konto anmelden und die gewünschte Zahlungsart (Lastschrift, PayPal-Guthaben, Kreditkarte und ggf. Rechnungs- oder Ratenkauf) auswählen. Der zu zahlende Betrag wird Ihnen unmittelbar im eigenen PayPal-Konto gutgeschrieben. Die ansonsten üblichen Banklaufzeiten von Überweisungen oder die Verzögerung bei der Ausschüttung von Collecting-Services entfallen. Dies ermöglicht eine Echtzeit-Zahlungsabwicklung im Internet.
1.1.1 PayPal Express Checkout
Für verkürzte Bestellungen bietet das1cs Online Bezahlsystem den PayPal Express Checkout an: Ihr Kunde muss keine Adressdaten eingeben, sondern klickt schon im Warenkorb auf Checkout mit PayPal, meldet sich dort an und wählt seine Rechnungs- und Lieferadresse bei PayPal aus. Das 1cs Online Bezahlsystem gibt dann die Lieferadresse als Ergebnisparameter an Ihren Shop zurück.
1.1.2 Käufer- und Verkäuferschutz inbegriffen
PayPal bietet Käufern wie auch Händlern einen umfangreichen Käufer- bzw. Verkäuferschutz. So erhalten Käufer die Möglichkeit, bei Nichterfüllung eines Kaufvertrages das Geld über PayPal zurückzuverlangen. Mit Adressverifikation und PayPal-Verkäuferschutz trägt PayPal für die Händler das Zahlungsausfallrisiko bei Lastschriftzahlungen, innerdeutschen Kreditkartenzahlungen und ungerechtfertigten Käuferbeschwerden. Der Verkäuferschutz ist stets an PayPal-Regularien und Bedingungen geknüpft. Das PayPal-Risikomanagement mit Käuferschutz und Adressverifikation steht Ihnen über das 1cs Online Bezahlsystem zur Verfügung.
1.1.3 Weltweit online bezahlen
Besonders nützlich ist PayPal für die Kundenakquise im Ausland. Das 1cs Online Bezahlsystem unterstützt alle von PayPal angebotenen Währungen und Märkte. In vielen Ländern bietet PayPal den Kunden landestypische Zahlungsmethoden an. Kunden im Ausland können oft die dort typischen Zahlungsmethoden wie Prepaid-Karten in Italien oder Debit-Karten in Großbritannien nutzen. Durch die Einbindung von PayPal in Ihren Shop stehen Ihren Kunden deshalb gleich mehrere Zahlungsmethoden zur Verfügung.
Weitere Informationen finden Sie auch auf der Webseite von PayPal (http://www.paypal.com).
1.2 Diagramme zum Prozessablauf
1.2.1 PayPal Prozessablauf aus Händlersicht
1.2.2 PayPal Shortcut-Prozessablauf aus Händlersicht
1.3 Wichtige Hinweise
Bitte beachten Sie, dass entgegen der Darstellung in unserer Währungstabelle die Währungen HUF (Ungarn – Forint) und TWD (Republik China – Taiwan-Dollar) ohne Nachkommastellen einzureichen sind.
Beispiel: Um 100,00 HUF einzureichen übergeben Sie Amount=100
Diese Ausnahme gilt ausschließlich für die Zahlungsart PayPal.
Hinweis: Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den 1cs Support, um diese Funktion für Sie zu aktivieren.
2 Konfiguration für PayPal
Damit Sie als Online-Anbieter PayPal-Transaktionen über das 1cs Online Bezahlsystem abwickeln können, benötigen Sie ein Geschäftskonto bei PayPal. Weiterhin müssen Sie die PayPal-Schnittstelle für die Nutzung über das 1cs Online Bezahlsystem freigeben und die nötigen Einstellungen für den Empfang von Zahlungen vornehmen.
2.1 PayPal-Geschäftskonto anlegen und konfigurieren
1. Bitte rufen Sie die URL http://www.paypal.com
2. Anschließend klicken Sie links in der Servicebox auf die Schaltfläche „Neu anmelden“.
3. Sie werden von PayPal auf die nächste Seite weitergeleitet.
4.Dort wählen Sie „Geschäftskonto“ aus und klicken auf „weiter“.
5. Nun werden Sie auf die Seite „Geschäftskonto eröffnen“ weitergeleitet. Bitte geben Sie dort Ihre Emailadresse ein, welche für den PayPal-Account verwendet werden soll und klicken dann auf die Schaltfläche „Weiter“.
6. Bitte geben Sie hier Ihre Daten ein, bestätigen per Option die PayPal-Nutzungsbedingungen und klicken dann auf die Schaltfläche „Weiter“.
7. Hinterlegen Sie auf den nächsten Seiten die benötigten Angaben zu Ihrem Unternehmen.
8. Sie erhalten jetzt eine E-Mail, welche Sie bestätigen müssen.
9. Ergänzen Sie bitte die weiteren notwendigen Angaben zu Ihrem Unternehmen.
2.2 PayPal-API freigeben
Damit über das 1cs Online Bezahlsystem PayPal-Transaktionen abgewickelt werden können, muss die API-Genehmigung für die First Cash Solution erteilt werden. Dazu führen Sie die nachfolgend erklärten sechs Schritte aus.
1. Wählen Sie im Menü „Mein Profil“ die „Kontoeinstellungen“ aus
2. Bitte wählen Sie nun links in der Servicebox „Verkäufer/Händler“ …
… und anschließend mit der Schaltfläche „Aktualisieren“ den Punkt „API-Zugriff“ aus.
3. Klicken Sie dann bitte auf den Link „API-Genehmigung erteilen“
4. Bitte tragen Sie im Feld „Benutzername für Genehmigungen für Drittanbieter“ den nachfolgenden Wert ein und klicken dann auf die Schaltfläche „Nachschlagen“: frank.arnoldt_api1.computop.de
5. Bitte setzen Sie bei den folgenden Punkten das Häkchen, alle anderen Optionen lassen Sie deaktiviert. Anschließend bestätigen Sie die Eingaben per Schaltfläche „Hinzufügen“.
– Verwenden der Express-Kaufabwicklung für Ihre Zahlungsvorgänge
– Veranlassen einer Rückzahlung für bestimmte Transaktionen
– Autorisieren und Einziehen Ihrer PayPal-Transaktionen
– Abrufen von Informationen zu einer einzelnen Transaktion
– Durchsuchen Ihrer Transaktionen nach Artikeln, die spezifische Kriterien entsprechen, und Anzeigen der Ergebnisse
6. Sie erhalten die Bestätigung darüber, dass der Drittanbieter „frank.arnoldt_api1.computop.de“ hinzugefügt wurde.
2.3 PayPal-API Genehmigung für Sandbox
Für die PayPal Sandbox können die API-Genehmigungen folgendermaßen erteilt werden.
1. Auf https://developer.paypal.com finden Sie unter “Accounts” –> (Accountname) –> “Manage accounts” –> “View/ edit account” die Zugangsdaten des jeweiligen Händlerkontos.
2. Mit diesen Zugangsdaten melden Sie sich unter https://sandbox.paypal.com an.
3. Klicken Sie oben rechts auf den Namen und gehen zu den “Kontoeinstellungen”.
4. Klicken Sie auf “API-Zugriff” –> “API-Genehmigung erteilen” –> Tragen Sie “test_paypal_api_api1.computop.com” ein.
5. Setzen Sie die Häkchen bei folgenden Berechtigungen:
– Verwenden von PayPal Express für Ihre Zahlungsvorgänge
– Veranlassen einer Rückzahlung für eine bestimmte Transaktion
– Autorisieren und Einziehen Ihrer PayPal-Transaktionen
– Abrufen von Informationen zu einer einzelnen Transaktion
– Ihre Transaktionen nach bestimmte Kriterien durchsuchen und die Suchergebnisse anzeigen
2.4 Einstellungen für den Zahlungsempfang vornehmen
1. Im Menü wählen Sie „Mein Profil“ aus und klicken auf „Kontoeinstellungen“.
2. Bitte wählen Sie hier unter „Verkäufer/Händler“ den Punkt „Zahlungen sperren“ über den Link „Aktualisieren“ aus.
3. Bitte stellen Sie hier folgende Punkte ein:
– Zahlungseingänge in einer nicht unterstützten Währung blockieren
– Doppelte Zahlungen vermeiden
– Folgende Zahlungen ablehnen: Hiermit schließen Sie Zahlungsquellen aus, die keine Sofortzahlung unterstützen. Auf eBay-Zahlungen hat diese Einstellung keine Auswirkung.
– Zahlungen von minderjährigen Inhabern von Schülerkonten sperren
– Texteingabefeld “Anweisungen für Verkäufer hinzufügen” anzeigen:
Bitte bestätigen Sie Ihre Eingaben mit einem Klick auf die Schaltfläche „Speichern“.
3 1cs Online Bezahlsystem-Schnittstelle
3.1 Definitionen
3.1.1 Datenformate
| Format | Beschreibung |
| a | alphabetisch |
| as | alphabetisch mit Sonderzeichen |
| n | numerisch |
| an | alphanumerisch |
| ans | alphanumerisch mit Sonderzeichen |
| ns | numerisch mit Sonderzeichen |
| bool | Bool’scher Ausdruck (true oder false) |
| 3 | feste Länge mit 3 Stellen/Zeichen |
| ..3 | variable Länge mit maximal 3 Stellen/Zeichen |
| enum | Aufzählung erlaubter Werte |
| dttm | ISODateTime (JJJJ-MM-TTThh:mm:ss) |
3.1.2 Abkürzungen
| Abkürzung | Beschreibung | Kommentar |
| CND | Bedingung (condition) | |
| M | Pflicht (mandatory) | Wenn ein Parameter Pflicht ist, dann muss er vorhanden sein |
| O | optional | Wenn ein Parameter optional ist, dann kann er vorhanden sein, ist aber nicht erforderlich |
| C | bedingt (conditional) | Wenn ein Parameter bedingt ist, dann gibt es eine Bedingungsregel, die angibt, ob er Pflicht oder optional ist |
Hinweis: Bitte beachten Sie, dass die Bezeichnungen der Parameter in Groß- oder Kleinbuchstaben zurückgegeben werden können.
3.2 Aufruf der Schnittstelle
Um eine PayPal-Zahlung im 1cs Online Bezahlsystem-Formular abzuwickeln, nutzen Sie folgende URL und Parameter:
Mit dieser URL unterstützt das 1cs Online Bezahlsystem zwei verschiedene PayPal-Methoden: Einerseits können Sie PayPal ganz normal als zusätzliche Zahlungsmethode zum Abschluss einer Bestellung anbieten. Zum anderen können Sie PayPal Express Checkout nutzen, damit der Kunde vom Warenkorb direkt zu PayPal gelangt und dort seine Liefer- und Rechnungsadresse auswählt. Dem Kunden erspart das die erneute Eingabe von Adressdaten und als Händler genießen Sie den PayPal Verkäuferschutz.
Das 1cs Online Bezahlsystem unterstützt auch für PayPal Express Checkout das Auseinanderfallen von Autorisierung und Buchung. Sie können über das 1cs Online Bezahlsystem über Parameter steuern, ob der Betrag auf dem PayPal-Account des Kunden geblockt oder gleich gebucht werden soll.
Hinweis: Bitte beachten Sie, dass eine PayPal-Anbindung im Shop per i-Frame aufgrund von PayPal-Regularien nicht möglich ist. Express Checkout funktioniert mit einer Weiterleitung des Kunden direkt zu PayPal.
Hinweis: Damit Sie vom PayPal Verkäuferschutz profitieren, muss eine der folgenden Bedingungen erfüllt sein. Entweder der Kunde nutzt PayPal Express Checkout und wählt eine bei PayPal selbst hinterlegte Lieferadresse aus, die das 1cs Online Bezahlsystem an Ihren Shop übergibt. Oder Ihr Shop übergibt die bereits bekannte Lieferadresse an PayPal. Der Verkäuferschutz gilt nur, wenn die Ware an diese angegebene Adresse geliefert wurde. Zwischen der Autorisierung des Betrags im PayPal-Konto des Kunden und der Buchung dürfen nicht mehr als 3 Tage liegen, wenn Sie vom Verkäuferschutz profitieren möchten. Das 1cs Online Bezahlsystem unterstützt deshalb mehrere Alternativen zur Abwicklung von PayPal-Zahlungen: für eine Beratung zur Implementierung von PayPal stehen wir Ihnen gerne zur Verfügung.
Hinweis: Aus Sicherheitsgründen lehnt das 1cs Online Bezahlsystem alle Zahlungsanfragen mit Formatfehlern ab. Bitte übergeben Sie deshalb bei jedem Parameter den korrekten Datentyp.
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss. |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den 1cs Support, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a3 | M | Währungskürzel, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/ |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| RefNr | ans..30 | O | Eindeutige Referenznummer des Händlers Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| Capture | a..6 | O | Auto oder Manual: bestimmt, ob der angefragte Betrag sofort oder erst später abgebucht wird. Wichtiger Hinweis: Bitte kontaktieren Sie den First Cash Solution Support für Manual, um die unterschiedlichen Einsatzmöglichkeiten abzuklären. |
| TxType | ans..5 | C | Pflicht bei Capture=Manual: Transaktionstyp mit den möglichen Werten Order oder Auth sowie BAID (BillingAgreementID) |
| PayPalMethod | enum | O | Wert “shortcut” wählt den geänderten Transaktionsablauf, bei dem der Kunde für die Zahlungsbestätigung in den Shop zurückgeleitet wird und z.B. bei einem Ratenkauf die Ratenkaufdaten angezeigt werden, die er dann bestätigen muss. Zum Abschließen der Bestellung muss anschließend die Schnittstelle paypalcomplete.aspx aufgerufen werden. |
| RTF | ans1 | O | Für wiederkehrende Zahlungen (Abos): I = Initialzahlung eines neuen Abos, R = Wiederkehrende Zahlung (Recurring) Hier nur RTF=I zulässig, weitere Abo-Zahlungen werden über die separate Schnittstelle paypalAbo.aspx ausgeführt. |
| OrderDesc | ans..127 | M | Beschreibung der gekauften Waren, Einzelpreise etc. – Wenn OrderDesc(n) verwendet wird, muss gelten: Amount=ItemTotal+TaxTotal+ShAmount |
| OrderDesc(n) | ans..2048 | O | Warenkorb des Kunden in der Form: OrderDesc(n)=Name,Amount,Number,Quantity,Description,Tax OrderDesc2 bis max. OrderDesc99 zulässig Zur korrekten Ausführung der Darstellungsfunktion müssen alle OrderDesc(n) Amounts mit dem übergebenen 1cs Online Bezahlsystem-Parameter Amount übereinstimmen. |
| TaxTotal | n..12 | C | Pflicht, wenn bei OrderDesc(n) die Beschreibung +Tax angegeben wird. Gesamtbetrag der Steuern aller einzelnen Artikel in der kleinsten Währungseinheit (z.B. EUR Cent) = Summe(Tax*Number) |
| ItemTotal | n..12 | C | Pflicht, wenn bei OrderDesc(n) die Beschreibung +Tax angegeben wird. Gesamtbetrag der einzelnen Artikel in der kleinsten Währungseinheit (z.B. EUR Cent) = Summe(Amount*Number) |
| ShAmount | n..12 | O | Versandkosten in der kleinsten Währungseinheit (z.B. EUR Cent). Kann nur in Verbindung mit den Parametern ItemTotal und TaxTotal verwendet werden. |
| ReqID | ans..32 | O | Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion mit derselben ReqID erneut eingereicht wird, führt das 1cs Online Bezahlsystem keine Zahlung aus sondern gibt nur den Status der ursprünglichen Transaktion zurück. Bitte beachten Sie, dass das 1cs OBS für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet. |
| URLSuccess | ans..256 | M | Vollständige URL, die das 1cs Online Bezahlsystem aufruft, wenn die Zahlung erfolgreich war. Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen, nutzen Sie stattdessen den Parameter UserData.  Allgemeine Hinweise: Wir empfehlen, den Parameter “response=encrypt” zu verwenden, um eine verschlüsselte Antwort vom 1cs OBS zu erhalten Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess senden. Überprüfen Sie daher unbedingt den “code”-Wert des DATA-Elements. Nur eine Antwort mit “code=00000000” sollte als erfolgreich angesehen werden. |
| URLFailure | ans..256 | M | Vollständige URL, die das 1cs Online Bezahlsystem aufruft, wenn die Zahlung gescheitert ist. Die URL darf nur über Port 443 aufgerufen werden. Diese URL darf keine Parameter enthalten: Um Parameter durchzureichen, nutzen Sie stattdessen den Parameter UserData. Allgemeine Hinweise: Wir empfehlen, den Parameter “response=encrypt” zu verwenden, um eine verschlüsselte Antwort vom 1cs OBS zu erhalten Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess senden. Überprüfen Sie daher unbedingt den “code”-Wert des DATA-Elements. Nur eine Antwort mit “code=00000000” sollte als erfolgreich angesehen werden. |
| Response | a7 | O | Die Status-Rückmeldung, die das 1cs Online Bezahlsystem an URLSuccess und URLFailure sendet, sollte verschlüsselt werden. Dazu übergeben Sie den Parameter Response=encrypt. |
| URLNotify | ans..256 | M | Vollständige URL, die das 1cs Online Bezahlsystem aufruft, um den Shop zu benachrichtigen. Die URL darf nur über Port 443 aufgerufen werden. Sie darf keine Parameter enthalten: Nutzen Sie stattdessen den Parameter UserData. Allgemeine Hinweise: Wir empfehlen, den Parameter “response=encrypt” zu verwenden, um eine verschlüsselte Antwort vom 1cs OBS zu erhalten Betrüger könnten das verschlüsselte DATA-Element kopieren, welches an URLFailure gesendet wurde, und betrügerisch dasselbe DATA an URLSuccess senden. Überprüfen Sie daher unbedingt den “code”-Wert des DATA-Elements. Nur eine Antwort mit “code=00000000” sollte als erfolgreich angesehen werden. |
| UserData | ans..1024 | O | Wenn beim Aufruf angegeben, übergibt das 1cs Online Bezahlsystem die Parameter mit dem Zahlungsergebnis an den Shop |
| expirationTime | ans..19 | O | Zeitstempel für den Endzeitpunkt der Transaktionsverarbeitung, Angabe in UTC. Format: YYYY-MM-ddTHH:mm:ss |
| Account | ans..128 | O | Zur Steuerung mehrerer PayPal-Accounts, Händler-Account: ID oder E-Mail-Adresse, für die die Anfrage an PayPal gesendet werden soll |
| BrandName | ans..127 | O | Auf der Login-Seite angezeigter Markenname |
| HeaderLogo | ans..127 | O | URL für ein Logo-Bild im Login-Bereich. Grafikformate GIF, JPG oder PNG mit maximal 190 x 60 Pixeln. Größere Logos werden von PayPal abgeschnitten. PayPal zeigt das Logo oben im Warenkorb an. |
| LandingPage | ans | O | Steuert, wie die PayPal-Seite angezeigt wird. Mögliche Werte „Login“ oder „Billing“ |
| FundingSource | a..7 | O | Für PayPal Ratenkauf: „FINANCE“ Die PayPal Ratenzahlung wird aktuell für Kunden mit deutscher Rechnungsadresse in EUR ab einem Warenwert von 99 EUR angeboten. Vor der Bestätigung der Bestellung müssen die Ratenkaufdaten dem Kunden angezeigt werden. Dazu muss die PayPalMethod „shortcut“ verwendet werden. Zusätzlich ist die Übergabe der LineItems in den OrderDesc Parametern inkl. taxtotal, itemtotal und shamount erforderlich. |
| Language | an2 | O | AU, DE, FR, IT, GB, ES, US; Standard DE |
| FirstName | ans..30 | OC | (Pflicht für USA und Kanada): Entweder nur der Vorname oder Vor- und Nachname, falls ein Firmenname als Lieferadresse genutzt wird. |
| LastName | ans..30 | OC | (Pflicht für USA und Kanada): Nachname oder Firmenbezeichnung der Lieferadresse |
| AddrStreet | ans..100 | OC | (Pflicht für USA und Kanada): Straßenname der Lieferadresse |
| AddrStreet2 | ans..100 | O | 2. Straßenname in der Lieferadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat vom 1cs Support aktiviert werden. |
| AddrCity | ans..40 | OC | (Pflicht für USA und Kanada): Ortsname der Lieferadresse |
| AddrState | ans..40 | OC | (Pflicht für USA und Kanada): Bundesland (Bundesstaat) der Lieferadresse. Die in AddrCity übergebene Stadt muss im angegebenen Bundesstaat liegen, sonst lehnt PayPal die Zahlung ab. Mögliche Werte entnehmen Sie bitte der PayPal-API-Reference Dokumentation. |
| AddrZip | ans..20 | OC | (Pflicht für USA und Kanada): Postleitzahl der Lieferadresse |
| AddrCountryCode | an2 | O | Ländercode des Lieferlandes |
| Phone | n..20 | O | Telefonnummer |
| NoShipping | n1 | O | Übergabe NoShipping=1 verhindert die Anzeige der bei PayPal hinterlegten Lieferadresse |
| AllowNote | ans..2 | O | Wert „no“ verhindert die Möglichkeit, eine Nachricht an den Händler zu übermitteln. Standardmäßig wird eine eventuelle Mitteilung im Parameter Infotext zurückgegeben. |
| BuyerEMail | ans..127 | OC | Vorbelegung einer E-Mail-Adresse auf der Login-Seite von PayPal |
| NoteToBuyer | ans..165 | O | Hinweistext für den Käufer |
Parameter für PayPal-Zahlungen
Die folgende Tabelle beschreibt die Ergebnis-Parameter, die das 1cs Online Bezahlsystem an Ihre URLSuccess, URLFailure und URLNotify übergibt. Wenn Sie den Parameter Response=encrypt angegeben haben, werden die folgenden Parameter mit Blowfish verschlüsselt an Ihr System übergeben:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung, z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für alle einzelnen Transaktionen (Order, Sale, Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..30 | M | OK, AUTHORIZE_REQUEST oder Timeout (nur bei Capture=Manual) auf der URLSuccess-Seite oder FAILED auf der URLFailure-Seite. AUTHORIZE_REQUEST – Wird nur beim Aufrufparameter “TxType=auth” bzw. “PayPalMethod=shortcut” aktiv versendet. Bei Verwendung von TxType=auth oder ohne TxType wird direkt der abschließende Status gemeldet. Timeout – Alle offenen Zahlungsvorgänge im Status AUTHORIZE_REQUEST werden nach ~ 3h automatisiert geschlossen und als Timeout gemeldet. |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description sondern Code für die Auswertung des Transaktionsstatus! |
| Code | n8 | M | Fehlercode gemäß Excel-Datei 1cs Online Bezahlsystem Antwort Codes |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| RefNr | ans..30 | O | Referenznummer des Händlers Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| UserData | ans..1024 | O | Wenn beim Aufruf angegeben, übergibt das 1cs Online Bezahlsystem die Parameter mit dem Zahlungsergebnis an den Shop |
| CodeExt | n..10 | O | Fehlercode von PayPal, wenn mit dem First Cash Solution Support abgesprochen |
| Name | ans..32 | M | Vorname und Nachname zusammengenommen |
| FirstName | ans..30 | M | Vorname vom Bezahler (PayerInfo, kann vom Account-Namen abweichen) |
| LastName | ans..30 | M | Nachname vom Bezahler (PayerInfo, kann vom Account-Namen abweichen) |
| ans..100 | M | E-Mail-Adresse des Käufers. | |
| AddrStreet | ans..100 | O | Straßenname der Lieferadresse |
| AddrStreet2 | ans..100 | O | 2. Straßenname der Lieferadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat von der First Cash Solution aktiviert werden. |
| AddrCity | ans..40 | O | Ortsname der Lieferadresse |
| AddrState | ans..40 | O | Bundesland (Bundesstaat) der Lieferadresse |
| AddrZIP | ans..20 | O | Postleitzahl der Lieferadresse |
| AddrCountryCode | an2 | O | Ländercode des Lieferlandes |
| Phone | n..20 | O | Telefonnummer |
| BillingAgreementiD | an19 | M | Identifikationsnummer der Rechnungsvereinbarung. Wenn der Käufer die Rechnungsvereinbarung bestätigt, wird sie gültig und bleibt gültig, bis sie vom Käufer widerrufen wird. |
| BillingName | ans..32 | O | Vorname und Nachname zusammengenommen |
| BillingAddrStreet | ans..100 | O | Straßenname der bei PayPal hinterlegten Rechnungsadresse |
| BillingAddrStreet2 | ans..100 | O | 2. Straßenname der bei PayPal hinterlegten Rechnungsadresse, wenn mit der First Cash Solution abgestimmt |
| BillingAddrCity | ans..40 | O | Ortsname der bei PayPal hinterlegten Rechnungsadresse |
| BillingAddrState | ans..40 | O | Bundesland der bei PayPal hinterlegten Rechnungsadresse |
| BillingAddrZIP | ans..20 | O | Postleitzahl der bei PayPal hinterlegten Rechnungsadresse |
| BillingAddrCountryCode | an2 | O | Ländercode des Lieferlandes |
| TransactionID | an..19 | M | Eindeutige Transaktionsnummer bei PayPal für eine Transaktion (PayPal Order) |
| TID | ans..19 | O | Eindeutige Transaktionsnummer von PayPal für eine Autorisierung (PayPal Auth): Nur bei automatischer PayPal-Konfiguration oder sonst wenn TxType=Auth |
| payerStatus | ans..10 | O | Status des Käufers mit den möglichen Werten “verified” oder “unverified” |
| InfoText | ans..255 | M | Nachricht an den Händler |
| PayerID | ans..13 | O | Eindeutige Identifikationsnummer des Kundenkontos bei PayPal. (Die Rückgabe dieses Parameters muss aktiviert werden. Bitte wenden Sie sich an den support@1cs.de, wenn Sie diesen Wert in der Antwort benötigen.) |
| IsFinancing | ans..5 | C | Nur bei Ratenkauf: gibt an, ob es sich um einen Ratenkauf handelt: Wert „TRUE“ oder „FALSE“ |
| FinancingFeeAmount | ans..9 | C | Nur bei Ratenkauf: Ratenkauf-Gebühr. (Weitergabe von PayPal; bisher keine Umrechnung in kleinste Einheit je Währung) |
| FinancingMonthlyPayment | ans..9 | C | Nur bei Ratenkauf: geschätzter Betrag inkl. Gebühren, der durch den Kunden pro Monat gezahlt wird. (Weitergabe von PayPal; bisher keine Umrechnung in kleinste Einheit je Währung) |
| FinancingTerm | an..2 | C | Nur bei Ratenkauf: Anzahl der Raten (6, 12, 18 und 24 möglich) |
| FinancingTotalCost | ans..9 | C | Nur bei Ratenkauf: geschätzter Betrag inkl. Gebühren, der durch den Kunden gesamt gezahlt wird. (Weitergabe von PayPal; bisher keine Umrechnung in kleinste Einheit je Währung) |
| GrossAmount | an..9 | O | Endgültig berechneter Betrag einschließlich Lieferkosten und Steuern von Ihrem Händlerprofil |
| FeeAmount | an..9 | O | Betrag der für die Transaktion berechneten PayPal-Gebühr |
| SettleAmount | an..9 | O | Ihrem PayPal-Konto nach einer Währungsumrechnung gutgeschriebener Betrag |
| TaxAmount | an..9 | O | Für die Transaktion berechnete Steuer |
| ExchangeRate | an..17 | O | Wechselkurs bei einer Währungsumrechnung. Nur relevant, wenn die Rechnung nicht in der primären Währung ausgestellt ist. Wenn der Käufer in einer anderen als der nicht primären Währung bezahlt, erfolgt die Umrechnung im Händlerkonto. |
| mc_fee | an..9 | C | Nur bei separatem Notify von PayPal: Transaktionsgebühr für die Zahlung. mc_gross minus mc_fee entspricht dem Betrag, der dem Empfängerkonto gutgeschrieben wird. Ist äquivalent zur payment_fee bei Zahlung in US-Dollar. Ein negativer Betrag signalisiert ein Storno oder eine Gutschrift. Beide Zahlungs-Status können für den vollständigen oder teilweisen Betrag der ursprünglichen Transaktionsgebühr sein. |
| mc_gross | an..9 | C | Nur bei separatem Notify von PayPal: Gesamtbetrag der Zahlung des Kunden vor Abzug der Transaktionsgebühr. Ist äquivalent zu payment_gross bei Zahlung in US-Dollar. Ein negativer Betrag signalisiert ein Storno oder eine Gutschrift. Beide Zahlungs-Status können für den vollständigen oder teilweisen Betrag der ursprünglichen Transaktionsgebühr sein. |
Ergebnis-Parameter für URLSuccess, URLFailure und URLNotify bei PayPal
Hinweis: Die Adress-Parameter werden immer an den Shop übergeben, sind aber leer, wenn keine Adressdaten ausgetauscht wurden.
3.3 Aufruf der Schnittstelle für Methode “shortcut”
Die PayPal-Methode “shortcut” ermöglicht einen geänderten Transaktionsablauf, bei dem der Kunde für die Zahlungsbestätigung in den Shop zurückgeleitet wird und z.B. bei Ratenkauf die Ratenkaufdaten angezeigt werden, die er dann bestätigen muss. Um im nächsten Schritt diese PayPal-Zahlung abzuschließen, nutzen Sie folgende URL und Parameter:
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den 1cs OBS, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a3 | M | Währungskürzel, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/ |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung. Übergeben Sie hier die PayID aus der Antwort von paypal.aspx im bisherigen Transaktionsablauf erhalten haben. |
| RefNr | ans..30 | O | eindeutige Referenznummer Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| OrderDesc(n) | ans..2048 | O | Warenkorb des Kunden in der Form: OrderDesc(n)=Name,Amount,Number,Quantity,Description,Tax OrderDesc2 bis max. OrderDesc99 zulässig Zur korrekten Ausführung der Darstellungsfunktion müssen alle OrderDesc(n) Amounts mit dem übergebenen Parameter Amount übereinstimmen. – Wenn OrderDesc(n) verwendet wird, muss gelten: Amount=ItemTotal+TaxTotal+ShAmount Hinweis: Bei Änderung von OrderDesc(n) muss auch der Amount angepasst werden. |
| Adressinformationen. Durch Übergabe dieser Werte ist auch eine Adress-Änderung möglich. Hinweis: Wenn FirstName übergeben wird, sollten auch alle anderen Werte übergeben werden. Wenn FirstName nicht übergeben wird, werden andere Adressparameter nicht berücksichtigt. | |||
| FirstName | ans..30 | C | Pflicht, um Adressangaben zu übermitteln: Entweder nur der Vorname oder Vor- und Nachname, falls ein Firmenname als Lieferadresse genutzt wird. |
| LastName | ans..30 | C | Pflicht, wenn FirstName übergeben wird: Nachname oder Firmenbezeichnung der Lieferadresse |
| AddrStreet | ans..100 | C | Pflicht, wenn FirstName übergeben wird: Straßenname der Lieferadresse |
| AddrStreet2 | ans..100 | C | Pflicht, wenn FirstName übergeben wird: 2. Straßenname in der Lieferadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat vom 1cs Support aktiviert werden. |
| AddrCity | ans..40 | C | Pflicht, wenn FirstName übergeben wird: Ortsname der Lieferadresse |
| AddrState | ans..40 | C | Pflicht, wenn FirstName übergeben wird: Bundesland (Bundesstaat) der Lieferadresse. Die in AddrCity übergebene Stadt muss im angegebenen Bundesstaat liegen, sonst lehnt PayPal die Zahlung ab. Mögliche Werte entnehmen Sie bitte der PayPal-API-Reference Dokumentation. |
| AddrZip | ans..20 | C | Pflicht, wenn FirstName übergeben wird: Postleitzahl der Lieferadresse |
| AddrCountryCode | an2 | C | Pflicht, wenn FirstName übergeben wird: Ländercode des Lieferlandes |
| Phone | n..20 | C | Pflicht, wenn FirstName übergeben wird: Telefonnummer |
Parameter für PayPal-Zahlungen mit Methode “shortcut”
Die folgende Tabelle beschreibt die Ergebnis-Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung, z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für alle einzelnen Transaktionen (Order, Sale, Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..30 | M | OK oder FAILED |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description sondern Code für die Auswertung des Transaktionsstatus! |
| Code | n8 | M | Fehlercode gemäß 1cs Online Bezahlsystem Antwort Codes (Fehlercodes) |
| RefNr | ans..30 | O | Eindeutige Referenznummer des Händlers Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| CodeExt | n..10 | O | Fehlercode von PayPal, wenn mit dem First Cash Solution Support abgesprochen |
Ergebnis-Parameter bei PayPal mit Methode “shortcut”
3.4 Aufruf der Schnittstelle für separate Autorisierung
Für eine PayPal Zahlung kann im Prozessablauf die ORDER von der anschließenden Autorisierung und nachfolgenden Schritten getrennt werden. Eine separate Autorisierung ist nur nach erfolgten Order (TxType=Order) möglich.
Für eine separate Autorisierung bei PayPal rufen Sie folgende URL auf:
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| PayID | an32 | M | vom 1cs Online Bezahlsystem vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den 1cs Support, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a3 | M | Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/ |
| TxType | ans..5 | M | Transaktionstyp Auth |
| FirstName | ans..30 | O | Entweder nur der Vorname oder Vor- und Nachname, falls ein Firmenname als Lieferadresse genutzt wird. |
| LastName | ans..30 | O | Nachname oder Firmenbezeichnung der Lieferadresse |
| AddrStreet | ans..100 | O | Straßenname der Lieferadresse |
| AddrStreet2 | ans..100 | O | 2. Straßenname in der Lieferadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat von der First Cash Solution aktiviert werden. |
| AddrCity | ans..40 | O | Ortsname der Lieferadresse |
| AddrState | ans..40 | O | Bundesland (Bundesstaat) der Lieferadresse. Die in AddrCity übergebene Stadt muss im angegebenen Bundesstaat liegen, sonst lehnt PayPal die Zahlung ab. Mögliche Werte entnehmen Sie bitte der PayPal-API-Reference Dokumentation. |
| AddrZip | ans..20 | O | Postleitzahl der Lieferadresse |
| AddrCountryCode | an2 | O | Ländercode des Lieferlandes |
| Phone | n..20 | O | Telefonnummer |
Parameter für PayPal-Autorisierung
Die folgende Tabelle beschreibt die Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung, z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für alle einzelnen Transaktionen (Order, Sale, Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..30 | M | OK oder FAILED |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description sondern Code für die Auswertung des Transaktionsstatus! |
| Code | n8 | M | Fehlercode gemäß Excel-Datei 1cs Online Bezahlsystem Antwort Codes (Fehlercodes) |
| CodeExt | n..10 | O | Fehlercode von PayPal, wenn mit dem First Cash Solution Support abgesprochen |
Ergebnis-Parameter bei PayPal-Autorisierung
3.5 Aufruf der Schnittstelle für eine Buchung
Um eine Buchung (Capture) für PayPal über eine Server-zu-Server-Verbindung auszuführen, ver-wenden Sie bitte folgende URL:
Hinweis: Aus Sicherheitsgründen lehnt das 1cs Online Bezahlsystem alle Zahlungsanfragen mit Formatfehlern ab. Bitte übergeben Sie deshalb bei jedem Parameter den korrekten Datentyp.
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den 1cs Support, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a..3 | M | Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: A1 Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/. |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| ReqId | ans..32 | O | Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion / Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder auch jede Aktion mit derselben ReqID erneut eingereicht wird, führt das 1cs OBS keine Zahlung / weitere Aktion aus sondern gibt nur den Status der ursprünglichen Transaktion / Aktion zurück. Bitte beachten Sie, dass das 1cs OBS für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet. |
| RefNr | ans..30 | O | Referenznummer des Händlers: hier kann eine separate Referenznummer wie z.B. Rechnungsnummer übergeben werden Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| TID | ans..17 | O | Eindeutige Transaktionsnummer bei PayPal. Notwendig bei Teilbuchungen auf vorangegangene Autorisierungen. |
| CompleteType | ans..3 | O | Wird <YES> übergeben, wird bei der Buchung die mögliche offene Order von PayPal geschlossen. (Hintergrund: seitens PayPal ist eine 115% Buchung zulässig. Bei Buchung ab 100% sendet das 1cs Online Bezahlsystem automatisch einen Aufruf zum Schließen der Zahlung an PayPal.) |
Parameter für PayPal-Buchungen
Die folgende Tabelle beschreibt die Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung, z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für alle einzelnen Transaktionen (Order, Sale, Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..30 | M | OK oder FAILED |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description sondern Code für die Auswertung des Transaktionsstatus! |
| Code | n8 | M | Fehlercode gemäß 1cs Online Bezahlsystem Antwort Codes (Fehlercodes) |
| CodeExt | n..10 | O | Fehlercode von PayPal, wenn mit dem First Cash Solution Support abgesprochen |
| TID | ans..17 | O | Eindeutige Transaktionsnummer bei PayPal. Notwendig bei Teilbuchungen auf vorangegangene Autorisierungen. |
Ergebnis-Parameter für PayPal-Buchungen
3.6 Aufruf der Schnittstelle für eine Gutschrift mit Referenz
Um eine Gutschrift (Credit) mit Referenztransaktion für PayPal auszuführen, verwenden Sie bitte folgende URL:
Hinweis: Aus Sicherheitsgründen lehnt das 1cs Online Bezahlsystem alle Zahlungsanfragen mit Formatfehlern ab. Bitte übergeben Sie deshalb bei jedem Parameter den korrekten Datentyp.
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| PayID | ans..64 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| TransID | an32 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den 1cs Support, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a3 | M | Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/. |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| ReqId | ans..32 | O | Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion / Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder auch jede Aktion mit derselben ReqID erneut eingereicht wird, führt das 1cs OBS keine Zahlung / weitere Aktion aus sondern gibt nur den Status der ursprünglichen Transaktion / Aktion zurück. Bitte beachten Sie, dass das 1cs OBS für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet. |
| RefNr | ans..30 | O | Referenznummer des Händlers: hier kann eine separate Referenznummer wie z.B. Rechnungsnummer übergeben werden Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| Account | ans..128 | O | Zur Steuerung mehrerer PayPal-Accounts, Händler-Account: ID oder E-Mail-Adresse, für die die Anfrage an PayPal gesendet werden soll |
| TID | ans..17 | O | Eindeutige Transaktionsnummer bei PayPal. Notwendig bei Teilgutschriften auf vorangegangene Teilbuchungen. |
| Note | ans..768 | C | Hinweistext für Empfänger |
| Subject | ans..255 | C | MassPay: Betreff für E-Mail an Empfänger Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den 1cs Support, um diese Funktion für Sie zu aktivieren. |
Parameter für PayPal-Gutschriften mit Bezugstransaktion
Die folgende Tabelle beschreibt die Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung, z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für alle einzelnen Transaktionen (Order, Sale, Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..30 | M | OK oder FAILED |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description sondern Code für die Auswertung des Transaktionsstatus! |
| Code | n8 | M | Fehlercode gemäß Excel-Datei 1cs Online Bezahlsystem Antwort Codes |
| CodeExt | n..10 | O | Fehlercode von PayPal, wenn mit dem First Cash Solution Support abgesprochen |
| TID | ans..17 | O | Eindeutige Transaktionsnummer bei PayPal. Notwendig bei Teilbuchungen auf vorangegangene Autorisierungen. |
| FeeRefundAmount | n..10 | O | Gutgeschriebener Betrag der PayPal-Transaktionsgebühren. Notwendig bei Teilgutschriften auf vorangegangene Teilbuchungen. |
| GrossRefundAmount | n..10 | O | Gutgeschriebener Betrag an den Käufer bei dieser Gutschrift. Notwendig bei Teilgutschriften auf vorangegangene Teilbuchungen. |
| NetRefundAmount | n..10 | O | Von ihrem PayPal-Konto abgezogener Betrag, um diese Gutschrift auszuführen. Notwendig bei Teilgutschriften auf vorangegangene Teilbuchungen. |
Ergebnis-Parameter für PayPal-Gutschriften mit Bezugstransaktion
3.7 Aufruf der Schnittstelle für nicht referenzierte Gutschriften
Um eine Gutschrift ohne Bezugstransaktion für PayPal abzuwickeln, nutzen Sie folgende URL und Parameter:
https://www.computop-paygate.com/paypalcreditEx.aspx
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| TransID | ans..64 | M | TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den 1cs Support, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a3 | M | Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/. |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| ReqID | ans..32 | O | Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion / Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder auch jede Aktion mit derselben ReqID erneut eingereicht wird, führt das 1cs OBS keine Zahlung / weitere Aktion aus sondern gibt nur den Status der ursprünglichen Transaktion / Aktion zurück. Bitte beachten Sie, dass das 1cs OBS für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet. |
| RefNr | ans..30 | O | Referenznummer des Händlers: hier kann eine separate Referenznummer wie z.B. Rechnungsnummer übergeben werden Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| Note | ans..768 | C | MassPay: Hinweistext für Empfänger Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den 1cs Support, um diese Funktion für Sie zu aktivieren. |
| Subject | ans..255 | C | MassPay: Betreff für E-Mail an Empfänger Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den 1cs Support, um diese Funktion für Sie zu aktivieren. |
| Payer | ans..100 | O | MassPay: E-Mail-Adresse des Käufers Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den 1cs Support, um diese Funktion für Sie zu aktivieren. |
Parameter für PayPal-Gutschriften ohne Bezugstransaktion
Die folgende Tabelle beschreibt die Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung, z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für alle einzelnen Transaktionen (Order, Sale, Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..30 | M | OK oder FAILED |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description sondern Code für die Auswertung des Transaktionsstatus! |
| Code | n8 | M | Fehlercode gemäß Excel-Datei 1cs Online Bezahlsystem Antwort Codes |
| CodeExt | n..10 | O | Fehlercode von PayPal, wenn mit dem First Cash Solution Support abgesprochen |
| FeeRefundAmount | n..10 | O | Gutgeschriebener Betrag der PayPal-Transaktionsgebühren. Notwendig bei Teilgutschriften auf vorangegangene Teilbuchungen. |
| GrossRefundAmount | n..10 | O | Gutgeschriebener Betrag an den Käufer bei dieser Gutschrift. Notwendig bei Teilgutschriften auf vorangegangene Teilbuchungen. |
| NetRefundAmount | n..10 | O | Von ihrem PayPal-Konto abgezogener Betrag, um diese Gutschrift auszuführen. Notwendig bei Teilgutschriften auf vorangegangene Teilbuchungen. |
Ergebnis-Parameter für PayPal-Gutschriften ohne Bezugstransaktion
3.8 Aufruf der Schnittstelle für Stornierungen
Um eine Transaktion bei PayPal zu stornieren, nutzen Sie folgende URL und Parameter:
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent) Bitte wenden Sie sich an den Helpdesk, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a..3 | M | Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/. |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) mit SHA-256-Algorithmus. Details finden Sie hier: HMAC-Authentisierung (Anfrage) HMAC-Authentisierung (Notify) |
| ReqId | ans..32 | O | Um Doppelzahlungen zu vermeiden, übergeben Sie einen alphanumerischen Wert, der Ihre Transaktion / Aktion identifiziert und nur einmal vergeben werden darf. Falls die Transaktion oder auch jede Aktion mit derselben ReqID erneut eingereicht wird, führt das 1cs OBS keine Zahlung / weitere Aktion aus sondern gibt nur den Status der ursprünglichen Transaktion / Aktion zurück. Bitte beachten Sie, dass das 1cs OBS für die erste initiale Aktion einen abgeschlossenen Transaktionsstatus haben muss. Einreichungen mit identischer ReqID auf einen offenen Status werden regulär verarbeitet. Bitte beachten Sie, dass eine ReqID nur 12 Monate gültig ist, danach wird sie vom 1cs Online Bezahlsystem gelöscht. |
| TID | ans..17 | O | Eindeutige Transaktionsnummer bei PayPal. Notwendig bei Teilstornierungen auf vorangegangene Teilautorisierungen. |
Parameter für PayPal-Stornierungen
Die folgende Tabelle beschreibt die Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung, z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für alle einzelnen Transaktionen (Order, Sale, Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..30 | M | OK oder FAILED |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description sondern Code für die Auswertung des Transaktionsstatus! |
| Code | n8 | M | Fehlercode gemäß Excel-Datei 1cs Online Bezahlsystem Antwort Codes (Fehlercodes) |
| CodeExt | n..10 | O | Fehlercode von PayPal, wenn mit dem First Cash Solution Support abgesprochen |
| TID | ans..17 | O | Eindeutige Transaktionsnummer bei PayPal. Notwendig bei Teilstornierungen auf vorangegangene Teilautorisierungen. |
Ergebnis-Parameter für PayPal-Stornierungen
3.9 Aufruf der Schnittstelle für Abonnements
3.9.1 Voraussetzungen
- Die Option „Reference Transaction“ muss bei PayPal eingerichtet sein. Bitten Sie PayPal direkt um die Aktivierung.
- Bitte konfigurieren Sie zusätzlich die entsprechende Genehmigung in Ihrem Paypal-Händlerkonto
- Belasten bestehender Kunden auf der Grundlage einer früherer Transaktion
- Einholen der Autorisierung und initiieren von PayPal-Zahlungen per Händleranbindung
- Die Option „Reference Transaction“ muss für Ihre 1cs OBS MerchantID eingerichtet sein.
3.9.2 Ablauf
1. Zur Erstellung eines Abos wird zuerst eine normale PayPal-Zahlung mit dem zusätzlichen Parameter „RTF=I“ initiiert. Dies fügt ein Abo-Flag an die Transaktion an, damit diese von PayPal wiedererkannt wird. Möchten Sie in dem ersten Request nur die „BillingAgreementID“ holen, ohne dem Kunden einen Betrag anzuzeigen, übermitteln Sie bitte an das 1cs Online Bezahlsystem den Parameter “txtype=BAID”. Wird der txtype=BAID gesendet, wird der eingereichte Betrag vom 1cs OBS automatisch auf 0,00 gesetzt.
Bitte beachten Sie, dass der Händler auf gar keinen Fall einen Betrag von 0,00€ senden darf, dies kann unser 1cs Online Bezahlsystem nicht verarbeiten.
D.h. der Händler muss einen Betrag X >0,00 übertragen und wir setzen diesen dann in Richtung PayPal auf 0,00.
2. Unsere Response an den Händler enthält die normalen PayPal-Parameter sowie den zusätzlichen Parameter „BillingAgreementID“. Dieser muß in deren System an der Zahlung hinterlegt werden.
3. Zur Erstellung der zweiten/wiederkehrenden Abo-Zahlung verwenden Sie bitte die URL https://www.computop-paygate.com/paypalAbo.aspx durchgeführt werden. In dieser Server-zu-Server-Verbindung verwenden Sie bitte die normalen PayPal-Parameter zuzüglich des Parameters „BillingAgreementID“. Der zusätzliche Parameter löst die zweite/wiederkehrende Zahlung mit Bezug auf die ursprüngliche Zahlung aus Auf diese Weise ist kein Login des PayPal-Kunden notwendig und Sie können Beträge von dessen Konto abbuchen.
3.9.3 Hinweis
- Folgender Zusatz wird während des Bezahlprozesses im PayPal Account des Kunden angezeigt (Beispiel):
“Hiermit genehmigen Sie –Händlername–, künftige Zahlungen direkt und ohne Ihr Zutun von Ihrem PayPal-Konto abzubuchen. Sie können diese Genehmigung für die Zukunft jederzeit in Ihrem Profil widerrufen.” - Der Kunde kann sich in seinem PayPal Account über diese Funktion informieren.
3.9.4 Capture on demand (capture=manual + txtype=Order oder Auth)
- Wenn die initiale Zahlung mit txtype=Order oder Auth ausgeführt wird, sendet das 1cs OBS die „BillingAgreementID“ bereits im Notify auf diese Aktion mit zurück. Beim darauffolgenden Capture muss diese nicht mitgegeben werden, nur wenn wirklich ein komplett neues Payment ausgelöst wird.
3.9.5 Löschen der BillingAgreementID
- Grundsätzlich kann ein Kunde die generierte BillingAgreementID in seinem PayPal-Konto löschen/stornieren. Eine Info darüber kann ein Händler nur erhalten, wenn die zusätzliche Option IPN “instant payment notification” für sein Konto aktiviert ist. Diese Aktivierung muss sowohl im Konto bei 1cs OBS als auch bei PayPal erfolgen. Bitte beachten Sie, dass der Händler bei aktiviertem IPN auch Meldungen zu jeder Statusänderung einer PayPal-Zahlung erhält.
- Wenn ein Kunde die BillingAgreementID löscht, sind weitere Zahlungen mit dieser ID nicht mehr möglich. Eine gelöschte BillingAgreementID kann nicht mehr aktiviert werden.
3.9.6 Zahlungsabwicklung für Abonnements
Die Abwicklung von PayPal-Zahlungen per Abonnement setzt eine Initial-Transaktion voraus, die über die übliche Schnittstelle abgewickelt worden ist. Zudem muss die Möglichkeit von Abonnements zuvor sowohl bei PayPal als auch bei 1cs OBS aktiviert worden sein. Dazu muss die Option „Reference Transaction“ beim 1cs Online Bezahlsystem und bei PayPal eingerichtet sein. Zudem sind im Bereich „Verfügbare Genehmigungen“ bei der Einrichtung (siehe Kapitel PayPal-API freigeben oben) folgende 3 Optionen zu aktivieren:
– Belasten bestehender Kunden auf der Grundlage früherer Transaktionen
– Erstellen und Verwalten von Abonnementzahlungen
– Einholen der Autorisierung und Initiierung von PayPal-Zahlungen per Händlerabbuchung
Um eine PayPal-Zahlung per Abonnement abzuwickeln, nutzen Sie folgende URL und Parameter:
Die folgende Tabelle beschreibt die verschlüsselten Übergabeparameter:
| Key | Format | CND | Beschreibung |
| MerchantID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird. Dieser Parameter ist zusätzlich auch unverschlüsselt zu übergeben. |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent) Bitte wenden Sie sich an den 1cs Support, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a..3 | M | Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/. |
| RefNr | ans..30 | O | Referenznummer des Händlers, die für jede Zahlung eindeutig sein muss Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| OrderDesc | ans..30 | Beschreibung der gekauften Waren, Einzelpreise etc. | |
| Capture | a..6 | M | Auto oder Manual: bestimmt, ob der angefragte Betrag sofort oder erst später abgebucht wird. Wichtiger Hinweis: Bitte kontaktieren Sie den First Cash Solution Support für Manual, um die unterschiedlichen Einsatzmöglichkeiten abzuklären. |
| TxType | ans..5 | M | Pflicht bei Capture=Manual: Transaktionstyp mit den möglichen Werten Order sowie Auth |
| BillingAgreementID | an19 | M | Identifikationsnummer der Rechnungsvereinbarung. Wenn der Käufer die Rechnungsvereinbarung bestätigt, wird sie gültig und bleibt gültig, bis sie vom Käufer widerrufen wird. |
| RTF | ans1 | O | Bei wiederkehrenden Zahlungen (Abos): I = Initialzahlung eines neuen Abos, R = Wiederkehrende Zahlung (Recurring) |
| FirstName | ans..30 | OC | (Pflicht für USA und Kanada): Entweder nur der Vorname oder Vor- und Nachname, falls ein Firmenname als Lieferadresse genutzt wird. |
| LastName | ans..30 | OC | (Pflicht für USA und Kanada): Nachname oder Firmenbezeichnung der Lieferadresse |
| AddrStreet | ans..100 | OC | (Pflicht für USA und Kanada): Straßenname der Lieferadresse |
| AddrCity | ans..40 | OC | (Pflicht für USA und Kanada): Ortsname der Lieferadresse |
| AddrState | ans..40 | OC | (Pflicht für USA und Kanada): Bundesland (Bundesstaat) der Lieferadresse. Die in AddrCity übergebene Stadt muss im angegebenen Bundesstaat liegen, sonst lehnt PayPal die Zahlung ab. Mögliche Werte entnehmen Sie bitte der PayPal-API-Reference Dokumentation. |
| AddrZip | ans..20 | OC | (Pflicht für USA und Kanada): Postleitzahl der Lieferadresse |
| AddrCountryCode | an2 | O | Ländercode des Lieferlandes |
| Phone | n..20 | O | Telefonnummer |
Parameter für PayPal-Abonnements
Die folgende Tabelle beschreibt die Parameter, die das 1cs Online Bezahlsystem als Antwort zurückgibt:
es können jederzeit neue Parameter hinzugefügt bzw. die Reihenfolge geändert werden
die Parameter (z.B. MerchantId, RefNr) sollten nicht auf Groß-/Kleinschreibung geprüft werden
| Key | Format | CND | Beschreibung |
| MID | ans..30 | M | HändlerID, die von der First Cash Solution vergeben wird |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung, z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| XID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für alle einzelnen Transaktionen (Order, Sale, Autorisierung, Buchung, Gutschrift), die für eine Zahlung durchgeführt werden |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Status | a..30 | M | OK oder FAILED |
| Description | ans..1024 | M | Nähere Beschreibung bei Ablehnung der Zahlung. Bitte nutzen Sie nicht den Parameter Description sondern Code für die Auswertung des Transaktionsstatus! |
| Code | n8 | M | Fehlercode gemäß Excel-Datei 1cs Online Bezahlsystem Antwort Codes (Fehlercodes) |
| CodeExt | n..10 | O | Fehlercode von PayPal, wenn mit dem First Cash Solution Support abgesprochen |
| BillingAgreementID | an19 | M | Identifikationsnummer der Rechnungsvereinbarung. Wenn der Käufer die Rechnungsvereinbarung bestätigt, wird sie gültig und bleibt gültig, bis sie vom Käufer widerrufen wird. |
Ergebnis-Parameter für PayPal-Abonnements
4 Batch-Nutzung der Schnittstelle
Grundsätzliche Informationen zur Arbeit mit Batch-Dateien sowie zu deren Aufbau erfahren Sie im separaten Handbuch zum Batchmanager. Im Batch-Verfahren sind nicht alle Funktionen verfügbar, die für die Online-Schnittstelle verfügbar sind.
Dieses Kapitel beschreibt die Parameter, die Sie im Datensatz (Record) für die Ausführung einer PayPal-Zahlung übergeben müssen und welche Informationen Sie der Antwort-Datei über den Status des Zahlungsvorgangs entnehmen können.
Bei den Batch-Aufrufen ist die verwendete Batch-Version zu unterscheiden, wovon die optionalen Parameter abhängen. Alle mit „2.“ beginnen Versionsbezeichnungen betreffen Aufrufe für einen Konzern. Das bedeutet, innerhalb einer Batch-Datei mit einer bestimmten MerchantID können auch Transaktionen anderer Händler mit einer abweichenden Sub-MID übertragen werden.
Folgende Tabelle gibt eine Übersicht der pro Aktion jeweils möglichen Batch-Versionen und ihrer Besonderheiten:
| Aktion | Version | Beschreibung |
| Authorize | 1.0 / 2.0 | Standardversion ohne Rückgabe von Code |
| 1.4 / 2.4 | mit TID | |
| Capture | 1.0 / 2.0 | Standardversion ohne Rückgabe von Code |
| 1.x / 2.x | mit RefNr (gilt für alle Versionen außer 1.0) | |
| 1.4 / 2.4 | mit TID | |
| Credit | 1.0 / 2.0 | Standardversion ohne Rückgabe von Code |
| 1.x / 2.x | mit RefNr (gilt für alle Versionen außer 1.0) | |
| 1.4 / 2.4 | mit TID | |
| CreditEx | 1.0 / 2.0 | Standardversion ohne Rückgabe von Code |
| 1.x / 2.x | mit RefNr (gilt für alle Versionen außer 1.0) | |
| Reverse | 1.0 / 2.0 | Standardversion ohne Rückgabe von Code |
| 1.4 / 2.4 | mit TID | |
| Abo | 1.0 / 2.0 | Standardversion ohne Rückgabe von Code |
| 1.x / 2.x | mit RefNr (gilt für alle Versionen außer 1.0) |
Beschreibung der möglichen Batch-Versionen
Der Aufbau für eine PayPal-Zahlung in einer einzureichenden Batch-Datei sieht folgendermaßen aus:
HEAD,<MerchantID>,<Date>,<Version>
PAYPAL,Authorize,<Amount>,<Currency>,<TransID>,<PayID>
PAYPAL,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>(,<TID>)
PAYPAL,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>(,<TID>) PAYPAL,CreditEx,<TransID>,(<RefNr>,)<Amount>,<Currency>,<payer>,<note> PAYPAL,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>(,<TID>) PAYPAL,ABO,<Amount>,<Currency>,<TransID>,(<RefNr>,)(<OrderDesc>,)(<Capture>,)(<TxType>,)<BillingAgreementId>
FOOT,<CountRecords>,<SumAmount>
Beispiel für Master MID Funktion:
HEAD,[Master]MerchantID,Date,2.x
Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action)
FOOT,CountRecords,SumAmount
Hinweis: Bei Version 1.4 ist es auch möglich, bei einer Capture-Aktion den CompleteType zusätzlich mit zu übergeben:
PAYPAL,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>(,<CompleteType>,<TID>)
Die folgende Tabelle beschreibt die einzelnen Felder und Werte, die im Datensatz (Record) innerhalb der Batch-Datei verwendet werden:
| Key | Format | CND | Beschreibung |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für Vom 1cs Online Bezahlsystem vergebene ID für diese Transaktion |
| TransID | ans..64 | M | Ihre eigene TransaktionsID, die für jede Zahlung eindeutig sein muss |
| Amount | n..10 | M | Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den 1cs Support, wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. |
| Currency | a3 | M | Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP. Hier eine Übersicht: Währungstabelle. Bitte beachten Sie die weltweit von PayPal unterstützten Währungen unter https://developer.paypal.com/api/rest/reference/currency-codes/. |
| Type | a..11 | M | HEAD für Header, FOOT für Footer, PAYPAL für PayPal |
| Action | a..20 | M | Der Action-Parameter definiert die Art der Transaktion: Authorize (Autorisierung) Capture (Buchung) Credit (Gutschrift) CreditEx (Gutschrift ohne vorherige Buchung; bitte stimmen sie sich hierzu vorher mit dem First Cash Solution Support ab) Reverse (Storno) Abo (Abonnement) |
| RefNr | ans..30 | O | eindeutige Referenznummer Es sind ausschließlich ASCII-Zeichen erlaubt. Sonderzeichen wie (“Umlaute”, …) sind nicht erlaubt und müssen ggf. durch ASCII-Zeichen ersetzt werden (z.B. ü → ue, é → e, …). |
| payer | ans..100 | O | MassPay: E-Mail-Adresse des Käufers: Übergeben Sie hier den erhaltenen Parameter E-Mail aus der Response. Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den 1cs Support, um diese Funktion für Sie zu aktivieren. |
| note | ans..758 | O | Hinweistext für Empfänger |
| TID | ans..17 | O | Eindeutige Transaktionsnummer bei PayPal. Notwendig bei mehreren Autorisierungen oder Teilbuchungen, Teilgutschriften, Teilstornierungen. |
| OrderDesc | ans..127 | O | Beschreibung der gekauften Waren, Einzelpreise etc. |
| Capture | a..6 | O | Auto oder Manual: bestimmt, ob der angefragte Betrag sofort oder erst später abgebucht wird. |
| TxType | ans..5 | OC | Pflicht bei Capture=Manual: Transaktionstyp mit den möglichen Werten Order sowie Auth |
| BillingAgreementID | an19 | M | Identifikationsnummer der Rechnungsvereinbarung. Wenn der Käufer die Rechnungsvereinbarung bestätigt, wird sie gültig und bleibt gültig, bis sie vom Käufer widerrufen wird. |
Währung, drei Zeichen DIN / ISO 4217, z.B. EUR, USD, GBP.
Der Record-Bereich in der Antwort-Datei zu Batch-Transaktionen sieht folgendermaßen aus:
HEAD,<MerchantID>,<Date>,<Version>
PAYPAL,Authorize,<Amount>,<Currency>,<TransID>,<PayID>,<Status>,<Code>,<CodeExt>
PAYPAL,Capture,<Betrag>,<Währung>,<TransID>,(<RefNr>,)<PayID>,(TID,)<Status>,<Code>,<CodeExt> PAYPAL,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,(TID,)<Status>,<Code>,<CodeExt> PAYPAL,CreditEx,<TransID>,(<RefNr>,)<Amount>,<Currency>,<payer>,<note>,<Status>,<Code>,<CodeExt> PAYPAL,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<Status>,<Code>,<CodeExt> PAYPAL,ABO,<Amount>,<Currency>,<TransID>,(<RefNr>,)(<OrderDesc>,)(<Capture>,)(<TxType>,)<BillingAgreementId>,<CodeExt>,<PayID>,<Status>,<Code> FOOT,<CountRecords>,<SumAmount>
Die folgende Tabelle beschreibt die Antwort-Parameter, die der Batch-Manager im Record-Bereich zu jeder Transaktion speichert (hier nicht erklärte Standardparameter wie etwa <TransID> oder <RefNR> und Aufrufparameter, werden unverändert zum Aufruf wieder zurückgegeben und sind vorstehend beschrieben):
| Key | Format | CND | Beschreibung |
| Action | a..20 | M | Der Action-Parameter definiert die Art der Transaktion wie Capture (Buchung) oder Credit (Gutschrift). |
| PayID | an32 | M | Vom 1cs Online Bezahlsystem vergebene ID für die Zahlung; z.B. zur Referenzierung in Batch-Dateien sowie im Capture- oder Credit-Request. |
| Status | a..50 | M | OK oder FAILED |
| Code | n8 | M | Fehlercode gemäß 1cs Online Bezahlsystem Antwort Codes. (Fehlercodes) |
Beschreibung der Ergebnis-Parameter im Datensatz von Batch-Dateien
5 PayPal Abrechnungsdateien
PayPal stellt verschiedene Typen von Abrechnungsdateien wie zum Beispiel DDR, DDL, STL, TRR oder ORT zur Verfügung, von denen es allerdings nicht jede täglich geben muss. Die Originalbeschreibungen der verschiedenen Abrechnungsdateien finden Sie auf Englisch auf der Webseite von PayPal unter der Adresse https://developer.paypal.com/docs/reports/sftp-reports/.
Grundlage der 1cs Online Bezahlsystem Abrechnungsdatei CTSF ist der STL-Report von PayPal. Dieser STL-Report gibt Händlern und Verarbeitungspartnern ausführliche Informationen über jede Transaktion, welche die Abrechnung von Geldern für das Konto beeinflusst. Die Details in dem Bericht enthalten den Ereigniscode der Transaktion und das Datum, wann die Transaktion ausgelöst wurde.
