User Tools

Site Tools


en:girocheckout:giropay:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
en:girocheckout:giropay:start [2019/06/19 18:43]
michaelheumann
en:girocheckout:giropay:start [2024/03/13 20:53] (current)
michaelheumann
Line 1: Line 1:
-====== giropay / giropay-ID ====== +====== giropay ======
-Information about giropay can be found under [[https://www.girosolution.de/girocheckout/fuer-haendler/|https://www.girosolution.de/girocheckout/fuer-haendler/]].+
  
 **giropay can only process EURO payments.** **giropay can only process EURO payments.**
 + 
  
-===== Test Data ===== +<WRAP center round info 70%> 
-{{page>en:testdata:giropay&noheader&nofooter}}+**Important information** \\ 
 +During the coming months, we will be gradually ending our support for the existing giropay API (see [[/en:girocheckout:giropay-legacy:start|legacy giropay documentation]]). After that, the ONLY valid API will be the one documented here. While planning your transition, please take into consideration our [[/en:girocheckout:giropay-overview:start#migration_guide|migration guide]] on our giropay overview web site. There you will also find a [[/en:girocheckout:giropay-overview:start#comparison_old_and_new_api|comparison of the old and new API]]. 
 +</WRAP> 
 + 
 + 
 +<WRAP center round info 70%> 
 +**API change** \\ 
 +The following change is being made to the API in the following days: \\ 
 +The parameter merchantReconciliationReferenceNumber is replaced by merchantOrderReferenceNumber, which will continue to be optional but allows only 20 characters.  Please also have a look a the allowed characters that are specified below. 
 +</WRAP> 
 + 
 + 
 +===== Test data giropay ===== 
 +{{page>en:testdata:giropaypd&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>
  
 ===== Workflow ===== ===== Workflow =====
Line 21: Line 52:
  
 buyer -> shop:  buyer -> shop: 
-shop -> girocheckout:  
-girocheckout -> shop:  
 shop -> girocheckout: shop -> girocheckout:
 girocheckout -> giropay:  girocheckout -> giropay: 
Line 28: Line 57:
 girocheckout -> shop:  girocheckout -> shop: 
 shop -> buyer:  shop -> buyer: 
-buyer -> bank:+buyer -> giropay: 
 +giropay -> bank:
 bank -> buyer:  bank -> buyer: 
 buyer -> bank: buyer -> bank:
Line 40: Line 70:
 giropay -> shop:  giropay -> shop: 
  
-center footer (c)2016 by GiroSolution AG+center footer (c)2021 by GiroSolution AG
 </uml> </uml>
  
-  - buyer/ customer chooses giropay/ giropay-ID and enters his bank's BIC +  - buyer/ customer chooses giropay/ giropay-ID
-  - merchant checks the bankstatus ([[en:girocheckout:giropay:start#check_bankstatus|check bankstatus]]) +
-  - merchant receives a reply, if bank supports giropay/giropay-ID+
   - merchant initialises giropay/giropay-ID request ([[en:girocheckout:giropay:start#initialise_giropay_payment|initialise giropay payment]])   - merchant initialises giropay/giropay-ID request ([[en:girocheckout:giropay:start#initialise_giropay_payment|initialise giropay payment]])
   - GiroCheckout initialises request at giropay   - GiroCheckout initialises request at giropay
Line 51: Line 79:
   - merchant gets response about initialisation (if an issue occurs the transaction is finished)   - merchant gets response about initialisation (if an issue occurs the transaction is finished)
   - merchant sends redirect URL to buyer/ customer   - merchant sends redirect URL to buyer/ customer
-  - the buyer's/ customer's browser redirects to buyer's/ customer's online banking account+  - the buyer's/ customer's browser redirects to giropay where the bank is selected (optional, only if bank is not already stored in browser) 
 +  - giropay redirects to the customer's online banking
   - bank shows login page   - bank shows login page
   - buyer/ customer authorises giropay payment/ giropay-ID   - buyer/ customer authorises giropay payment/ giropay-ID
Line 63: Line 92:
   - buyer/customer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:giropay:start#redirection_of_the_customer_to_merchant|buyer redirection]])   - buyer/customer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:giropay:start#redirection_of_the_customer_to_merchant|buyer redirection]])
  
 +==== 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>
 ===== API functions ===== ===== API functions =====
  
 ==== Overview ===== ==== Overview =====
  
-As shown in the workflow there are different API calls during a giropay transaction or giropay-ID verification. A combinaion of giropay and giropay-ID is also possible.+As shown in the workflow there are different API calls during a giropay transaction.
  
-  - check bankstatus 
   - initialise transaction   - initialise transaction
   - payment result notification to merchant    - payment result notification to merchant 
-  - buyer redirection to the merchant (triggered by buyer)+  - buyer redirection to the merchant (triggered by buyer after the payment or automatically after a few seconds)
  
- 
-==== Check bankstatus ==== 
-This API call checks if a bank supports the giropay payment method or giropay-ID verification. Therefore the BIC of the buyer's account has to be submitted. The response shows if the bank provides giropay or giropay-ID. It is recommended to do this prior to an initial payment, to make sure that the buyer's bank supports giropay. 
- 
-=== API call === 
-**URL:** https://payment.girosolution.de/girocheckout/api/v2/giropay/bankstatus \\ 
-**provided by:** GiroCheckout \\ 
-**called by:** merchant 
- 
-== POST parameter == 
-^parameter      ^mandatory  ^type      ^description   ^ 
-|merchantId     |yes       |Integer   |Merchant ID of a giropay, giropay-ID or giropay-ID + giropay project | 
-|projectId      |yes       |Integer   |Project ID of a giropay, giropay-ID or giropay-ID + giropay project | 
-|bic            |yes       |String(11)|the buyer's bank account BIC (8 or 11-digits), which schould be checked (determined by [[en:tools:bankstatus_widget|Bankstatus Widget]])| 
-|hash           |yes       |String(32)|HMAC MD5 hash over all API call params (see [[en:girocheckout:general:start#hash generation|hash generation]])| 
- 
-== Example == 
-{{page>codesamples:giropay#bankstatus.request&noheader&nofooter}} 
- 
-=== Reply === 
-The reply contains an encoded JSON string. An response code is submitted in the field rc. If the response contains **rc = 0**, the bank supports giropay. Additional information which feature of giropay is supported can be found in the //giropay// and //giropay-ID// parameters. There will also be additional information about the bank returned, if they are known. 
- 
-== JSON parameter == 
-^name           ^mandatory  ^type      ^description   ^ 
-|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|error codes]] | 
-|msg            |yes       |String    |additional informationen about the response code | 
-|bankcode       |optional  |Integer   |bank code | 
-|bic            |optional  |String    |BIC | 
-|bankname       |optional  |String    |name of the bank | 
-|giropay        |optional  |Integer   |0 = giropay payment is not supported \\ 1 = giropay payment is supported| 
-|giropayid      |optional  |Integer   |0 = giropay-ID and giropay-ID + giropay payment are not supported \\ 1 = giropay-ID and giropay-ID + giropay payment are supported | 
-^HEADER parameter^^^^ 
-|hash           |yes       |String    |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | 
- 
-== Example in case of success == 
-{{page>codesamples:giropay#bankstatus.response.true&noheader&nofooter}} 
- 
-== Example in case of error == 
-{{page>codesamples:giropay#bankstatus.response.false&noheader&nofooter}} 
- 
-==== giropay issuer bank request ==== 
-Returns a list which contains all supported giropay issuer banks. The buyer has to choose his one. 
- 
-**URL:** https://payment.girosolution.de/girocheckout/api/v2/giropay/issuer \\ 
-**provided by:** GiroSolution AG \\ 
-**called by:** Händler 
- 
-== POST parameter == 
-^name           ^mandatory  ^type      ^description   ^ 
-|merchantId     |yes       |Integer   |Merchant ID | 
-|projectId      |yes       |Integer   |Project ID | 
-|hash           |yes       |String(32)|HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]])| 
- 
-== Example == 
-{{page>codesamples:giropay#issuer.request&noheader&nofooter}} 
- 
-=== Reply === 
-The reply contains an encoded JSON string. An response code is submitted in the field rc. If the response contains **rc = 0**, the request was successful. 
- 
-== JSON parameter == 
-^name           ^mandatory  ^type      ^description   ^ 
-|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|error codes]] | 
-|msg            |yes       |String    |additional informationen about the response code | 
-|issuer         |optional  |Mixed     |list of all supported issuer banks containing bic as key and name| 
- 
-== Example == 
-{{page>codesamples:giropay#issuer.response&noheader&nofooter}} 
  
  
Line 153: Line 135:
 **called by:** Merchant **called by:** Merchant
  
-== POST parameter == +== POST parameters == 
-^Name           ^Mandatory  ^^^Type        ^Description   ^ +^Name           ^Mandatory  ^Type        ^Description   ^ 
-^           ^giropay^giropay-ID^giropay+giropay-ID  ^        ^   ^ +|merchantId     |yes       |Integer     |merchant ID of a giropay project | 
-|merchantId     |yes       |yes       |yes       |Integer     |merchant ID of a giropay project | +|projectId      |yes       |integer     |project ID of a giropay project | 
-|projectId      |yes       |yes       |yes       |integer     |project ID of a giropay project | +|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 & = + , : ; . _ ! ? # /  
-|merchantTxId   |yes       |yes       |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 | 
-|amount         |yes                |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| 
-|currency       |yes                |yes       |String(3)   |currency\\ EUR = Euro| +|purpose        |yes       |String(27)  |purpose field, characters must comply with the SEPA character set (see [[en:girocheckout:giropay:start#sepa_compliant_characters|SEPA-compliant characters]]) 
-|purpose        |yes                |yes       |String(27)  |purpose | +|type           |yes  |String(4     |Transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Sale is booked immediately (default) \\ AUTH = Reservation of the amount 
-|bic            |optional  |optional  |optional  |String(11 |BIC (8 or 11-digits), (determined by [[en:tools:bankstatus_widget|Bankstatus Widget]])| +|shoppingCartType |Optional String(19) |Type of the shopping cart. The following values are allowed: \\ PHYSICAL = All goods in the cart are of a physical nature, \\ DIGITAL = All goods in the cart are of a digital nature (require no shipping), \\ MIXED = The cart contains both physical and digital goods (this is the default value should the parameter not be given), \\ ANONYMOUS_DONATION = This is an anonymous donation and not a commercial transaction (no address data necessary), \\ AUTHORITIES_PAYMENT = This is a payment for local authorities (no address data necessary).| 
-|iban           |optional |optional |optional |String(34)  |IBAN **without whitespaces**| +|shippingAddresseFirstName |(see descr.) |String(100)  | First name of the shipping address. **Mandatory** for shopping cart types PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters: All letters (UTF-8, also foreign), 0-9, the symbols %% .-!#$%&'*+/=?^_’`´{|}~"(),:;<>@[] %%, and blanks as well as line breaks. 
-|info1Label|optional |optional |optional |String(30 |additional information field which is shown on the payment form (label) +|shippingAddresseLastName |(see descr.) |String(100   Last name of the shipping address. **Mandatory** for shopping cart types PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters, see shippingAddresseFirstName. 
-|info1Text |optional |optional |optional |String(80 |additional information field which is shown on the payment form (text)  +|shippingCompany      |Optional   |String(100   Company name of shipping address. Permitted characters, see shippingAddresseFirstName. 
-|info2Label|optional |optional |optional |String(30 |additional information field which is shown on the payment form (label) | +|shippingAdditionalAddressInformation |Optional       |String(100) | Additional (streetinformation of shipping address. Permitted characters, see shippingAddresseFirstName. 
-|info2Text |optional |optional |optional |String(80 |additional information field which is shown on the payment form (text)  +|shippingStreet       |Optional      |String(100   Street of the shipping address. Permitted characters, see shippingAddresseFirstName. 
-|info3Label|optional |optional |optional |String(30 |additional information field which is shown on the payment form (label) +|shippingStreetNumber |Optional    |String(10  House number of the shipping address. Permitted characters, see shippingAddresseFirstName. 
-|info3Text |optional |optional |optional |String(80 |additional information field which is shown on the payment form (text)  | +|shippingZipCode      |(see descr.     |String(10)  | Postcode of shipping address. **Mandatory** for shopping cart types PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters, see shippingAddresseFirstName. 
-|info4Label|optional |optional |optional |String(30 |additional information field which is shown on the payment form (label) | +|shippingCity         |(see descr.)      |String(100)    City of shipping address. **Mandatory** for shopping cart types PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters, see shippingAddresseFirstName. | 
-|info4Text |optional |optional |optional |String(80 |additional information field which is shown on the payment form (text)  | +|shippingCountry      |(see descr.)    |String(2) | 2-letter country code (ISO 3166-1). **Mandatory** for shopping cart types PPHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. 
-|info5Label|optional |optional |optional |String(30)  |additional information field which is shown on the payment form (label) | +|shippingEmail        |(see descr.)     |String(255)    Email address of the buyer. **Mandatory** for shopping cart type DIGITAL, optional for all others. | 
-|info5Text |optional |optional |optional |String(80 |additional information field which is shown on the payment form (text)  +|merchantOrderReferenceNumber  |Optional         |String(20   Additional information for the payment reconciliation that is shown in the purpose on bank statements (only for type=SALE) Characters must comply with the SEPA character set (see [[en:girocheckout:giropay:start#sepa_compliant_characters|SEPA-compliant characters]]). 
-|urlRedirect    |yes       |yes       |yes       |String      |URL, where the buyer has to be sent after payment | +|cart           |Optional      |JSON String | All products in the shopping cart in the following format (see below): [[en:girocheckout:giropay:start#cart_field|Description of cart field]]. 
-|urlNotify      |yes       |yes       |yes       |String      |URL, where the notification has to be sent after payment | +|deliveryType |Optional | String(12   The destination of a shipment. The default value is STANDARD. Possible values: \\ STANDARD: The goods are delivered to an ordinary postal address. \\ PACKSTATION: The goods are delivered to a self-service parcel terminal. \\ STORE_PICKUP: The goods are collected from the store. 
-|hash           |yes       |yes       |yes       |String      |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) | +|urlRedirect    |yes       |String(2048) |URL, where the buyer has to be sent 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.  | 
-<WRAP center round info 60%> +|giropayCustomerId     |optional  |String(20)   |Customer number, max. length: 20 
-Through the info parameter you can display additional information on the payment form of the bank. There are up to info 5 elements possible. One info element consists of one label and one infotext. +|hash           |yes       |String(32)   |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
-</WRAP>+
  
 == Example == == Example ==
Line 194: Line 175:
 ^name           ^mandatory  ^type      ^description   ^ ^name           ^mandatory  ^type      ^description   ^
 |rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] | |rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] |
-|msg            |yes       |String    |additional information about the response code | +|msg            |yes       |String(255) |additional information about the response code | 
-|reference      |optional |String    |unique GiroCheckout transaction ID | +|reference      |optional |String(36) |unique GiroCheckout transaction ID | 
-|redirect       |optional |String    |redirect URL to the buyer's online banking account|+|redirect       |optional |String(2048)    |redirect URL to the buyer's online banking account|
 ^HEADER parameter^^^^ ^HEADER parameter^^^^
-|hash           |yes       |String    |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |+|hash           |yes       |String(32)    |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |
  
 == Example in case of success == == Example in case of success ==
Line 205: Line 186:
 == Example in case of error == == Example in case of error ==
 {{page>codesamples:giropay#transactionstart.response.false&noheader&nofooter}} {{page>codesamples:giropay#transactionstart.response.false&noheader&nofooter}}
 +
 +=== SEPA compliant characters ===
 +{{page>en:resources:sepa-chars&noheader&nofooter}}
 +
 +=== cart field ===
 +JSON array with item objects:
 +
 +^Name           ^Mandatory        ^Type        ^Description   ^
 +|name           |Yes             |String(100)      | Article name |
 +|ean            |Optional       |String(100)      | International artical number (EAN or GTIN) |
 +|quantity       |Yes             |Integer     | 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" : "Bobbycar",
 +    "ean" : "800001303",
 +    "quantity" : 3,
 +    "grossAmount" : 2599
 +  }, {
 +    "name" : "Helm",
 +    "quantity" : 1,
 +    "grossAmount" : 1853
 +  } ]
 +</code>
  
  
Line 211: Line 218:
 The result of a initialised 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 a initialised 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 a giropay payment is contained in the field //gcResultPayment//. If a giropay-ID or giropay-ID + giropay transaction was initialised the result of the age verification can be found in the field //gcResultAVS//.+The result of a giropay payment is contained in the field //gcResultPayment//
  
-Due to the internal giropay process, a redirection of the customer to urlRedirect is not done automatically but only after a customer click+At the end of the payment process on giriopay-side, an automatic redirect back to the shop is done after 5 seconds.
  
 === Request === === Request ===
Line 223: Line 230:
 ^name             ^mandatory  ^^^  type        ^description   ^ ^name             ^mandatory  ^^^  type        ^description   ^
 ^           ^giropay^giropay-ID^giropay+giropay-ID  ^        ^   ^ ^           ^giropay^giropay-ID^giropay+giropay-ID  ^        ^   ^
-|gcReference      |yes       |yes       |yes       |String      | unique GiroCheckout transaction ID | +|gcReference      |yes       |yes       |yes       |String(36)  | unique GiroCheckout transaction ID | 
-|gcMerchantTxId   |yes       |yes       |yes       | String     | merchant transaction ID | +|gcMerchantTxId   |yes       |yes       |yes       |String(255) | merchant transaction ID | 
-|gcBackendTxId    |yes       |yes       |yes       |String      | payment processor transaction ID |+|gcBackendTxId    |yes       |yes       |yes       |String(36)  | payment processor transaction ID |
 |gcAmount         |yes                |yes       |Integer     | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | |gcAmount         |yes                |yes       |Integer     | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny |
-|gcCurrency       |yes                |yes       |String      | currency | +|gcCurrency       |yes                |yes       |String(3)   | currency | 
-|gcResultPayment  |yes                |yes       |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]+|gcResultPayment  |yes                |yes       |Integer/String(1) String "0" or numeric [[en:girocheckout:resultcodes#zahlungsausgang|payment result code]]| 
-|gcResultAVS      |          |yes       |yes       |Integer     | [[en:girocheckout:resultcodes#altersverifikation|age verification result codes]] | +|gcHash           |yes       |yes       |yes       |String(32)  | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
-|gcObvName        |         |optional |optional |String | Optional adjustable field, which includes the name of the person who has to be verified (giropay-ID) +
-|gcHash           |yes       |yes       |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |+
  
 === Reply === === Reply ===
Line 242: Line 247:
  
 ==== Redirection of the customer to merchant ==== ==== 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+After completing the payment, the customer may return to the merchant through a link. After 5 seconds, there is an automatic redirect
  
 === Request === === Request ===
Line 252: Line 257:
 ^name             ^ mandatory  ^^^  type        ^description   ^ ^name             ^ mandatory  ^^^  type        ^description   ^
 ^           ^ giropay^giropay-ID^giropay+giropay-ID  ^        ^   ^ ^           ^ giropay^giropay-ID^giropay+giropay-ID  ^        ^   ^
-|gcReference      |yes       |yes       |yes       |String      | unique GiroCheckout transaction ID | +|gcReference      |yes       |yes       |yes       |String(36)  | unique GiroCheckout transaction ID | 
-|gcMerchantTxId   |yes       |yes       |yes       | String     | merchant transaction ID | +|gcMerchantTxId   |yes       |yes       |yes       |String(255) | merchant transaction ID | 
-|gcBackendTxId    |yes       |yes       |yes       |String      | payment processor transaction ID |+|gcBackendTxId    |yes       |yes       |yes       |String(36)  | payment processor transaction ID |
 |gcAmount         |yes                |yes       |Integer     | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | |gcAmount         |yes                |yes       |Integer     | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny |
-|gcCurrency       |yes                |yes       |String      | currency | +|gcCurrency       |yes                |yes       |String(3)   | currency | 
-|gcResultPayment  |yes                |yes       |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]+|gcResultPayment  |yes                |yes       |Integer/String(1) String "0" or numeric [[en:girocheckout:resultcodes#zahlungsausgang|payment result code]]| 
-|gcResultAVS      |          |yes       |yes       |Integer     | [[en:girocheckout:resultcodes#altersverifikation|age verification result codes]] | +|gcHash           |yes       |yes       |yes       |String(32)  | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
-|gcObvName        |         |optional |optional |String | Optional adjustable field, which includes the name of the person who has to be verified (giropay-ID) +
-|gcHash           |yes       |yes       |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |+
  
 ===== Retrieve sender information ===== ===== Retrieve sender information =====
Line 286: Line 289:
 ^Name           ^Mandatory  ^Type      ^Description   ^ ^Name           ^Mandatory  ^Type      ^Description   ^
 |rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] | |rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] |
-|msg            |yes       |String    |additional information about the response code in case of error| +|msg            |yes       |String(255) |Additional information about the response code in case of error| 
-|accountholder  |Optional |String    |Account holder of the sender account| +|accountholder  |Optional  |String(255) |Account holder of the sender account| 
-|iban           |Optional |String    |IBAN of the sender account | +|iban           |Optional  |String(36)  |IBAN of the sender account | 
-|bic            |Optional |String    |BIC of the sender account |+|bic            |Optional  |String(11)  |BIC of the sender account |
 ^HEADER parameter^^^^ ^HEADER parameter^^^^
-|hash           |yes       |String    |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |+|hash           |yes       |String(32)  |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |
  
 == Example in case of success == == Example in case of success ==
Line 299: Line 302:
 {{page>codesamples:giropay#senderinfo.response.false&noheader&nofooter}} {{page>codesamples:giropay#senderinfo.response.false&noheader&nofooter}}
  
-===== Bank selection widget ===== +===== Other transaction types ===== 
-{{page>en:girocheckout:widget&noheader&nofooter}}+These transactions refer to a previous transaction. They are based on a server-to-server communication and require no customer intervention (in terms of data entry). 
 + 
 +Provided by: GiroCheckout \\ 
 +Called by: Merchant \\ 
 + 
 +==== Workflow ==== 
 + 
 +<uml> 
 +hide footbox 
 + 
 +participant "Shop" as shop 
 +participant "GiroCheckout" as girocheckout 
 +participant "giropay" as gp 
 + 
 +autonumber 
 + 
 +shop -> girocheckout:  
 +girocheckout -> gp:  
 +gp -> girocheckout:  
 +girocheckout -> shop:  
 + 
 +center footer (c)2024 by S-Public Services GmbH 
 +</uml> 
 + 
 +  - Shop sends referencing transaction 
 +  - GiroCheckout routes transaction to giropay 
 +  - giropay transmits result to GiroCheckout 
 +  - Shop receives reply regarding transaction result ([[en:girocheckout:giropay: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 giropay project | 
 +|projectId      |Yes       |Yes |Integer     |Project ID of a giropay project | 
 +|merchantTxId   |Yes       |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       |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(36)      | 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. | 
 +|kassenzeichen  |Optional | |String(255)      |CAPTURE ONLY. 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. | 
 +|hash           |Yes       |Yes |String(32)      |HMAC MD5 hash of all the values in the call. See [[en:girocheckout:general:start#hash_generation|Generate hash]] | 
 + 
 +== Example == 
 +{{page>codesamples:giropay#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(36)      | GiroCheckout transaction ID | 
 +|merchantTxId   |Yes       |String(255)      | Merchant transaction ID | 
 +|backendTxId    |Yes       |String(36)      | 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(3)      | Currency | 
 +|resultPayment  |Yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result]]| 
 +|hash           |Yes       |String(32)      | 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:giropay#capture.response.true&noheader&nofooter}} 
 + 
 +== Example of failure == 
 +{{page>codesamples:giropay#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 giropay project | 
 +|projectId      |Yes       |Integer     |Project ID of a giropay project | 
 +|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 & = + , : ; . _ ! ? # /  | 
 +|reference      |Yes       |String(36)      |GiroCheckout transaction ID that is to be voided | 
 +|hash           |Yes       |String(32)      |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:giropay#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(255)    |Additional information about the response code | 
 +|reference      |yes       |String(36)    |Unique GiroCheckout transaction ID | 
 +|referenceParent      |yes       |String(36)      | GiroCheckout transaction ID of the original base transaction | 
 +|merchantTxId   |yes       |String(255)      | Unique transaction id of the merchant | 
 +|backendTxId    |yes       |String(36)      | 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(3)      | Currency | 
 +|resultPayment  |yes       |Integer     | [[en:girocheckout:resultcodes#result_codes_payment|Payment result codes]]| 
 +^HEADER parameter^^^^ 
 +|hash           |yes       |String(32)    |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:giropay#void.response.true&noheader&nofooter}} 
 + 
 +== Example in case of failure == 
 +{{page>codesamples:giropay#void.response.false&noheader&nofooter}}
  
en/girocheckout/giropay/start.txt · Last modified: 2024/03/13 20:53