Table of Contents

SOFORT Überweisung

You may find further information on the payment method “SOFORT Überweisung” here: https://www.girosolution.de/girocheckout/fuer-haendler/.

Test data

Form field Input value
BLZ 88888888
BIC SFRTDE20XXX
Login (any)
Passwort (any)
Konto (select from list)
TAN (any)

Workflow

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

  1. Customer selects payment method Sofortüberweisung
  2. Shop initiates transaction for Sofortüberweisung (Initialization)
  3. GiroCheckout initializes transaction at SOFORT
  4. SOFORT transmits payment URL to GiroCheckout
  5. Shop receives response with payment URL (transaction ends in case of error)
  6. Shop sends payment URL to customer browser
  7. Customer browser redirects to Sofortüberweisung
  8. Sofortüberweisung requests payment data from customer
  9. Customer enters payment data and authorizes transaction
  10. SOFORT carries out transaction
  11. SOFORT calls Girocheckout for customer redirect
  12. Girocheckout redirects customer to result page
  13. SOFORT informs GiroCheckout about transaction outcome
  14. GiroCheckout notifies Shop about transaction outcome (Notification)
  15. Shop processes transaction outcome
  16. Shop sends HTTP status code to GiroCheckout

API-Functions

Overview

As shown in the workflow diagram above, there are several API calls during a Sofortüberweisung transaction.

  1. Initialize transaction
  2. Transmit payment information to merchant
  3. Payment information with redirect of customer browser back to merchant (triggered by customer after payment)

Below, the API fields and calls are explained in detail.

Initialization of a SOFORT payment

A successful initialization creates a reference number and transmits a redirection link to the merchant. The link leads to the SOFORT website where the customer carries out the payment process. The customer must be redirected to this URL. This may happen by means of an HTTP redirect header, an HTML page with a corresponding meta tag or through Javascript.

Request

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
Provided by: GiroCheckout
Called by: Merchant

POST Parameters
Name Mandatory Type Description
merchantId Yes Integer Merchant ID of a SOFORT project
projectId Yes integer Project ID of a SOFORT project
merchantTxId Yes String(255) Unique transaction ID of the merchant
amount Yes Integer Amount in cents
If kind = 2, then specify an amount of 0
currency Yes String(3) Currency of the transaction
EUR = Euros (default)
purpose Yes String(27) Purpose of the SOFORT Überweisung
bic Optional String(11) BIC (8 or 11-digits)
urlRedirect Yes String URL to redirect the customer to after the payment.
urlNotify Yes String URL for notification of the payment outcome.
hash Yes String HMAC MD5 hash on all the values of the call. See hash generation
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=10000" \
     -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=e7d0315da159739d8087277f786f6f2f" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Response

The response contains a JSON Object. The field rc returns an error code. If rc = 0 is returned, the transaction was successfully initialized. The response contains a transaction number and the redirection URL to the SOFORT payment page.

Parameters
Name Mandatory Type Description
rc Yes Integer Error code
msg Yes String Additional information in case of error
reference Yes String Unique GiroCheckout transaction ID
redirect Yes String Redirect URL to lead the customer to the SOFORT payment page
HEADER Parameters
hash Yes String HMAC MD5 hash on all values of the response. See Response hash
Example in case of success

hash : ad1e0df28e2797a39c05ca08be654ef2 

{"reference":"7f6eaf07-c39f-41ea-91ba-d84e9ef27467","redirect":"https:\/\/www.sofort.com\/payment\/go\/5df96b843a91d433266d64cf6237bca27d4bd78a","rc":"0","msg":""}
Example in case of error

hash : f55ce87e132ebb7eb20004c6b186ce09 

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

Notification about transaction outcome

The outcome of a SOFORT payment is sent to the URL specified in the parameter urlNotify. This notification serves the purpose of informing the merchant about the transaction result. This information enables the merchant to modify his transaction status accordingly. The payment result of the SOFORT transaction can be found in the field gcResultPayment.

Because of the workflow in SOFORT transactions, there is no automatic redirection of the customer to the URL specified in the urlRedirect parameter. A redirection occurs only once the customer has clicked either the “Cancel” or the “Back to Shop” button.

Request

URL: notifyUrl from transaction initialization
Provided by: Merchant
Called by: GiroCheckout

GET Parameters
Name Mandatory Type Description
gcReference Yes String GiroCheckout transaction ID
gcMerchantTxId Yes String Merchant transaction ID
gcBackendTxId Yes String Payment processor transaction ID
gcAmount Yes Integer For currencies with decimals, specify amount in the smallest currency unit, e.g. Cent
gcCurrency Yes String Currency
gcResultPayment Yes Integer Result codes of the SOFORT payment
gcHash Yes String HMAC MD5 hash on all values of the call. See Hash generation

Response

As a response 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 didn't process the notification and doesn't want to be notified again.
All others The notification is repeated every 30 minutes for a maximum of 10 times, until the merchant either returns HTTP status code 200 or 400.

Redirection of customer to merchant

After completion of the SOFORT payment, the customer may return to the merchant via a link. A redirection occurs only once the customer has clicked either the “Cancel” or the “Back to Shop” button. This redirection is not done automatically.

Request

URL: redirectUrl from transaction initialization
Provided by: Merchant
Called by: GiroCheckout

GET Parameters
Name Mandatory Type Description
gcReference Yes String GiroCheckout transaktion ID
gcMerchantTxId Yes String Merchant transaktion ID
gcBackendTxId Yes String Payment processor transaction ID
gcAmount Yes Integer For currencies with decimals, specify amount in the smallest currency unit, e.g. Cent
gcCurrency Yes String Currency
gcResultPayment Yes Integer Result codes of the SOFORT payment
gcHash Yes String HMAC MD5 hash on all values of the call. See Hash generation