====== Paydirekt ======
Please find general information on Paydirekt at https://www.girosolution.de/girocheckout.

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

===== Transaction types =====
Detailed information regarding [[en:girocheckout:transactiontypes:start|Transaction types]]. 

<uml>
left to right direction
skinparam packageStyle rect

rectangle SALE{
  (SALE) --> (REFUND)
  (REFUND)
}
rectangle AUTH {
  (AUTH) --> (CAPTURE )
  (CAPTURE ) --> (REFUND )

}
</uml>

===== Initialization of a Paydirekt payment =====
A successful initialization generates a reference number and a redirect link, which are both returned to the merchant. The redirect link will lead the customer to the payment form, so the merchant must ensure the proper redirection. This may be accomplished through an HTTP redirect header, an HTML page with a corresponding meta tag or via Javascript.

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

==== Workflow ====

<uml>
hide footbox

participant "Customer" as customer
participant "Shop" as shop
participant "GiroCheckout" as girocheckout
participant "Paydirekt" as pd

autonumber

customer -> shop: 
shop -> girocheckout: 
girocheckout -> pd: 
pd -> girocheckout: 
girocheckout -> shop: 
shop -> customer: 
customer -> pd:
pd -> customer: 
customer -> pd:
pd -> pd: 
pd -> girocheckout:
girocheckout -> shop
shop -> shop: 
shop -> girocheckout: 
girocheckout -> pd: 
pd -> shop: 


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

  - Customer chooses payment method Paydirekt
  - Shop initiates Paydirekt transaction ([[en:girocheckout:paydirekt:start#initialization_of_a_paydirekt_payment|Initialization]])
  - GiroCheckout initializes transaction at Paydirekt 
  - Paydirekt sends result to GiroCheckout
  - Shop receives feedback on initialization result (transaction ends on error)
  - Shop sends redirect URL to customer browser 
  - Customer browser redirects to Paydirekt
  - Paydirekt display payment form
  - Customer authorizes transaction
  - Paydirekt carries out the transaction
  - Paydirekt transmits result to GiroCheckout
  - GiroCheckout informs Shop about transaction result ([[girocheckout:paydirekt:start#notification_of_payment_result|Notification]])
  - Shop processes transaction result
  - Shop sends HTTP status code to GiroCheckout
  - GiroCheckout sends merchant return address to Paydirekt 
  - Customer clicks "Back to Shop" ([[girocheckout:paydirekt:start#returning_the_customer_to_the_merchant|Return]])


==== Reservation (AUTH) ====
{{page>en:girocheckout:transactiontypes:descriptions#auth.desc&noheader&nofooter}}
<uml>
left to right direction
skinparam packageStyle rect

rectangle AUTH {
  (AUTH) --> (capture)
  (AUTH) --> (refund)
}
</uml>
==== Reservation/Booking (SALE) ====
{{page>en:girocheckout:transactiontypes:descriptions#sale.desc&noheader&nofooter}}
<uml>
left to right direction
skinparam packageStyle rect

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

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

^Name           ^Mandatory  ^^Type        ^Description   ^
^:::           ^AUTH ^SALE  ^:::        ^::: ^
|merchantId     |Yes  |Yes       |Integer     |Merchant ID of a Paydirekt project |
|projectId      |Yes  |Yes       |Integer     |Project ID of a Paydirekt project |
|merchantTxId   |Yes  |Yes       |String(255) |The merchant's unique transaction ID |
|amount         |Yes  |Yes       |Integer     |For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |
|currency       |Yes  |Yes       |String(3)   |Currency of the transaction according to [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]].\\ EUR = Euro |
|purpose        |Yes  |Yes       |String(37)  |Purpose of the transaction. This information appears on the accounting reports. |
|type           |Yes  |Optional |String      |Transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Sale is booked immediately (default) \\ AUTH = Reservation of the amount |
|shoppingCartType |Optional |Optional |String    |Type of the shopping cart. The following values are permitted: \\ PHYSICAL = All items in the cart are physical (this is the default value if the parameter is not specified), \\ DIGITAL = All items in the cart are digital (so they don't require a dispatch service), \\ MIXED = The cart contains both physical and digital items, \\ ANONYMOUS_DONATION = This is an anonymous donation (no adress data required), \\ AUTHORITIES_PAYMENT = This is a payment operation to the authorities (e-Government, no address data required) |
|customerId           |Optional  |Optional  |String(20)    | Customer number , max. length: 20|
|shippingAmount       |Optional  |Optional  |Integer   | Shipping costs. For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |
|shippingAddresseFirstName |(see descr.)  |(see descr.) |String    | First name of the receiver, **mandatory** for cart types MIXED, PHYSICAL and DIGITAL, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. |
|shippingAddresseLastName  |(see descr.)  |(see descr.) |String    | Last name of the receiver, **mandatory** for cart types MIXED, PHYSICAL and DIGITAL, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. |
|shippingCompany      |Optional |Optional  |String    | Company name |
|shippingAdditionalAddressInformation |Optional |Optional |String | Additional address info |
|shippingStreet       |Optional |Optional |String    | Street of the receiver's address |
|shippingStreetNumber |Optional |Optional |String    | Street number of the receiver's address |
|shippingZipCode      |(see descr.)  |(see descr.)  |String    | Zip code of the receiver's address. This field is mandatory for carts of type PHYSICAL and MIXED, optional for the others. |
|shippingCity         |(see descr.)  |(see descr.)  |String    | City of the receiver's address. This field is mandatory for carts of type PHYSICAL and MIXED, optional for the others. |
|shippingCountry      |(see descr.)  |(see descr.)  |String(2) | Country code (ISO 3166-1). This field is mandatory for carts of type PHYSICAL and MIXED, optional for the others. |
|shippingEmail        |(see descr.) |(see descr.)        |String    | Email address of the buyer. This field is mandatory for carts of type DIGITAL only, optional for the others. |
|merchantReconciliationReferenceNumber        | |Optional         |String(30)    | Additional information for the payment reconciliation that is shown in the purpose on bank statements (only for type=SALE) |
|orderAmount    |Optional  |Optional       |Integer    | Amount of the order (excluding shipping costs), for currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |
|orderId        |Yes  |Yes       |String     | Order number, allowed characters: A-Z a-z 0-9 + ? / - : ( ) . , ' (blank), max. length: 20 |
|cart           |Optional  |Optional       |JSON String | All elements contained in the shopping cart in the following format: [[en:girocheckout:paydirekt:start#cart|Cart]] |
|invoiceId      |Optional  |Optional  |String    | Invoice number |
|customerMail   |Optional  |Optional  |String     | Customer email address |
|minimumAge     |Optional |Optional|Integer     | Minimum customer age required for the transaction, if any |
|urlRedirect    |Yes  |Yes       |String      |URL where the customer is to be redirected after the payment. |
|urlNotify      |Yes  |Yes       |String      |URL where the payment result should be informed (notify). |
|hash           |Yes  |Yes       |String      |HMAC MD5 hash on all the valus of the request. See  [[en:girocheckout:general:start#hash_generieren|Generate hash]] |

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


=== Cart ===
JSON Array with item objects:

^Name           ^Mandatory        ^Type        ^Description   ^
|name           |Yes            |String      | Product (article) name |
|ean            |Optional       |String      | International article number (EAN or GTIN) |
|quantity       |Yes            |Dezimal     | Article quantity (integer) |
|grossAmount    |Optional       |Integer     | Gross amount of the article (price of each unit, if more than one), Bruttobetrag des Artikels, for currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |

== Example ==
<code>
[ {
    "name" : "Kids bike",
    "ean" : "800001303",
    "quantity" : 3,
    "grossAmount" : 2599
  }, {
    "name" : "Helmet",
    "quantity" : 1,
    "grossAmount" : 1853
  } ]
</code>

==== Response ====
The response is a JSON object. The field rc returns an error code. If rc = 0 is returned, the transaction was successfully initialized. You will receive a transaction number and the redirect URL leading to the Paydirekt payment confirmation page in the response.

=== 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    |URL to redirect customer to Paydirekt|
^HEADER Parameters^^^^
|hash           |Yes       |String    |HMAC MD5 Hash of all values of the response. See [[en:girocheckout:general:start#api_call_reply_to_the_merchant|Response hash]] |

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

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


==== Notification of payment result ====

The result of a payment is transmitted to the URL specified in the //urlNotify// parameter. This notification serves the purpose of informing the merchant about the outcome of the transaction. This enables the merchant to update his transaction status.

The result of the transaction's payment is contained 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 payment provider |
|gcAmount         |Yes       |Integer     | For currencies that use decimals, specify amount in the smallest unit, 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 of all the values of the request. See [[en:girocheckout:general:start#hash_generation|Generate hash]] |

=== 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 for a maximum of 10 times every 30 minutes, until the merchant returns either HTTP 200 or 400. |

==== Returning the customer to the merchant ====
Once the payment is finished, the customer may return to the merchant via a link. A redirection does not take place until the customer has clicked the "Cancel" or "Return to Shop" button.  This redirect 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 provider |
|gcAmount         |Yes       |Integer     | For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |
|gcCurrency       |Yes       |String      | Currency |
|gcResultPayment  |Yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result]]|
|gcHash           |Yes       |String      | HMAC MD5 hash of all the values in the request. See [[en:girocheckout:general:start#hash_generation|Generate hash]] |


===== Other transaction types =====
These transactions refer to a previous transaction. They are based on a server to server communication and require no customer intervention (in terms if data entry).

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

==== Workflow ====

<uml>
hide footbox

participant "Shop" as shop
participant "GiroCheckout" as girocheckout
participant "Paydirekt" as pd

autonumber

shop -> girocheckout: 
girocheckout -> pd: 
pd -> girocheckout: 
girocheckout -> shop: 

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

  - Shop sends referencing transaction
  - GiroCheckout routes transaction to Paydirekt
  - Paydirekt transmits result to GiroCheckout
  - Shop receives reply regarding transaction result ([[en:girocheckout:paydirekt:start#notification_of_payment_result|Notification]])

==== Booking (CAPTURE) ====
{{page>en:girocheckout:transactiontypes:descriptions#capture.desc&noheader&nofooter}}

<uml>
left to right direction
skinparam packageStyle rect

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

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

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

=== POST Parameters ===
CAPTURE URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture \\
REFUND URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund \\

^Name           ^Mandatory^^Type        ^Description   ^
^::: ^ CAPTURE ^ REFUND ^::: ^::: ^
|merchantId     |Yes       |Yes |Integer     |Merchant ID of a Paydirekt project |
|projectId      |Yes       |Yes |Integer     |Project ID of a Paydirekt project |
|merchantTxId   |Yes       |Yes |String(255) |Unique merchant transaction ID |
|amount         |Yes       |Yes |Integer     |Full or partial amount. For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |
|currency       |Yes       |Yes |String(3)   |Transaction currency, see [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]].\\ EUR = Euro |
|purpose        |Yes       |Yes |String(27)  |Transaction purpose. This information is displayed on the accounting reports. |
|reference      |Yes  |Yes |String      | GiroCheckout transaction ID of the underlying AUTH transaction. |
|merchantReconciliationReferenceNumber   |Optional  |Optional         |String(30)    | Additional information for the payment reconciliation that is shown in the purpose on bank statements. |
|final   |Optional  | |Boolean | CAPTURE ONLY. Last CAPTURE for a reservation. After this, no further CAPTURE may be done on the referenced reservation. |
|hash           |Yes       |Yes |String      |HMAC MD5 hash of all the values in the call. See [[en:girocheckout:general:start#hash_generation|Generate hash]] |

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

=== Response ===
The response is a JSON object. The field resultPayment returns an error code. If resultPayment = 4000 is returned, the transaction was carried out successfully. You receive a transaction number in the reply.

== Parameters ==
^Name             ^Mandatory  ^Type        ^Description   ^
|reference      |Yes       |String      | GiroCheckout transaction ID |
|merchantTxId   |Yes       |String      | Merchant transaction ID |
|backendTxId    |Yes       |String      | Transaction ID of the payment provider |
|amount         |Yes       |Integer     | For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny |
|currency       |Yes       |String      | Currency |
|resultPayment  |Yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result]]|
|hash           |Yes       |String      | HMAC MD5 hash of all the values of the call. Siehe  [[en:girocheckout:general:start#hash_generation|Generate hash]] |

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

== Example of failure ==
{{page>codesamples:paydirekt#capture.response.false&noheader&nofooter}}

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

=== POST Parameters ===
URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void

^Name           ^Mandatory  ^Type      ^Description   ^
|merchantId     |Yes       |Integer     |Merchant ID of a paydirekt project |
|projectId      |Yes       |Integer     |Project ID of a paydirekt project |
|merchantTxId   |Yes       |String(255) |Unique transaction ID of the merchant |
|reference      |Yes       |String      |GiroCheckout transaction ID that is to be voided |
|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 ==
{{page>codesamples:paydirekt#void.request&noheader&nofooter}}

=== Reply ===
The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the call was successful. The response includes a transaction number and other information.

== 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 |
|referenceParent      |yes       |String      | GiroCheckout transaction ID of the original base transaction |
|merchantTxId   |yes       |String      | Unique transaction id of the merchant |
|backendTxId    |yes       |String      | Payment processor transaction ID |
|amount         |yes       |Integer     | Voided amount, 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:paydirekt#void.response.true&noheader&nofooter}}

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