en:girocheckout:giropay:start
Differences
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/25 17:38] michaelheumann |
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> | + | **Important information** \\ |
| + | During the coming months, we will be gradually ending our support for the existing giropay API (see [[/ | ||
| + | </ | ||
| + | |||
| + | |||
| + | <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 ===== | ===== 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 -> 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 |
| </ | </ | ||
| - | - 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 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' | + | - 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 63: | 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 === | ||
| - | **URL:** https:// | ||
| - | **provided by:** GiroCheckout \\ | ||
| - | **called by:** merchant | ||
| - | |||
| - | == POST parameter == | ||
| - | ^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 can be found in the //giropay// and // | ||
| - | |||
| - | == JSON parameter == | ||
| - | ^name | ||
| - | |rc | ||
| - | |msg |yes | ||
| - | |bankcode | ||
| - | |bic |optional | ||
| - | |bankname | ||
| - | |giropay | ||
| - | |giropayid | ||
| - | ^HEADER parameter^^^^ | ||
| - | |hash | ||
| - | |||
| - | == Example in case of success == | ||
| - | {{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 | ||
| - | |||
| - | == Example == | ||
| - | {{page> | ||
| Line 153: | Line 135: | ||
| **called by:** Merchant | **called by:** Merchant | ||
| - | == POST parameter | + | == POST parameters |
| - | ^Name | + | ^Name |
| - | ^ | + | |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 | |
| - | <WRAP center round info 60%> | + | |giropayCustomerId |
| - | 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 |
| - | </ | + | |
| == Example == | == Example == | ||
| Line 194: | Line 175: | ||
| ^name | ^name | ||
| |rc | |rc | ||
| - | |msg |yes | + | |msg |yes |
| - | |reference | + | |reference |
| - | |redirect | + | |redirect |
| ^HEADER parameter^^^^ | ^HEADER parameter^^^^ | ||
| - | |hash | + | |hash |
| == 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> | {{page> | ||
| + | |||
| + | === SEPA compliant characters === | ||
| + | {{page> | ||
| + | |||
| + | === cart field === | ||
| + | JSON array with item objects: | ||
| + | |||
| + | ^Name | ||
| + | |name | ||
| + | |ean |Optional | ||
| + | |quantity | ||
| + | |grossAmount | ||
| + | |||
| + | == Example == | ||
| + | < | ||
| + | [ { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } ] | ||
| + | </ | ||
| Line 211: | Line 218: | ||
| The result of a initialised transaction will be submitted to the prior in the // | The result of a initialised transaction will be submitted to the prior in the // | ||
| - | The result of a giropay payment is contained in the field // | + | The result of a giropay payment is contained in the field // |
| - | Due to the internal giropay process, a redirection | + | At the end of the payment process on giriopay-side, |
| === Request === | === Request === | ||
| Line 223: | Line 230: | ||
| ^name | ^name | ||
| ^ | ^ | ||
| - | |gcReference | + | |gcReference |
| - | |gcMerchantTxId | + | |gcMerchantTxId |
| - | |gcBackendTxId | + | |gcBackendTxId |
| |gcAmount | |gcAmount | ||
| - | |gcCurrency | + | |gcCurrency |
| - | |gcResultPayment | + | |gcResultPayment |
| - | |gcResultAVS | + | |gcHash |
| - | |gcObvName | + | |
| - | |gcHash | + | |
| === 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 | + | 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> | ||
en/girocheckout/giropay/start.1464190710.txt.gz · Last modified: 2021/04/12 14:32