Girocheckout API

User Tools

Site Tools

Trace: • PayPal

Sidebar

Introduction

Integration

Basics

Apple Pay
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal

Tools

Error codes
Result codes
Test data

SDK

PHP SDK
Java SDK
.NET SDK

Others

API Change log
Plugins Changelog

Imprint
Privacy policy
S-Public Services GmbH

Translations of this page:
en:girocheckout:paypal:start

This is an old revision of the document!

Table of Contents

PayPal

Information about credit card payent can be found under https://www.girosolution.de/girocheckout/bezahlverfahren.html.

test data

For testing purpose there runs a PayPal sumulation page. After initialisation of a PayPal payent the buyer is redirected to a simulation page. There can be chosed if the transaction should be finished successfully or unsuccessfully.

Transaktionsausgang

ResultCode Antwortcode Hinweis
4000 successful transaction The payment result can be chosen in the simulation page.
4900 unsuccessful transaction The payment result can be chosen in the simulation page.

workflow

buyermerchantGiroCheckoutPayPalbuyermerchantGiroCheckoutPayPal1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 (c)2013 by GiroSolution AG

  1. buyer chooses PayPal payment method
  2. merchant initialises PayPal transaction (initialising PayPal payment)
  3. GiroCheckout initialises transaction at PayPal
  4. PayPal submits response to GiroCheckout
  5. merchant gets response about initialisation (if an issue occurs the transaction is finished)
  6. merchant sends redirect URL to buyer
  7. the buyer's browser redirects buyer to the payment form
  8. PayPal shows payment form
  9. buyer authorises payment
  10. transaction is beeing processed
  11. PayPal submits payment result to GiroCheckout
  12. GiroCheckout notifies merchant about the payment result (payment result norification)
  13. merchant processes result
  14. merchant sends HTTP statuscode to GiroCheckout
  15. GiroCheckout sends merchants redirect page to PayPal
  16. buyer clicks “back to the shop” and gets redirected to the merchant (buyer redirection)

API functions

overview

As shown in the workflow there are different API calls during a PayPal transaction.

  1. initialise transaction
  2. payment result notification to merchant
  3. buyer redirection to the merchant (triggered by buyer)

initialise PayPal payment

Torwards a successful initialisation you receive a reference number and an redirect link. The redirect link leads to the payment page of PayPal. He has to be redirected. This can be achieved by a HTTP-Redirect-Header, HTML page with a corresponding Meta-Tag or JavaScript redirect.

request

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
provided by: GiroCheckout
called by: merchant

parameters
name mandatory type description
merchantId yes Integer merchant ID
projectId yes integer project ID
merchantTxId yes String(255) unique transaction id of the merchant
amount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency yes String(3) currency
EUR = Euro
purpose yes String(27) purpose
locale optional String(4) language of the credit card payment page
de = German (default)
en = English
es = Spanish
fr = French
it = Italian
pt = Portuguese
nl = Dutch
cs = Czech
sv = Swedish
da = Danish
pl = Polish
spde = Derman donate
spen = English donate
mobile optional Boolean optimised payent page for moible devices
0 = no (default)
1 = yes
pkn optional String(50) This field is used process a transaction without re-entering the card data.
create = generate a new pseudo card number
[pseudo card number] = pkn of the masked card data (see pseudo card number)
recurring optional Boolean recurring payment
0 = no (default)
1 = yes
urlRedirect yes String URL, where the buyer has to be sent after payment
urlNotify yes String URL, where the notification has to be sent after payment
hash yes String HMAC MD5 hash (see hash generation)
example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "locale=de" \
     -d "mobile=0" \
     -d "pkn=create" \
     -d "recurring=0" \
     -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \
     -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \
     -d "hash=26fbe72bcc0b7cd0b024b2282e974583" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

reply

The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialised. The response also includes a transaction id and a redirect URL to the payment page.

Parameter
name mandatory type description
rc yes Integer response code
msg yes String additional information about the response code
reference optional String unique GiroCheckout transaction ID
redirect optional String redirect URL to the payment page
hash yes String HMAC MD5 hash (see hash generation)
example in case of success
{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=wrlIRO9O30S4NNAO9h6uHwhyWibDFKUWeoWy7mPLDDyZ","rc":"0","msg":""}
example in case of error
{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}

notification about the payment result

The result of a initialised transaction will be submitted to the prior specified URL in the urlNotify parameter. This notification should be used to update the payment status in the merchants system. The result of the payment is contained in the field gcResultPayment. Due to the internal payment process, a redirection of the customer to urlRedirect is not done automatically but only after a customer click.

request

URL: notifyUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout

GET parameter
name mandatory type description
gcReference yes String unique GiroCheckout transaction ID
gcMerchantTxId yes String merchant transaction ID
gcBackendTxId yes String payment processor transaction ID
gcAmount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
gcCurrency yes String currency
gcResultPayment optional Integer payment result codes
gcHash yes String HMAC MD5 hash (see hash generation)

reply

As a reply to the GET request, one of the following HTTP status codes is expected.

HTTP status code description
200 (OK) The notification was processed correctly.
400 (Bad Request) The merchant did not process the notification and does not wish to be notified again.
all others The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400.

redirection of the customer to merchant

After completing the payment, the customer may return to the merchant through a link. This return is not done automatically.

request

URL: redirectUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout

GET parameter
name mandatory type description
gcReference yes String unique GiroCheckout transaction ID
gcMerchantTxId yes String merchant transaction ID
gcBackendTxId yes String payment processor transaction ID
gcAmount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
gcCurrency yes String currency
gcResultPayment optional Integer payment result codes
gcHash yes String HMAC MD5 hash (see hash generation)

Initialisierung einer PayPal Zahlung

Durch eine erfolgreiche Initialisierung wird eine Referenznummer erstellt sowie ein Weiterleitunsurl (redirect) an den Händler übermittelt. Der Kunde muss an diese URL weitergeleitet werden. Dies kann durch einen HTTP-Redirect-Header, eine HTML-Seite mit entsprechendem Meta-Tag oder Javascript erfolgen.

Anfrage

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler

Parameter
Name Pflicht Type Beschreibung
merchantId Ja Integer Händler-ID eines PayPal Projekts
projectId Ja integer Projekt-ID eines PayPal Projekts
merchantTxId Ja String(255) Eindeutige Transaktions-ID des Händlers
amount Ja Integer Betrag in Cent
currency Ja String(3) Währung der Transaktion
EUR = Euro
purpose Ja String(27) Verwendungszweck der PayPal Transaktion
urlRedirect Ja String URL, an die der Kunde nach der Zahlung geschickt werden soll.
urlNotify Ja String URL, an die der Zahlungsausgang gemeldet werden soll.
hash Ja String HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
Beispiel
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \
     -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \
     -d "hash=19a1f2dae3e6fccc37ea29e025ebfb1a" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Antwort

Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, wurde die Transaktion erfolgreich initialisiert. Sie bekommen als Antwort eine Transaktionsnummer und eine redirectURL zum PayPal Formular zurück.

Parameter
Name Pflicht Type Beschreibung
rc Ja Integer Fehlernummer
msg Ja String zusätzliche Informationen im Fehlerfall
reference Optional String eindeutige GiroCheckout Transaktions-ID
redirect Optional String Redirect URL zur Weiterleitung des Kunden an sein Online Banking
Beispiel im Erfolgsfall

hash : 43bcc298c042d657506c25bd90812750 

{"reference":"a79985f0-004e-4823-9de4-54fcb45fab37","redirect":"https://payment.girosolution.de/payment/services/paypal/simulate/1196312","rc":"0","msg":""}
Beispiel im Fehlerfall

hash : f826b7b320bf0115722cc3276319b0a8 

{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}

Benachrichtigung über den Zahlungsausgang

Der Ausgang einer Zahlung wird, an die im urlNotify Paramter angegebene URL, übermittelt. Diese Rückmeldung dient dazu, dem Händler den Ausgang der Transaktion mitzuteilen. Durch diese Information kann der Transaktionsstatus beim Händler geändert werden.

Der Zahlungausgang einer Transaktion steht im Feld gcResultPayment.

Aufgrund des Zahlungsablaufes findet keine automatische Rückleitung des Käufers an die im Parameter urlRedirect angegebene URL statt. Eine Weiterleitung erfolgt erst, wenn der Käufer den “Abbrechen” oder “Zurück zum Shop” Button drückt.

Anfrage

URL: notifyUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout

GET Parameter
Name Pflicht Type Beschreibung
gcReference Ja String GiroCheckout Transaktions-ID
gcMerchantTxId Ja String Händler Transaktions-ID
gcBackendTxId Ja String Zahlungsabwickler Transaktions-ID
gcAmount Ja Integer bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
gcCurrency Ja String Währung
gcResultPayment Optional Integer Ergebniscodes der Zahlung
gcHash Ja String HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

Antwort

Als Antwort auf den GET-Request wird einer der folgenden HTTP Statuscodes erwartet.

HTTP Statuscode Beschreibung
200 (OK) Die Benachrichtigung wurde korrekt verarbeitet.
400 (Bad Request) Der Händler hat die Benachrichtigung nicht verarbeitet, möchte aber auch nicht erneut benachrichtigt werden.
Alle anderen Die Benachrichtigung wird max. 10 Mal alle 30 Minuten wiederholt, bis der Händler den HTTP Statuscode 200 oder 400 zurückgibt.

Rückleitung des Kunden zum Händler

Nach Beendigung der Zahlung kann der Kunde über einen Link zurück zum Händler kommen. Eine Weiterleitung erfolgt erst, wenn der Käufer den „Abbrechen“ oder „Zurück zum Shop“ Button drückt. Diese Rückleitung erfolgt nicht automatisch.

Anfrage

URL: redirectUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout

GET Parameter
Name Pflicht Type Beschreibung
gcReference Ja String GiroCheckout Transaktions-ID
gcMerchantTxId Ja String Händler Transaktions-ID
gcBackendTxId Ja String Zahlungsabwickler Transaktions-ID
gcAmount Ja Integer bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
gcCurrency Ja String Währung
gcResultPayment Ja Integer Ergebnis der Zahlung
gcHash Ja String HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
en/girocheckout/paypal/start.1400070728.txt.gz · Last modified: 2021/04/12 14:33

Page Tools