Table of Contents

Bluecode

You may find further information on the payment method “Bluecode” here: https://www.bluecode.com/.

Testdata

In order to test Bluecode e-commerce payments, you require a smart phone with an installed and activate Bluecode app.

We recommend that you call the following URLs directly on your smart phone:

iOS: https://install.appcenter.ms/orgs/bluecode-organization/apps/at.secure-shopping.bluecode.sandbox-ios/distribution_groups/public
Android: https://install.appcenter.ms/orgs/bluecode-organization/apps/com.spt.bluecode.sandbox-android/distribution_groups/public

Important:

  • After installation of the Bluecode sandbox app, you must define a personal PIN for access to it.
  • Then, please click on “Bankkonto verbinden” (connect bank account) and enter “test” in the bank search field.
  • This will cause the display of an entry “Activate a test user”. Click on it to add a test account.
  • Then please select the first entry “Hypo Tirol”.
  • Next, a Bluecode is displayed for payment.
  • In order to scan a QR code with your phone, tap the QR icon in the top left corner of your app to activate the camera.
  • Once scanned, the payable amount is displayed on your phone. Confirm the payment by swiping as indicated on-screen.

Special note on iOS:
When first installing the sandbox app on iOS devices, it is necessary to establish trust for the business app “bluesource”. Do this by going to “Settings > General > Profiles & Devices” and confirming that you trust this app. Only then the Bluecode app may be used on iOS.

No “real” payments are processed in the Bluecode sandbox app, they are only simulated!

Transaction types

Find detailed information about the transaction types.

SALEREFUND

Initializing a Bluecode payment

After a successful initialization a reference number and a redirect link is transmitted to the merchant. The transmitted link leads to the payment form, to which the customer must be redirected. This may be done via an HTTP redirect hreader, an HTML page with a meta tag or Javascript.

Provided by: GiroCheckout
Called by: Merchant

Workflow

CustomerShopGiroCheckoutBluecode1 2 3 4 5 6 7 8 9 10 11 12 13 (c)2019 by GiroSolution GmbH

  1. Customer selects payment method Bluecode
  2. Shop initializes Bluecode transaction (Initialization)
  3. Shop receives response about transaction outcome (transaction ends on error) and sends redirect URL to customer browser
  4. Customer browser forwards to the Bluecode payment page, where a QR code is displayed (in Desktop variant)
  5. Customer scans QR code with his smartphone (Bluecode App) (in Desktop variant)
  6. Bluecode sends message to customer smartphone and waits for confirmation
  7. Customer authorizes the transaction on his smartphone
  8. Bluecode processes the transaction
  9. Customer clicks “Back to shop” (Redirect)
  10. Bluecode transmits result to GiroCheckout
  11. GiroCheckout notifies shop about transaction outcome (Notification)
  12. Shop processes transaction outcome
  13. Shop informs customer about transaction outcome

Sale

Use sale when the business case is complete, e.g. a shopping cart was offered, ordered and delivered to the customer. The customer's payment method is debited with the amount of the sale.

  • initial Transaction


left to right direction
skinparam packageStyle rect

rectangle SALE{
(SALE)
}

POST Parameters

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Name Mandatory Type Description
merchantId Yes Integer Merchant ID of a Bluecode project
projectId Yes Integer Project ID of a Bluecode project
merchantTxId Yes String(255) Unique merchant transaction ID. 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 of the transaction according to ISO 4217.
EUR = Euro
purpose Yes String(37) Purpose of the transaction. This information appears on the settlement sheet.
urlRedirect Yes String(2048) URL, where the buyer is to be redirected 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=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=1189b707a5eeab6ba79e6dc937abad0d" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Response

The response is a JSON object. The field rc returns an error code. If rc=0 is returned, the transaction was initialized successfully. As a response, you receive a transaction number and the redirectURL to the Bluecode payment page.

Parameters

Name Mandatory Type Description
rc Yes Integer Error Codes
msg Yes String(255) Additional information in case of error
reference Optional String(26) Unique GiroCheckout transaction ID
redirect Optional String(2048) Redirect URL that leads the customer to the Bluecode payment page
HEADER Parameters
hash Yes String(32) HMAC MD5 hash over the complete JSON string. (see api call reply)
Example in case of success

hash : 899f05ca96d469efd99a550c5b29ed01 

{"reference":"e3c0399d-6fc4-4063-8c23-9e9603dce299","redirect":"https:\/\/go.bluecode.mobi\/28\/2\/04\/33\/pay\/ecom4743c66a-9686-471b-b42d-125a1c1e34ec","rc":0,"msg":""}
Example in case of failure

hash : b32ac9a94378b697ede4929bc0c564d2 

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

Notification about payment result

The result of a payment is sent to the URL specified in the urlNotify parameter. This notification serves the purpose of informing the merchant the result of the transaction. This information allows the modification of the order status in his shop.

The result (outcome) of the payment can be found in the field gcResultPayment.

Request

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

GET Parameters

Name Mandatory Type Description
gcReference Yes String(36) GiroCheckout transaction ID
gcMerchantTxId Yes String(255) Merchant transaction ID
gcBackendTxId Yes String(26) Transaction ID of the payment processor
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 of the transaction according to ISO 4217.
EUR = Euro
gcResultPayment Yes Integer Result codes
gcHash Yes String(32) HMAC MD5 hash of the complete JSON string (see hash generation)

Response

One of the following HTTP status codes is expected as response to the GET request:

HTTP Status code Description
200 (OK) Notification was processed correctly.
400 (Bad Request) The merchant didn't process the notification, but does not want to be notified again.
All others Notification not processed. It is repeated for a max. of 10 times until the merchant returns HTTP status 200 or 400.

Redirecting the customer to the merchant

After finishing the payment, the customer may return to the merchant via a link. Currently, the redirect is only donde after the customer clicked the “Return to Shop” button, it 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(36) GiroCheckout transaction ID
gcMerchantTxId Yes String(255) Merchant transaction ID
gcBackendTxId Yes String(26) Transaction ID of the payment processor
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 of the transaction according to ISO 4217.
EUR = Euro
gcResultPayment Yes Integer Result codes
gcHash Yes String(32) HMAC MD5 hash of the complete JSON string (see hash generation)

Other transaction types

Refund

A refund is to be used when a previous payment is to be returned fully or partially to the customer.

  • Condition: may only be applied to the following transaction types:
    • Reservation
    • Reservation/Booking
  • Amount ⇐ Transaction amount of the previous transaction

POST Parameters

URL REFUND: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund

Name Mandatory Type Description
merchantId yes Integer Merchant ID
projectId yes Integer Project ID
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, e.g. Cent, Penny
currency yes String(3) Currency according to ISO 4217.
EUR = Euro
reference yes String(36) GiroCheckout transaction ID from a previous transaction, which the capture or refund is for
purpose optional String(27) Purpose of the refund. This information is printed on the credit card statement.
hash yes String(32) HMAC MD5 hash on the complete call. See hash generation
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/capture

Reply

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialized. The response also includes a transaction id and other information about the transaction.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) Additional information about the response code
reference yes String(36) Unique GiroCheckout transaction ID
merchantTxId yes String(255) Unique transaction id of the merchant
backendTxId yes String(26) Payment processor transaction ID
amount yes Integer If a decimal currency is used, the amount has to be in the smallest unit of value, e.g. Cent, Penny
currency yes String(3) Currency
resultPayment yes Integer Payment result codes
HEADER parameter
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"7f18859d-7246-4181-8fb5-30ce7958f309","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1196307_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}
Example in case of error
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":"5200","rc":0,"msg":"Transaktion nicht akzeptiert"}