User Tools

Site Tools


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

iDEAL

Test data

form value
issuer RABOBANK

transaction result

result code answer description
4000 successful transaction After submission of the form by using the data above there can be created a successful transaction.
unsuccessful transaction not supported

workflow

buyermerchantGiroCheckoutiDEALonline banking1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 (c)2013 by GiroSolution AG

  1. buyer chooses iDEAL payment method
  2. merchant requests the available banks (bank request)
  3. merchant gets a reply of all issuer banks, that support iDEAL
  4. buyer selects Bank and merchant initialises iDEAL payment (initialise iDEAL payment)
  5. GiroCheckout initialises transaction at iDEAL
  6. iDEAL submits response to GiroCheckout
  7. merchant gets response about initialisation (if an issue occurs the transaction is finished)
  8. merchant sends redirect URL to buyer
  9. the buyer's browser redirects buyer to his online banking account
  10. bank shows login page
  11. buyer authorises payment
  12. bank processes payment
  13. bank submits payment result to iDEAL
  14. iDEAL submits result to GiroCheckout
  15. GiroCheckout notifies merchant about the transaction result (payment result notification)
  16. merchant processes result
  17. merchant sends HTTP Statuscode to GiroCheckout
  18. GiroCheckout sends merchants redirect page to iDEAL
  19. buyer clicks “Zurück zum Shop” and gets redirected to the merchant (buyer redirection)

API functions

overview

As shown in the workflow there are different API calls during an iDEAL transaction.

  1. iDEAL issuer bank request
  2. initialise transaction
  3. payment result notification to merchant
  4. buyer redirection to the merchant (triggered by buyer)

iDEAL issuer bank request

Returns a list which contains all supported iDEAL issuer banks. The buyer has to choose his one.

URL: https://payment.girosolution.de/girocheckout/api/v2/ideal/issuer
provided by: GiroSolution AG
called by: Händler

POST parameter
name mandatory type description
merchantId yes Integer Merchant ID
projectId yes Integer Project ID
hash yes String(32)HMAC MD5 hash (see hash generation)
example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "hash=02f123fdb8b2056596abc0e6ebb1a8c3" \
     https://payment.girosolution.de/girocheckout/api/v2/ideal/issuer

reply

The reply contains an encoded JSON string. An response code is submitted in the field rc. If the response contains rc = 0, the request was successful.

JSON parameter
name mandatory type description
rc yes Integer error codes
msg yes String(255) additional informationen about the response code
issuer optional Mixed list of all supported issuer banks
Beispiel

hash : eef32d3cd0f91bf9328825da6b8997ce

{"issuer":{"NLRABO2U152":"Issuer Simulation","INGBNL2A":"Issuer Simulation V3 - ING","RABONL2U":"Issuer Simulation V3 - RABO"},"rc":0,"msg":""}

Initialize iDEAL payment

After a successful initialization you receive a reference number and a redirect link. The redirect link leads to the online banking account of the buyer's bank. He has to be redirected to his bank. This can be achieved by an 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: Händler

POST parameter
name mandatory type description
merchantId yes Integer merchant ID of an iDEAL project
projectId yes integer project ID of an iDEAL project
merchantTxId yes String(255) unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
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
issuer optional String(20) iDEAL Issuer Bank. If not given, redirects to bank selection page prior to payment.
urlRedirect yes String(2048) URL, where the buyer has to be sent after payment
urlNotify yes String(2048) URL, where the notification has to be sent after payment
kassenzeichen optional String(255) Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there. Characters must comply with the UTF-8 character set.
hash yes String(32) 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 "issuer=INGBNL2A" \
     -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \
     -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \
     -d "hash=256b7bb16edbc76871c830d0d623c303" \
     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 online banking account of the buyer's bank.

Parameter
name mandatory type description
rc yes Integer response code
msg yes String(255) additional information about the response code
reference optional String(36) unique GiroCheckout transaction ID
redirect optional String(2048) redirect URL to the online banking account
HEADER parameter
hash yes String(32) HMAC MD5 hash overall the JSON string. (see api call reply)
example in case of success

hash : 17790db9c9745b94e1b8db1b22cc7876

{"reference":"c6edadaa-b507-49f1-a548-013675fb5c83","redirect":"http://testnl.paydutch.nl/WeDeal/start.aspx?ID=9c55b84d-3c1f-4c9a-86e1-322318e282cd","rc":"0","msg":""}
example in case of error

hash : 98d9d8b133acf97eb92601fa72d804a0

 {"reference":"f84e606f-817d-439f-ada1-d37e85cb6314","redirect":"","rc":"5100","msg":""}

notification about the payment result

The result of a initialised transaction will be submitted to the prior in the urlNotify parameter specified URL. This notification should be used to update the payment status in the merchant's system. The result of an iDEAL payment is contained in the field gcResultPayment.

Due to the internal iDEAL 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(36) unique GiroCheckout transaction ID
gcMerchantTxId yes String(255) merchant transaction ID
gcBackendTxId yes String(8) 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(3) currency
gcResultPayment yes Integer payment result codes
gcHash yes String(32) 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(36) unique GiroCheckout transaction ID
gcMerchantTxId yes String(255) merchant transaction ID
gcBackendTxId yes String(8) 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(3) currency
gcResultPayment yes Integer payment result codes
gcHash yes String(32) HMAC MD5 hash (see hash generation)

Retrieve sender information

This service allows the retrieval of the information associated to the sender of a completed transaction. As a response to the given reference number, the account holder, IBAN and BIC of the customer are returned. This information may be used for a refund to the original payer.

API call

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

POST Parameters
Name Mandatory Type Description
merchantId Yes Integer merchant ID of a iDEAL project
projectId Yes Integer project ID of a iDEAL project
reference Yes String(36)GiroCheckout transaction ID
hash Yes String(32)HMAC MD5 hash of the full JSON string. (see api call reply)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "reference=9ce6c641-4082-4f75-ae54-333309febcc5" \
     -d "hash=246d1fa2ed97ecff895de974c560f9ec" \
     https://payment.girosolution.de/girocheckout/api/v2/ideal/senderinfo

Response

The response is a JSON object. The rc field returns an error code. If rc = 0 is returned, the corresponding fields contain the sender information.

JSON Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) additional information about the response code in case of error
accountholder Optional String(255) Account holder of the sender account
iban Optional String(36) IBAN of the sender account
bic Optional String(11) BIC of the sender account
HEADER parameter
hash yes String(32) HMAC MD5 hash of the full JSON string. (see api call reply)
Example in case of success

hash : cde71b6b98e8dae709fdc1e17aef885f

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
Example in case of error

hash : f1d186103b8c4cb59c54ae7b987a9d4c

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
en/girocheckout/ideal/start.txt · Last modified: 2023/05/07 08:09

Page Tools