====== Bluecode ======

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

===== Testdata =====
{{page>en:testdata:bluecode&noheader&nofooter}}

===== Transaction types =====
Find detailed information about the [[en:girocheckout:transactiontypes:start|transaction types]]. 

<uml>
left to right direction
skinparam packageStyle rect

rectangle SALE{
 (SALE) --> (REFUND)
}
</uml>

===== 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 ====

<uml>
hide footbox

participant "Customer" as customer
participant "Shop" as shop
participant "GiroCheckout" as girocheckout
participant "Bluecode" as bc

autonumber

customer -> shop: 
shop -> girocheckout: 
girocheckout -> shop:
shop -> bc:
customer -> customer:
bc -> customer:
customer -> bc:
bc -> bc:
bc -> shop:
bc -> girocheckout:
girocheckout -> shop: 
shop -> shop: 
shop -> customer: 


center footer (c)2019 by GiroSolution GmbH
</uml>

  - Customer selects payment method Bluecode
  - Shop initializes Bluecode transaction ([[en:girocheckout:bluecode:start#initializing_a_bluecode_payment|Initialization]])
  - Shop receives response about transaction outcome (transaction ends on error) and sends redirect URL to customer browser
  - Customer browser forwards to the Bluecode payment page, where a QR code is displayed (in Desktop variant)
  - Customer scans QR code with his smartphone (Bluecode App) (in Desktop variant)
  - Bluecode sends message to customer smartphone and waits for confirmation
  - Customer authorizes the transaction on his smartphone
  - Bluecode processes the transaction
  - Customer clicks "Back to shop" ([[en:girocheckout:bluecode:start#redirecting_the_customer_to_the_merchant|Redirect]])
  - Bluecode transmits result to GiroCheckout
  - GiroCheckout notifies shop about transaction outcome ([[en:girocheckout:bluecode:start#notification_about_payment_result|Notification]])
  - Shop processes transaction outcome
  - Shop informs customer about transaction outcome

==== Sale ====
{{page>en:girocheckout:transactiontypes:descriptions#sale.desc&noheader&nofooter}}
<uml>
left to right direction
skinparam packageStyle rect

rectangle SALE{
  (SALE)
}
</uml>

==== 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 |
|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 [[https://en.wikipedia.org/wiki/ISO_4217#Active_codes|ISO 4217]].\\ EUR = Euro |
|purpose        |Yes       |String(37)  |Purpose of the transaction.  This information appears on the settlement sheet. |
|urlRedirect    |Yes       |String      |URL, where the buyer is to be redirected after payment. |
|urlNotify      |Yes       |String      |URL, where the notification has to be sent after payment. |
|hash           |Yes       |String      |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |

== Example ==
{{page>codesamples:bluecode#transactionstart.request&noheader&nofooter}}

==== 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   |[[en:girocheckout:errorcodes|Error Codes]] |
|msg            |Yes       |String    |Additional information in case of error |
|reference      |Optional |String    |Unique GiroCheckout transaction ID |
|redirect       |Optional |String    |Redirect URL that leads the customer to the Bluecode payment page|
^HEADER Parameters^^^^
|hash           |Yes       |String    |HMAC MD5 hash over the complete JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |

== Example in case of success ==
{{page>codesamples:bluecode#transactionstart.response.true&noheader&nofooter}}

== Example in case of failure ==
{{page>codesamples:bluecode#transactionstart.response.false&noheader&nofooter}}


==== 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      | GiroCheckout transaction ID |
|gcMerchantTxId   |Yes       |String      | Merchant transaction ID |
|gcBackendTxId    |Yes       |String      | 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      | Currency of the transaction according to [[https://en.wikipedia.org/wiki/ISO_4217#Active_codes|ISO 4217]].\\ EUR = Euro |
|gcResultPayment  |Yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Result codes]]|
|gcHash           |Yes       |String      | HMAC MD5 hash of the complete JSON string (see [[en:girocheckout:general:start#hash_generation|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      | GiroCheckout transaction ID |
|gcMerchantTxId   |Yes       |String      | Merchant transaction ID |
|gcBackendTxId    |Yes       |String      | 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      | Currency of the transaction according to [[https://en.wikipedia.org/wiki/ISO_4217#Active_codes|ISO 4217]].\\ EUR = Euro |
|gcResultPayment  |Yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Result codes]]|
|gcHash           |Yes       |String      | HMAC MD5 hash of the complete JSON string (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |


===== Other transaction types =====

==== Refund ====
{{page>en:girocheckout:transactiontypes:descriptions#refund.desc&noheader&nofooter}}

=== 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 |
|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 [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]].\\ EUR = Euro |
|reference      |yes       |String      |GiroCheckout transaction ID from a previous transaction, which the capture or refund is for |
|purpose        |optional  |String      |Purpose of the refund. This information is printed on the credit card statement. |
|hash           |yes       |String      |HMAC MD5 hash on the complete call. See [[en:girocheckout:general:start#hash_generation|hash generation]] |

== Example ==
{{page>codesamples:creditcard#capture.request&noheader&nofooter}}

=== 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   |[[en:girocheckout:errorcodes|response code]] |
|msg            |yes       |String    |Additional information about the response code |
|reference      |yes       |String    |Unique GiroCheckout transaction ID |
|merchantTxId   |yes       |String      | Unique transaction id of the merchant |
|backendTxId    |yes       |String      | 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      | Currency |
|resultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result codes]]|
^HEADER parameter^^^^
|hash           |yes       |String    |HMAC MD5 hash on the complete JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |

== Example in case of success ==
{{page>codesamples:creditcard#capture.response.true&noheader&nofooter}}

== Example in case of error ==
{{page>codesamples:creditcard#capture.response.false&noheader&nofooter}}