====== Direct Debit ======
Information about direct debit payment can be found under https://www.girosolution.de/girocheckout/fuer-haendler/.

A direct debit payment can **only** be processed in **Euros**.

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

===== Workflow =====

The direct debit payment can be processed in two ways: 
  * If the bank account data is known (IBAN or bank account and bank code), a transaction can be processed directly. 
  * Alternatively a payment page can be used.

**Direct debit with payment page**


<uml>
hide footbox

participant "buyer" as customer
participant "merchant" as shop
participant "GiroCheckout" as girocheckout
participant "payment processor" as za

autonumber

customer -> shop: 
shop -> girocheckout: 
girocheckout -> za: 
za -> girocheckout: 
girocheckout -> shop: 
shop -> customer: 
customer -> za:
za -> customer: 
customer -> za
za -> za: 
za -> girocheckout:
girocheckout -> shop
shop -> shop: 
shop -> girocheckout: 
girocheckout -> za: 
za -> shop: 


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


  - Buyer chooses direct debit payment method
  - merchant initialises direct debit transaction ([[en:girocheckout:directdebit:start#initialise_direct_debit_payment|initialising direct debit transaction]])
  - GiroCheckout initialises transaction at direct debit processor
  - direct debit processor submits response to GiroCheckout
  - merchant gets response about initialisation (if an issue occurs the transaction is finished)
  - merchant sends redirect URL to buyer
  - the buyer's browser redirects buyer to the payment form
  - direct debit processor shows payment form
  - buyer authorises payment
  - transaction is beeing processed
  - direct debit processor submits payment result to bank
  - GiroCheckout notifies merchant about the payment result ([[en:girocheckout:directdebit:start#notification_about_the_payment_result|payment result norification]])
  - merchant processes result
  - merchant sends HTTP statuscode to GiroCheckout
  - GiroCheckout sends merchants redirect page to bank
  - buyer clicks "back to the shop" and gets redirected to the merchant ([[en:girocheckout:directdebit:start#redirect_to_the_merchant|buyer redirection]])

**Direct debit without payment page**

<uml>
hide footbox

participant "buyer" as customer
participant "merchant" as shop
participant "GiroCheckout" as girocheckout
participant "bank" as bank

autonumber

customer -> shop: 
shop -> girocheckout: 
girocheckout -> bank: 
bank -> girocheckout:
girocheckout -> shop: 
shop -> customer: 

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

  - buyer choses direct debit payment and fills in his IBAN
  - merchant subits direct debit payent to GiroCheckout ([[en:girocheckout:directdebit:start#direct_debit_without_payment_page|direct debit without payment page]])
  - GiroCheckout submits direct debit payent to the bank
  - bank replies and submits payment result to GiroCheckout
  - GiroCheckout replies merchant
  - merchant informs buyer about the payment result

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

==== Overview =====


As shown in the workflow there are different API calls during a direct debit transaction with payment page.

  - Initialize transaction
  - Request account information from customer
  - Transmit payment information to merchant
  - Payment information and buyer redirection to the merchant (triggered by buyer after payment)

As shown in the workflow there is just one API call during a direct debit transaction without payment page.

  - Process transaction

==== Initialize direct debit payment with payment page ====

After a successful initialization you receive a reference number and an redirect link. The redirect link leads to the payment page. He has to be redirected. This can be achieved by a 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:** merchant

== 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(50)  |purpose |
|type           |optional |String |Transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Immediate sale (default) \\ AUTH = Reservation of amount|
|locale         |optional |String(4)   |language of the payment page \\ de = German (default) \\ en = English \\ es = Spanish \\ fr = French \\ it = Italian \\ 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     |optimized payment page for mobile devices \\ 0 = no (default) \\ 1 = yes |
|mandateReference | optional |String(35)  | mandate reference \\ if nothing is specified, a unique number is generated. The reply includes the mandate reference number. \\
    numbers: 0 – 9  
    characters: A – Z and a – z  
    special characters: & \ / = + , : ; . _ \ - ! ? 
|
|mandateSignedOn | optional |String(10)| date (YYYY-MM-DD), when the SEPA mandate was placed. If no date is specified the current date will be used. |
|mandateReceiverName |optional |String(70)| name of the recipient. If nothing is specified companies name from the master data is used. \\
    numbers: 0 – 9  
    characters: A – Z and a – z  
    special characters: & / = + , : ; . _ - ! ? 
|
|mandateSequence | optional |Integer |Sequence type of the SEPA direct debit. \\ 1 = single payment (default) \\ 2 = first payment of a sequence \\ 3 = recurring payment \\ 4 = last payment of a sequence |
|pkn            |optional |String      |This field is used to initiate a new transaction without the need for repeating the banking data. \\ create = generate new pseudo card number for the used banking data \\ [Pseudo card number] = Card number of the banking data to be used (see [[en:girocheckout:directdebit:start#pseudo_card_number_pkn|pseudo card number]])\\ **This feature requires a separate configuration involving a one-time setup fee.**|
|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:directdebit#transactionstart.request&noheader&nofooter}}


=== Reply ===
The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initiated. 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 |
|mandateReference|optional|String    |mandate reference of the SEPA direct debit |
|redirect       |optional |String    |redirect URL to the payment page|
^HEADER parameter^^^^
|hash           |yes       |String    |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |

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

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


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

The result of an initialized 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 the payment is contained in the field //gcResultPayment//. 

=== Request ===
**URL:** notifyUrl of the prior 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#zahlungsausgang|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 is not done automatically. 

=== Request ===
**URL:** redirectUrl of the prior 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#zahlungsausgang|payment result codes]]|
|gcHash           |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |



==== Direct debit without payment page ====

After a successful initialization you receive a reference number and an redirect link. The redirect link leads to the payment page. He has to be redirected. This can be achieved by a HTTP-Redirect-Header, HTML page with a corresponding Meta-Tag or JavaScript redirect. 

=== Request ===
**URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/payment \\
**provided by:** GiroCheckout \\
**called by:** merchant

== 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(50)  |purpose |
|type           |optional |String |Transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Immediate sale (default) \\ AUTH = Reservation of amount|
|bankcode       |optional |String(8)   |bank code \\ **Mandatory, if no IBAN is set.** |
|bankaccount    |optional |String(10)  |bank account \\ **Mandatory, if no IBAN is set.** |
|iban           |optional       |String(34)      | IBAN of the buyer's bank account **without whitespace** |
|accountHolder  |yes|String(27)      | name of the account holder |
|mandateReference | optional |String(35)  | mandate reference \\ if nothing is specified, a unique number is generated. The reply includes the mandate reference number. \\
    numbers: 0 – 9  
    characters: A – Z and a – z  
    special characters: & \ / = + , : ; . _ - ! ? 
|
|mandateSignedOn | optional |String(10)| date (YYYY-MM-DD), when the SEPA mandate was placed. If no date is specified the current date will be used. |
|mandateReceiverName |optional |String(70)| name of the recipient. If nothing is specified companies name from the master data is used. \\
    numbers: 0 – 9  
    characters: A – Z and a – z  
    special characters: & / = + , : ; . _ - ! ? 
|
|mandateSequence | optional |Integer |Sequence type of the SEPA direct debit. \\ 1 = single payment (default) \\ 2 = first payment of a sequence \\ 3 = recurring payment \\ 4 = last payment of a sequence |
|pkn            |optional |String      |This field is used to initiate a new transaction without the need for repeating the banking data. \\ create = generate new pseudo card number for the used banking data \\ [Pseudo card number] = Card number of the banking data to be used (see [[en:girocheckout:directdebit:start#pseudo_card_number_pkn|pseudo card number]])\\ **This feature requires a separate configuration involving a one-time setup fee.**|
|urlNotify      |optional |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:directdebit#authorize.request&noheader&nofooter}}


=== Reply ===
The reply includes a JSON encoded string. The field rc contains the response code. The response also includes a transaction id and the payment's result.

== 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 |
|backendTxId    |optional |String    |payment processor transaction id |
|mandateReference |optional |String  |mandate reference of the SEPA direct debit |
|resultPayment  |optional |Integer   |[[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]] |
^HEADER parameter^^^^
|hash           |yes       |String    |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |

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

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

===== Pseudo card number (PKN) =====
<WRAP center round important 60%>
A separate configuration is required for this feature and a one-time setup fee will apply.
</WRAP>
A pseudo card number is a reference to bank data used by a buyer (account owner, account number, bank code or IBAN). This reference allows the merchant to offer previously used banking data for reuse by the buyer. If the PKN number is sent in the initialization request of a direct debit transaction, this banking data is pre-filled in the payment form or the payment carried out directly (depending on the desired mode, with or without payment page). 

==== Query pseudo card number information ====
This function provides PKN information. It returns in its result a PKN as well as the stored baking data (account owner, account number, bank code or IBAN), which has been used in a previous transaction.

=== Request ===
**URL:** https://payment.girosolution.de/girocheckout/api/v2/directdebit/pkninfo \\
**Provided by:** GiroCheckout \\
**Called by:** Merchant

== POST Parameters ==
^Name           ^Mandatory  ^Type      ^Description   ^
|merchantId     |yes       |Integer   |Merchant ID of a direct debit project |
|projectId      |yes       |Integer   |Project ID of a direct debit project |
|reference      |optional |String    |unique GiroCheckout transaction ID |
^HEADER parameters^^^^
|hash           |yes       |String    |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |

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

=== Response ===
The response is a JSON object. The field rc returns an error code. If rc = 0, the request was successful. The response contains the PKN number, the account owner and the banking data.

== Parameters ==
^Name           ^Mandatory  ^Type      ^Description   ^
|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] |
|msg            |yes       |String    |additional information about the response code |
|pkn            |yes       |String    |Pseudo card number |
|holder         |yes       |String    |Account owner (holder) |
|bankcode       |yes       |String    |Bank code (German BLZ) |
|bankaccount    |yes       |String    |Account number |
|iban           |yes       |String    |IBAN |
^HEADER Parameters^^^^
|hash           |yes       |String    |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |

== Example successful request ==
{{page>codesamples:creditcard#pkninfo.response.true&noheader&nofooter}}

== Example failed request ==
{{page>codesamples:creditcard#pkninfo.response.false&noheader&nofooter}}

===== Further transaction types =====
These transactions reference a previous transaction. The transaction is based on a server-to-server communication and requires no customer interaction (data input).

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

==== Workflow ====

<uml>
hide footbox

participant "Shop" as shop
participant "GiroCheckout" as girocheckout
participant "Abwickler" as cc

autonumber

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

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

  - Shop sends referencing transaction
  - GiroCheckout redirects transaction to payment processor
  - Processor transmits result to GiroCheckout
  - Shop receives response about transaction outcome ([[en:girocheckout:directdebit:start#notification_of_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 Parameter ===
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, eg. Cent, Penny |
|currency       |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        |optional  |String      |Purpose of the refund, printed on the bank statement |
|reference      |yes       |String      |GiroCheckout transaction ID, for which a capture or refund is to be done |
|hash           |yes       |String      |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |

== Example ==
{{page>codesamples:directdebit#refund.request&noheader&nofooter}}

=== Response ===
The response is a JSON object. The field rc returns the error code. If rc = 0, the transaction was successfully initialized. As a response, you receive a transaction number and the redirection URL to the payment form.

== 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 |
|backendTxId    |yes       |String    |payment processor transaction id |
|amount         |yes       |String    |the amount of the (partial) transaction, for currencies with decimals use the smallest payment unit, such as Cents or Pennies |
|currency       |yes       |String    | Currency |
|resultPayment  |yes       |Integer   |[[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]] |
^HEADER parameter^^^^
|hash           |yes       |String    |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |

== Example of successful transaction ==
{{page>codesamples:directdebit#refund.response.true&noheader&nofooter}}

== Example of failed transaction ==
{{page>codesamples:directdebit#refund.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 direct debit project |
|projectId      |Yes       |Integer     |Project ID of a direct debit 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:directdebit#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:directdebit#void.response.true&noheader&nofooter}}

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