This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
en:girocheckout:giropay:start [2016/05/13 18:34] michaelheumann [test data] |
en:girocheckout:giropay:start [2024/06/05 18:25] (current) michaelheumann |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== giropay/ giropay-ID | + | ====== giropay ====== |
- | Information about giropay can be found under [[https:// | + | |
**giropay can only process EURO payments.** | **giropay can only process EURO payments.** | ||
+ | |||
- | ===== Test Data ===== | + | <WRAP center round info 70%> |
- | {{page>en:testdata:giropay& | + | **Important information** \\ |
+ | During the coming months, we will be gradually ending our support for the existing giropay API (see [[/en:girocheckout:giropay-legacy: | ||
+ | </ | ||
- | ===== workflow | + | |
+ | <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, | ||
+ | </ | ||
+ | |||
+ | |||
+ | ===== Test data giropay ===== | ||
+ | {{page> | ||
+ | |||
+ | ===== Transaction types ===== | ||
+ | Detailed information regarding [[en: | ||
+ | |||
+ | < | ||
+ | left to right direction | ||
+ | skinparam packageStyle rect | ||
+ | |||
+ | rectangle SALE{ | ||
+ | (SALE) --> (REFUND) | ||
+ | (REFUND) | ||
+ | } | ||
+ | rectangle AUTH { | ||
+ | (AUTH) --> (CAPTURE ) | ||
+ | (CAPTURE ) --> (REFUND ) | ||
+ | |||
+ | } | ||
+ | </ | ||
+ | |||
+ | ===== Workflow | ||
<uml> | <uml> | ||
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 -> buyer: | bank -> buyer: | ||
buyer -> bank: | buyer -> bank: | ||
Line 40: | Line 70: | ||
giropay -> shop: | giropay -> shop: | ||
- | + | center footer (c)2021 by GiroSolution AG | |
- | center footer (c)2013 by GiroSolution AG | + | |
</ | </ | ||
- | - buyer/ customer chooses | + | - buyer/ customer chooses giropay/ giropay-ID |
- | - merchant checks the bankstatus ([[en: | + | |
- | - merchant receives a reply, if bank supports | + | |
- merchant initialises giropay/ | - merchant initialises giropay/ | ||
- GiroCheckout initialises request at giropay | - GiroCheckout initialises request at giropay | ||
Line 52: | 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' | + | - the buyer' |
+ | - giropay redirects to the customer' | ||
- bank shows login page | - bank shows login page | ||
- buyer/ customer authorises giropay payment/ giropay-ID | - buyer/ customer authorises giropay payment/ giropay-ID | ||
Line 64: | Line 92: | ||
- buyer/ | - buyer/ | ||
+ | ==== Reservation (AUTH) ==== | ||
+ | {{page> | ||
+ | <uml> | ||
+ | left to right direction | ||
+ | skinparam packageStyle rect | ||
+ | |||
+ | rectangle AUTH { | ||
+ | (AUTH) --> (capture) | ||
+ | (AUTH) --> (refund) | ||
+ | } | ||
+ | </ | ||
+ | ==== Reservation/ | ||
+ | {{page> | ||
+ | <uml> | ||
+ | left to right direction | ||
+ | skinparam packageStyle rect | ||
+ | |||
+ | rectangle SALE{ | ||
+ | (SALE) --> (refund) | ||
+ | } | ||
+ | </ | ||
===== API functions ===== | ===== API functions ===== | ||
- | ==== overview | + | ==== Overview |
- | As shown in the workflow there are different API calls during a giropay transaction | + | 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' | ||
- | === API call === | + | ==== Initialize giropay payment ==== |
- | **URL:** https:// | + | The initialization of a giropay |
- | **provided | + | |
- | **called by:** merchant | + | |
- | == POST parameter == | + | Towards |
- | ^parameter | + | |
- | |merchantId | + | |
- | |projectId | + | |
- | |bic |yes | + | |
- | |hash | + | |
- | + | ||
- | == example == | + | |
- | {{page> | + | |
- | + | ||
- | === 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 | + | |
- | + | ||
- | == JSON parameter == | + | |
- | ^name | + | |
- | |rc | + | |
- | |msg |yes | + | |
- | |bankcode | + | |
- | |bic |optional | + | |
- | |bankname | + | |
- | |giropay | + | |
- | |giropayid | + | |
- | ^HEADER parameter^^^^ | + | |
- | |hash | + | |
- | == example in case of success | + | === Request |
- | {{page> | + | |
- | + | ||
- | == example in case of error == | + | |
- | {{page> | + | |
- | + | ||
- | ==== giropay issuer bank request ==== | + | |
- | Returns a list which contains all supported giropay issuer banks. The buyer has to choose his one. | + | |
- | + | ||
- | **URL:** https:// | + | |
- | **provided by:** GiroSolution AG \\ | + | |
- | **called by:** Händler | + | |
- | + | ||
- | == POST parameter == | + | |
- | ^name | + | |
- | |merchantId | + | |
- | |projectId | + | |
- | |hash | + | |
- | + | ||
- | == example == | + | |
- | {{page> | + | |
- | + | ||
- | === 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 | + | |
- | |rc | + | |
- | |msg |yes | + | |
- | |issuer | + | |
- | + | ||
- | == Beispiel == | + | |
- | {{page> | + | |
- | + | ||
- | + | ||
- | ==== initialise giropay payment ==== | + | |
- | The initialisation of a giropay can be processed in different ways. This will be distinguished just by the project id. | + | |
- | + | ||
- | Torwards a successful initialisation you receive a reference number and an redirect link. The redirect link leads to the online banking account of the buyer' | + | |
- | + | ||
- | === request | + | |
**URL:** https:// | **URL:** https:// | ||
**provided by:** GiroCheckout \\ | **provided by:** GiroCheckout \\ | ||
- | **called by:** merchant | + | **called by:** Merchant |
- | == POST parameter | + | == POST parameters |
- | ^name ^mandatory | + | ^Name ^Mandatory |
- | ^ | + | |merchantId |
- | |merchantId | + | |projectId |
- | |projectId | + | |merchantTxId |
- | |merchantTxId | + | |amount |
- | |amount | + | |currency |
- | |currency | + | |purpose |
- | |purpose | + | |type |Optional |
- | |bic |yes | + | |shoppingCartType |
- | |iban |optional |optional |optional | + | |shippingAddresseFirstName |
- | |info1Label|optional |optional |optional | + | |shippingAddresseLastName |
- | |info1Text | + | |shippingCompany |
- | |info2Label|optional |optional |optional | + | |shippingAdditionalAddressInformation |Optional |
- | |info2Text | + | |shippingStreet |
- | |info3Label|optional |optional |optional | + | |shippingStreetNumber |
- | |info3Text | + | |shippingZipCode |
- | |info4Label|optional | + | |shippingCity |
- | |info4Text | + | |shippingCountry |
- | |info5Label|optional |optional |optional | + | |shippingEmail |
- | |info5Text | + | |merchantOrderReferenceNumber |
- | |urlRedirect | + | |cart |Optional |
- | |urlNotify | + | |deliveryType |
- | |hash |yes | + | |urlRedirect |
+ | |urlNotify | ||
+ | |kassenzeichen | ||
+ | |giropayCustomerId | ||
+ | |hash | ||
- | + | == Example | |
- | <WRAP center round info 60%> | + | |
- | 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. | + | |
- | </ | + | |
- | + | ||
- | == example | + | |
{{page> | {{page> | ||
- | === reply === | + | === Reply === |
The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialised. The response also includes a transaction id and a redirect URL to the online banking account of the buyer' | The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialised. The response also includes a transaction id and a redirect URL to the online banking account of the buyer' | ||
Line 195: | Line 175: | ||
^name | ^name | ||
|rc | |rc | ||
- | |msg |yes | + | |msg |yes |
- | |reference | + | |reference |
- | |redirect | + | |redirect |
^HEADER parameter^^^^ | ^HEADER parameter^^^^ | ||
- | |hash | + | |hash |
- | == example | + | == Example |
{{page> | {{page> | ||
- | == example | + | == Example |
{{page> | {{page> | ||
+ | === SEPA compliant characters === | ||
+ | {{page> | ||
- | ==== notification about the payment result ==== | + | === cart field === |
+ | JSON array with item objects: | ||
- | The result | + | ^Name |
+ | |name | ||
+ | |ean |Optional | ||
+ | |quantity | ||
+ | |grossAmount | ||
- | The result of a giropay payment is contained | + | == Example == |
+ | < | ||
+ | [ { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } ] | ||
+ | </ | ||
+ | |||
+ | |||
+ | ==== Notification about the payment result ==== | ||
+ | |||
+ | 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 | ||
- | Due to the internal | + | The result of a giropay |
+ | At the end of the payment process on giriopay-side, | ||
- | === request | + | === Request |
**URL:** notifyUrl of the prior init transaction call \\ | **URL:** notifyUrl of the prior init transaction call \\ | ||
**provided by:** merchant \\ | **provided by:** merchant \\ | ||
Line 225: | Line 230: | ||
^name | ^name | ||
^ | ^ | ||
- | |gcReference | + | |gcReference |
- | |gcMerchantTxId | + | |gcMerchantTxId |
- | |gcBackendTxId | + | |gcBackendTxId |
|gcAmount | |gcAmount | ||
- | |gcCurrency | + | |gcCurrency |
- | |gcResultPayment | + | |gcResultPayment |
- | |gcResultAVS | + | |gcHash |
- | |gcObvName | + | |
- | |gcHash | + | |
- | === reply === | + | === Reply === |
As a reply to the GET request, one of the following HTTP status codes is expected. | As a reply to the GET request, one of the following HTTP status codes is expected. | ||
Line 243: | Line 246: | ||
|all others | |all others | ||
- | ==== redirection | + | ==== Redirection |
- | After completing the payment, the customer may return to the merchant through a link. This return | + | After completing the payment, the customer may return to the merchant through a link. After 5 seconds, there is an automatic redirect. |
- | === request | + | === Request |
**URL:** redirectUrl of the prior init transaction call \\ | **URL:** redirectUrl of the prior init transaction call \\ | ||
- | **provided | + | **Provided |
- | **called | + | **Called |
== GET parameter == | == GET parameter == | ||
^name ^ mandatory | ^name ^ mandatory | ||
^ ^ giropay^giropay-ID^giropay+giropay-ID | ^ ^ giropay^giropay-ID^giropay+giropay-ID | ||
- | |gcReference | + | |gcReference |
- | |gcMerchantTxId | + | |gcMerchantTxId |
- | |gcBackendTxId | + | |gcBackendTxId |
|gcAmount | |gcAmount | ||
- | |gcCurrency | + | |gcCurrency |
- | |gcResultPayment | + | |gcResultPayment |
- | |gcResultAVS | + | |gcHash |
- | |gcObvName | + | |
- | |gcHash | + | |
+ | ===== Retrieve sender information ===== | ||
+ | This service allows the retrieval of the information associated to the sender of a completed transaction. As a response to the given reference number, the account holder, IBAN and BIC of the customer are returned. | ||
+ | |||
+ | === API call === | ||
+ | **URL:** https:// | ||
+ | **Provided by:** GiroCheckout \\ | ||
+ | **Called by:** Merchant | ||
+ | |||
+ | == POST Parameters == | ||
+ | ^Name | ||
+ | |merchantId | ||
+ | |projectId | ||
+ | |reference | ||
+ | |hash | ||
+ | |||
+ | == Example == | ||
+ | {{page> | ||
+ | |||
+ | === Response === | ||
+ | The response is a JSON object. The rc field returns an error code. If **rc = 0** is returned, the corresponding fields contain the sender information. | ||
+ | |||
+ | == JSON Parameters == | ||
+ | ^Name | ||
+ | |rc | ||
+ | |msg |yes | ||
+ | |accountholder | ||
+ | |iban | ||
+ | |bic |Optional | ||
+ | ^HEADER parameter^^^^ | ||
+ | |hash | ||
+ | |||
+ | == Example in case of success == | ||
+ | {{page> | ||
+ | |||
+ | == Example in case of error == | ||
+ | {{page> | ||
+ | |||
+ | ===== Other transaction types ===== | ||
+ | These transactions refer to a previous transaction. They are based on a server-to-server communication and require no customer intervention (in terms of data entry). | ||
+ | |||
+ | Provided by: GiroCheckout \\ | ||
+ | Called by: Merchant \\ | ||
+ | |||
+ | ==== Workflow ==== | ||
+ | |||
+ | <uml> | ||
+ | hide footbox | ||
+ | |||
+ | participant " | ||
+ | participant " | ||
+ | participant " | ||
+ | |||
+ | autonumber | ||
+ | |||
+ | shop -> girocheckout: | ||
+ | girocheckout -> gp: | ||
+ | gp -> girocheckout: | ||
+ | girocheckout -> shop: | ||
+ | |||
+ | center footer (c)2024 by S-Public Services GmbH | ||
+ | </ | ||
+ | |||
+ | - Shop sends referencing transaction | ||
+ | - GiroCheckout routes transaction to giropay | ||
+ | - giropay transmits result to GiroCheckout | ||
+ | - Shop receives reply regarding transaction result ([[en: | ||
+ | |||
+ | ==== Booking (CAPTURE) ==== | ||
+ | {{page> | ||
+ | |||
+ | <uml> | ||
+ | left to right direction | ||
+ | skinparam packageStyle rect | ||
+ | |||
+ | rectangle AUTH { | ||
+ | (auth) --> (CAPTURE) | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ==== Refund ==== | ||
+ | {{page> | ||
+ | <uml> | ||
+ | left to right direction | ||
+ | skinparam packageStyle rect | ||
+ | |||
+ | rectangle SALE{ | ||
+ | (sale) --> (REFUND) | ||
+ | } | ||
+ | rectangle AUTH { | ||
+ | (auth) --> (REFUND ) | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | === POST Parameters === | ||
+ | CAPTURE URL: https:// | ||
+ | REFUND URL: https:// | ||
+ | |||
+ | ^Name | ||
+ | ^::: ^ CAPTURE ^ REFUND ^::: ^::: ^ | ||
+ | |merchantId | ||
+ | |projectId | ||
+ | |merchantTxId | ||
+ | |amount | ||
+ | |currency | ||
+ | |purpose | ||
+ | |reference | ||
+ | |merchantReconciliationReferenceNumber | ||
+ | |final | ||
+ | |kassenzeichen | ||
+ | |hash | ||
+ | |||
+ | == Example == | ||
+ | {{page> | ||
+ | |||
+ | === 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 | ||
+ | |reference | ||
+ | |merchantTxId | ||
+ | |backendTxId | ||
+ | |amount | ||
+ | |currency | ||
+ | |resultPayment | ||
+ | |hash | ||
+ | |||
+ | == Example of success case == | ||
+ | {{page> | ||
+ | |||
+ | == Example of failure == | ||
+ | {{page> | ||
+ | |||
+ | ==== Void ==== | ||
+ | {{page> | ||
+ | |||
+ | === POST Parameters === | ||
+ | URL VOID: https:// | ||
+ | |||
+ | ^Name | ||
+ | |merchantId | ||
+ | |projectId | ||
+ | |merchantTxId | ||
+ | |reference | ||
+ | |hash | ||
+ | |||
+ | == Example == | ||
+ | {{page> | ||
+ | |||
+ | === 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 | ||
+ | |rc | ||
+ | |msg |yes | ||
+ | |reference | ||
+ | |referenceParent | ||
+ | |merchantTxId | ||
+ | |backendTxId | ||
+ | |amount | ||
+ | |currency | ||
+ | |resultPayment | ||
+ | ^HEADER parameter^^^^ | ||
+ | |hash | ||
+ | == Example in case of success == | ||
+ | {{page> | ||
+ | == Example in case of failure == | ||
+ | {{page> | ||