Girocheckout API

User Tools

Site Tools

Trace:
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
Last revision Both sides next revision
en:girocheckout:giropay:start [2018/03/06 13:41]
thorstenmarx [Initialize giropay payment] 		en:girocheckout:giropay:start [2024/03/13 20:51]
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  |Optional |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 (street) information 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

Page Tools