====== Maestro ======
Information about Maestro card payments can be found under https://www.girosolution.de/girocheckout/ (sorry, German only).

===== Test data =====
{{page>en:testdata:maestro&noheader&nofooter}}

===== Transaction types =====
Detailed information on the [[en:girocheckout:transactiontypes:start|transaction types]]. 

==== Reservation (AUTH) ====
{{page>en:girocheckout:transactiontypes:descriptions#auth.desc&noheader&nofooter}}

<uml>
left to right direction
skinparam packageStyle rect

rectangle AUTH {
  (AUTH) --> (CAPTURE)
  (AUTH) --> (VOID )
  (CAPTURE) --> (VOID )
  (CAPTURE) --> (REFUND )
  (REFUND ) --> (VOID )
}
</uml>

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

<uml>
left to right direction
skinparam packageStyle rect

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

===== Initialize Maestro payment =====

After a successful initialization the merchant receives a reference number and a redirect link. The redirect link leads to the payment page. The customer (buyer) must be redirected to this link. This can be achieved by an HTTP redirect header, an HTML page with a corresponding meta tag or a JavaScript redirect. 

**Provided by:** GiroCheckout \\
**Called by:** merchant

===== Workflow =====

<uml>
hide footbox

participant "Customer" as customer
participant "Shop" as shop
participant "GiroCheckout" as girocheckout
participant "Card Processor" as cc

autonumber

customer -> shop: 
shop -> girocheckout: 
girocheckout -> cc: 
cc -> girocheckout: 
girocheckout -> shop: 
shop -> customer: 
customer -> cc:
cc -> customer: 
customer -> cc:
cc -> cc: 
cc -> girocheckout:
girocheckout -> shop
shop -> shop: 
shop -> girocheckout: 
girocheckout -> cc: 
cc -> shop: 


center footer (c)2017 by GiroSolution AG
</uml>

  - Buyer selects payment type "Maestro"
  - Shop initializes credit card transaction ([[en:girocheckout:maestro:start#reservation_sale|Initialization]])
  - GiroCheckout initializes transaction at card processor
  - Card processor transmits result to GiroCheckout
  - Shop receives response about transaction outcome (transaction ends in case of error)
  - Shop sends redirect URL to customer browser
  - Customer browser redirects to card processor
  - Card processor displays payment form
  - Customer authorizes transaction
  - Card processor carries out transaction
  - Card processor transmits result to GiroCheckout
  - GiroCheckout notifies Shop about transaction outcome ([[en:girocheckout:maestro:start#notification_about_the_payment_result|Notification]])
  - Shop processes transaction outcome
  - Shop sends HTTP status code to GiroCheckout
  - GiroCheckout sends merchant redirect (return to merchant page) to card processor
  - Customer clicks "Back to shop" ([[en:girocheckout:maestro:start#redirection_of_the_customer_to_merchant|Return]])

===== API functions =====

==== Overview =====

As shown in the workflow, different API calls are involved in a Maestro card transaction. During the payment process a 3D-Secure check is usually applied as well, but this depends solely on the card issuing institute and does not affect merchant or PSP in any way.

  - Initialize transaction
  - 3D-Secure check (optional)
  - Payment result notification to merchant
  - Buyer redirection to the merchant (triggered by buyer)

==== Reservation/Sale ====

=== POST 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 |
|type           |optional  |String(4)   |transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Immediate booking (default) \\ AUTH = Reservation of amount|
|locale         |optional |String(4)   |language of the credit card payment page \\ de = German (default) \\ en = English \\ es = Spanish \\ fr = French \\ it = Italian \\ ja = Japanese \\ pt = Portuguese \\ nl = Dutch \\ cs = Czech \\ sv = Swedish \\ da = Danish \\ pl = Polish \\ spde = German donation \\ spen = English donation \\ de_DE_stadtn = German communes |
|mobile         |optional |Boolean     |optimised payment page for mobile devices \\ 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 [[en:girocheckout:general:start#hash_generation|hash generation]]) |

== Example ==
{{page>codesamples:maestro#transactionstart.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 a redirect URL to the payment page.

== Parameters ==
^Name           ^Mandatory  ^Type      ^Description   ^
|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|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|
^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:maestro#transactionstart.response.true&noheader&nofooter}}

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

==== Notification about the payment result ====

The result of an initialized transaction will be submitted to the merchant through URL specified in the //urlNotify// parameter. This notification should be used to update the order status in the merchant's system.

The result of the payment is contained in the field //gcResultPayment//. 

=== Request ===
**URL:** notifyUrl of the previous init transaction call \\
**Provided by:** Merchant \\
**Called by:** GiroCheckout

== GET parameters ==
^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  |yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result codes]]|
|gcHash           |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|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 only happens once the customer clicks the "cancel" or "return to shop" button and is not done automatically. 

=== Request ===
**URL:** redirectUrl of the previous init transaction call \\
**Provided by:** Merchant \\
**Called by:** GiroCheckout

== GET parameters ==
^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, e.g. Cent, Penny |
|gcCurrency       |yes       |String      | Currency |
|gcResultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result codes]]|
|gcHash           |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |


===== Other transaction types =====
These transactions reference a previous transaction.  They are based on a server to server communication and require no customer interaction (data entry).

**Provided by:** GiroCheckout \\
**Called by:** Merchant \\

==== Workflow ====

<uml>
hide footbox

participant "Shop" as shop
participant "GiroCheckout" as girocheckout
participant "Card Processor" as cc

autonumber

shop -> girocheckout: 
girocheckout -> cc: 
cc -> girocheckout: 
girocheckout -> shop: 

center footer (c)2017 by GiroSolution AG
</uml>

  - Shop sends reference to previous Maestro transaction
  - GiroCheckout sends transaction to card processor
  - Card processor transmits result to GiroCheckout
  - Shop receives reply on transaction outcome ([[en:girocheckout:maestro:start#notification_about_the_payment_result|Notification]])

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

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

=== POST Parameters ===
URL CAPTURE: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture \\
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 |
|purpose        |optional  |String(27)  |Refund purpose that is printed on the card statement |
|reference      |yes       |String      |GiroCheckout transaction ID from a previous transaction, which the capture or refund is for |
|hash           |yes       |String      |HMAC MD5 hash on the complete call. See [[en:girocheckout:general:start#hash_generation|hash generation]] |

== Example ==
{{page>codesamples:maestro#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:maestro#transactionstart.response.true&noheader&nofooter}}

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