This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
en:girocheckout:paypage:start [2018/07/13 19:19] michaelheumann [Notification about transaction result] |
en:girocheckout:paypage:start [2023/06/20 15:55] (current) michaelheumann |
||
---|---|---|---|
Line 1: | Line 1: | ||
~~NOCACHE~~ | ~~NOCACHE~~ | ||
====== Payment Page ====== | ====== Payment Page ====== | ||
+ | |||
+ | <WRAP center round info> | ||
+ | ==== Important indication regarding giropay and paydirekt ==== | ||
+ | The payment methods giropay and paydirekt are currently undergoing important changes that also affect the API. Please particularly note the new fields of the payment page API in the [[en: | ||
+ | |||
+ | The new fields are: | ||
+ | * paydirektShoppingCartType | ||
+ | * paydirektShippingCompany | ||
+ | * paydirektShippingAdditionalAddressInformation | ||
+ | * paydirektShippingStreet | ||
+ | * paydirektShippingStreetNumber | ||
+ | * paydirektShippingEmail | ||
+ | * paydirektMerchantOrderReferenceNumber | ||
+ | * paydirektCart | ||
+ | * paydirektDeliveryType | ||
+ | |||
+ | Please also note the information below regarding the purpose field. | ||
+ | |||
+ | </ | ||
+ | |||
+ | |||
+ | <WRAP center round info 80%> | ||
+ | **API change** \\ | ||
+ | The following change is being made to the API in the following days: \\ | ||
+ | The parameter paydirektMerchantReconciliationReferenceNumber is replaced by paydirektMerchantOrderReferenceNumber, | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | <WRAP hide> | ||
+ | Further information - especially about migration and settlement - is available in our new [[girocheckout: | ||
+ | </ | ||
+ | |||
This document describes all flows and interfaces that are required for an integration of the GiroCheckout Payment Page. | This document describes all flows and interfaces that are required for an integration of the GiroCheckout Payment Page. | ||
Line 7: | Line 40: | ||
**Example** | **Example** | ||
- | {{: | + | {{: |
+ | |||
+ | |||
+ | <WRAP center round info> | ||
+ | ==== Indication regarding the purpose field ==== | ||
+ | Depending on the payment method that is selected by the buyer, not all characters in the purpose fields may be passed on, because the maximum lengths differ among the payment methods (for example, 27 characters in case of giropay). | ||
+ | |||
+ | The final purpose text may be adapted by the payment page to fit the requirements, | ||
+ | </ | ||
+ | |||
+ | |||
+ | ==== Notes on 3-D Secure 2.0 ==== | ||
+ | |||
+ | Since January 21st 2021, the new security procedure for credit card payments "3D Secure 2.0" - introduced within the PSD2 efforts - has been mandatory for all payment providers. This API documentation already contains the fields necessary for this (field names beginning with " | ||
+ | |||
+ | **Please keep in mind**: The parameters related to 3D Secure 2.0 are subject to changes due to modifications in the EMVCo 3-D Secure specs. | ||
+ | |||
+ | |||
+ | ===== Supported payment methods ===== | ||
The following payment methods are currently supported: | The following payment methods are currently supported: | ||
- | * giropay | + | |
- | | + | ^ Payment method ^ Code ^ |
- | | + | | giropay |
- | * credit | + | | giropay-ID + giropay | 17 | |
- | * direct | + | | giropay with payment confirmation | 18 | |
- | * direct | + | | eps | 2 | |
- | * direct debit with guarantee | + | | iDEAL | 12 | |
- | | + | | Credit |
- | | + | | Direct |
- | * Sofort. | + | | Direct |
+ | | Bluecode | 26 | | ||
+ | | Maestro | 33 | | ||
+ | | PayPal | ||
+ | | paydirekt | ||
+ | | SOFORT-Überweisung | 27 | | ||
===== Payment initialization through the payment page ===== | ===== Payment initialization through the payment page ===== | ||
Line 54: | Line 111: | ||
shop -> customer: | shop -> customer: | ||
- | center footer (c)2017 by GiroSolution | + | center footer (c)2022 by S-Public Services |
</ | </ | ||
Line 77: | Line 134: | ||
**URL:** https:// | **URL:** https:// | ||
- | **Provided by:** GiroSolution | + | **Provided by:** S-Public Services GmbH \\ |
**Called by:** Merchant | **Called by:** Merchant | ||
Line 84: | Line 141: | ||
|merchantId | |merchantId | ||
|projectId | |projectId | ||
- | |hash | + | |hash |
== Example == | == Example == | ||
Line 95: | Line 152: | ||
^Name | ^Name | ||
|rc | |rc | ||
- | |msg |Yes | + | |msg |Yes |
- | |projects | + | |projects |
^HEADER Parameters^^^^ | ^HEADER Parameters^^^^ | ||
- | |hash | + | |hash |
== Example == | == Example == | ||
Line 112: | Line 169: | ||
|merchantId | |merchantId | ||
|projectId | |projectId | ||
- | |merchantTxId | + | |merchantTxId |
- | |amount | + | |amount |
|currency | |currency | ||
- | |purpose | + | |purpose |
|description | |description | ||
|pagetype | |pagetype | ||
- | |expirydate | + | |expirydate |
+ | |single | ||
+ | |timeout | ||
|type | |type | ||
|locale | |locale | ||
Line 125: | Line 184: | ||
|organization | |organization | ||
|freeamount | |freeamount | ||
- | |fixedvalues | + | |fixedvalues |
- | |minamount | + | |minamount |
- | |maxamount | + | |maxamount |
|orderid | |orderid | ||
- | |projectlist | + | |projectlist |
- | |pkn |Optional |String | + | |pkn |Optional |String(50) |This field allows the initialization of a new transaction without having to input the credit card or direct debit data again (recurring payments). \\ create = generate new pseudo card number for the payment data (credit card or bank data) used in this transaction. | |
|test | |test | ||
- | |successUrl | + | |certdata |
- | |backUrl | + | |otherpayments |
- | |failUrl | + | |paydirektShoppingCartType |Optional | String(19) |
- | |notifyUrl | + | |paydirektShippingFirstName |Optional |
- | |hash | + | |paydirektShippingLastName |
+ | |paydirektShippingCompany | ||
+ | |paydirektShippingAdditionalAddressInformation |Optional | ||
+ | |paydirektShippingStreet | ||
+ | |paydirektShippingStreetNumber |Optional | ||
+ | |paydirektShippingZipCode | ||
+ | |paydirektShippingCity | ||
+ | |paydirektShippingCountry | ||
+ | |paydirektShippingEmail | ||
+ | |paydirektMerchantOrderReferenceNumber | ||
+ | |paydirektCart | ||
+ | |paydirektDeliveryType |Optional | String(12) | ||
+ | |successUrl | ||
+ | |backUrl | ||
+ | |failUrl | ||
+ | |notifyUrl | ||
+ | |tds2Address |optional |String(50) | For 3D Secure 2.0: Main address line (usually street and number) of the card holder' | ||
+ | |tds2Postcode |optional |String(10) | For 3D Secure 2.0: Postal code of the card holder' | ||
+ | |tds2City |optional |String(50) | For 3D Secure 2.0: City of the card holder' | ||
+ | |tds2Country |optional |String(2) | For 3D Secure 2.0: Country of the card holder' | ||
+ | |tds2Optional |optional |JSON String | For 3D Secure 2.0: JSON-String that contains further optional fields. A complete list of the available fields can be found underneath this table under [[en: | ||
+ | |mandateReference | optional |String(35) | ||
+ | numbers: 0 – 9 | ||
+ | characters: A – Z and a – z | ||
+ | special characters: & \ / = + , : ; . _ \ - ! ? | ||
+ | | | ||
+ | |mandateSignedOn | optional |String(10)| date (YYYY-MM-DD), | ||
+ | |mandateReceiverName |optional |String(70)| name of the recipient. If nothing is specified companies name from the master data is used. \\ | ||
+ | numbers: 0 – 9 | ||
+ | characters: A – Z and a – z | ||
+ | special characters: & / = + , : ; . _ - ! ? | ||
+ | | | ||
+ | |mandateSequence | optional |Integer |Sequence type of the SEPA direct debit. \\ 1 = single payment (default) \\ 2 = first payment of a sequence \\ 3 = recurring payment \\ 4 = last payment of a sequence | | ||
+ | |informationText | Optional | String(300) | Informational notification text that is displayed on the Payment Page right above the payment method selection. This text may contain certain HTML tags: <a> <em> < | ||
+ | |kassenzeichen | ||
+ | |qrcodeReturn | ||
+ | |hash | ||
=== SEPA compliant characters === | === SEPA compliant characters === | ||
- | {{page> | + | {{page> |
=== Allowed description characters === | === Allowed description characters === | ||
Line 149: | Line 244: | ||
* Length between 1 and 60 characters | * Length between 1 and 60 characters | ||
- | === Payment methods | + | === 3D Secure 2.0 Optional Fields (tds2Optional) |
- | These are the allowed values for the payment methods specified in the parameter paymethods: | + | This is a JSON formatted object that has a hierarchical structure (2 levels) and contains |
- | ^ID ^Payment method | + | * billingAddress |
- | |1 | + | * shippingddress |
- | |2 | + | * homePhoneNumber |
- | |6 | + | * mobilePhoneNumber |
- | |7 | + | * workPhoneNumber |
- | |8 | + | * cardholderAccountInfo |
- | |11 | + | * tdsMerchantRiskIndicators |
- | |12 | + | * tdsRequestorAuthenticationInformation |
- | |14 | + | * tdsTransactionAttributes |
- | |23 | paydirekt | + | |
- | |27 | Sofort. | | + | Generally, the following fields (all optional) are available (fields in sub-objects are displayed as [sub-object name].[field]): |
+ | |||
+ | ^Name ^Type ^Description | ||
+ | |email |String(255) | The card holder' | ||
+ | |addressesMatch | ||
+ | ^**// | ||
+ | |billingAddress.line2 | ||
+ | |billingAddress.line3 | ||
+ | |billingAddress.state | ||
+ | ^**// | ||
+ | |shippingAddress.line1 |String(50) | First line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/ | ||
+ | |shippingAddress.line2 |String(50) | Second line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/ | ||
+ | |shippingAddress.line3 |String(50) | Third line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/ | ||
+ | |shippingAddress.postcode |String(10) |Postal code of the shipping address, Format A-Z, a-z, 0-9, Blank, [-], max. 11 | | ||
+ | |shippingAddress.city |String(50) | City of the shipping address, Format A-Z, a-z, 0-9, Blank, [-/ | ||
+ | |shippingAddress.state |String(50) | Subdivision (state, province or the like) of a country according to ISO 3166-2. Format A-Z, max. 3 | | ||
+ | |shippingAddress.country |String(2) | Country of the shipping address, Format A-Z, max. 2. Two-letter country code according to the currently applicable standard ISO 3166. | | ||
+ | ^**// | ||
+ | |homePhoneNumber.country |Integer | Country code of the telephone number without leading zeroes. Format 0-9, max. 3. e.g. 49 for Germany. | | ||
+ | |homePhoneNumber.regional |String(15) | Telephone number without country code and without leading 0 (area code and local number). Format 0-9, max. 15, e.g. 73482984938. | | ||
+ | ^**// | ||
+ | |mobilePhoneNumber.country |Integer | Country code of the mobile phone number without leading zeroes. Format 0-9, max. 3. e.g. 49 for Germany. | | ||
+ | |mobilePhoneNumber.regional |String(15) | Telephone number without country code and without leading 0 (area code and local number). Format 0-9, max. 15, e.g. 73482984938. | | ||
+ | ^**// | ||
+ | |workPhoneNumber.country |Integer | Country code of the work phone number without leading zeroes. Format 0-9, max. 3. e.g. 49 for Germany. | | ||
+ | |workPhoneNumber.regional |String(15) | Telephone number without country code and without leading 0 (area code and local number). Format 0-9, max. 15, e.g. 73482984938. | | ||
+ | ^**// | ||
+ | |cardholderAccountInfo.accountAgeIndicator |String(12) | Indicates when the customer' | ||
+ | |cardholderAccountInfo.passwordChangeIndicator |String(12) | Indicates when the password of the customer account was changed the last time. Possible values: " | ||
+ | |cardholderAccountInfo.paymentAccountAgeIndicator |String(12) | Indicates when the customer' | ||
+ | |cardholderAccountInfo.accountChange |String(12) | Indicates when the customer account in the shop was last modified, e.g. address change or new payment data. Possible values: " | ||
+ | |cardholderAccountInfo.shippingAddressAgeIndicator |String(12) | Indicates when the customer first used the current shipping address. Possible values: " | ||
+ | |cardholderAccountInfo.shippingNameIndicator |String(9) | Specifies if the card holder' | ||
+ | |cardholderAccountInfo.suspiciousAccountActivity |Boolean | Indicates if the shop experienced suspicious activities of the card holder (true) or not (false). | | ||
+ | |cardholderAccountInfo.provisioningDayCount |Integer | Number of "add card" attempts within the last 24 hours. Format 0-9, max. 3. | | ||
+ | ^**// | ||
+ | |tdsMerchantRiskIndicators.deliveryTimeframe |String(14) | Indicates when the customer will receive the merchandise. Possible values: " | ||
+ | |tdsMerchantRiskIndicators.deliveryEmailAddress | ||
+ | |tdsMerchantRiskIndicators.giftCardAmount | ||
+ | |tdsMerchantRiskIndicators.giftCardCount |Integer | Total count of gift cards purchased. Format 0-9, max. 2. | | ||
+ | |tdsMerchantRiskIndicators.giftCardCurrency |Integer | Currency code of a gift card according to ISO 4217. Format A-Z, max. 3. | | ||
+ | |tdsMerchantRiskIndicators.preOrderDate |Date | In the case of a pre-ordered purchase: date when the merchandise is expected to be available. | | ||
+ | |tdsMerchantRiskIndicators.preOrderPurchaseIndicator |String(9) | Possible values: " | ||
+ | |tdsMerchantRiskIndicators.reorderItemsIndicator |String(9) | Indicates if the customer is reordering previously purchased merchandise: | ||
+ | |tdsMerchantRiskIndicators.shippingIndicator |String(16) | Specifies where the merchandise is delivered to. Possible values: " | ||
+ | ^**// | ||
+ | |tdsRequestorAuthenticationInformation.authenticationData |String(2048) | Authentication data of the customer. Format A-Z, a-z, 0-9 [!"# | ||
+ | |tdsRequestorAuthenticationInformation.authenticationTimestamp |DateTime | Date and time when the customer authenticated in the shop. Format JJJJ-MM-TTTHH: | ||
+ | |tdsRequestorAuthenticationInformation.authenticationMethod |String(17) | Specifies how the customer authenticated to the shop. Possile values: " | ||
+ | ^**// | ||
+ | |tdsTransactionAttributes.purchaseInstalmentData |Integer | Maximum number of authorisations permitted for instalment payments. Format 0-9, max. 3, Wert muss > 1 sein. | | ||
+ | |tdsTransactionAttributes.recurringExpiry |Date | Date after which no further authorisations shall be carried out. Format YYYY-MM-DD. | | ||
+ | |tdsTransactionAttributes.recurringFrequency |Integer | Minimum number of days between authorisations. Format 0-9, max. 4. | | ||
+ | |tdsTransactionAttributes.type |String(17) | Type of 3-D Secure 2.0 payment. Possible values: " | ||
+ | |||
+ | == Example of a tds2Optional string (formatted for demonstration purposes, should normally be specified in one line) == | ||
+ | < | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | } | ||
+ | </ | ||
== Example == | == Example == | ||
Line 173: | Line 386: | ||
^Name | ^Name | ||
|rc | |rc | ||
- | |msg |Yes | + | |msg |Yes |
- | |reference | + | |reference |
- | |url | + | |url |Optional |
+ | |qrcode | ||
^HEADER Parameters^^^^ | ^HEADER Parameters^^^^ | ||
- | |hash | + | |hash |
== Example in case of success == | == Example in case of success == | ||
Line 185: | Line 399: | ||
{{page> | {{page> | ||
+ | === cart field === | ||
+ | JSON array with item objects: | ||
+ | |||
+ | ^Name | ||
+ | |name | ||
+ | |ean |Optional | ||
+ | |quantity | ||
+ | |grossAmount | ||
+ | |||
+ | == Example == | ||
+ | < | ||
+ | [ { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } ] | ||
+ | </ | ||
==== Notification about transaction result ==== | ==== Notification about transaction result ==== | ||
Line 201: | Line 437: | ||
^Name | ^Name | ||
- | |gcPaymethod | + | |gcPaymethod |
- | |gcType | + | |gcType |
- | |gcProjectId | + | |gcProjectId |
- | |gcReference | + | |gcReference |
- | |gcMerchantTxId | + | |gcMerchantTxId |
- | |gcBackendTxId | + | |gcBackendTxId |
|gcAmount | |gcAmount | ||
- | |gcCurrency | + | |gcCurrency |
|gcResultPayment | |gcResultPayment | ||
- | |gcPkn | + | |gcPkn |
- | |gcCardnumber | + | |gcCardnumber |
- | |gcCardExpDate | + | |gcCardExpDate |
- | |gcAccountHolder | + | |gcAccountHolder |
- | |gcIban | + | |gcIban |
- | |gcHash | + | |gcHash |
=== Redirect === | === Redirect === | ||
Line 221: | Line 457: | ||
The second communication path is the redirection of the buyer within his/her browser to one of the three redirection URLs specified during initialization: | The second communication path is the redirection of the buyer within his/her browser to one of the three redirection URLs specified during initialization: | ||
- | * successUrl: | + | |
- | * failUrl: | + | * failUrl: |
- | * backUrl: | + | * backUrl: |
+ | |||
+ | The success and fail URL are called via the POST method and obtain the same parameters specified for the notification above. | ||
+ | |||
+ | |||
+ | ===== Other transaction types ===== | ||
+ | These transactions reference a previous transaction. | ||
+ | In the case of the payment page, please bear in mind that these transaction types (capture and refund) will refer to the underlying transaction carried out previously and therefore the action is only admissible if the corresponding payment method supports this. | ||
+ | |||
+ | **Example: | ||
+ | |||
+ | If a payment link is used to pay an invoice and the customer chooses the payment method creditcard, this transaction may later be refunded through the use of the payment page transaction reference number. If the initial transaction was an authorization (reservation), | ||
+ | |||
+ | Furthermore it is important to be aware that depending on how the payment or donation page was initialized (especially regarding the single parameter), there may be several payments that were completed through the page. In this case, where more than one successful payment is associated to the payment page reference number, the optional parameter ' | ||
+ | |||
+ | **Provided by:** GiroCheckout \\ | ||
+ | **Called by:** Merchant \\ | ||
+ | |||
+ | ==== Workflow ==== | ||
+ | |||
+ | < | ||
+ | hide footbox | ||
+ | |||
+ | participant " | ||
+ | participant " | ||
+ | participant " | ||
+ | |||
+ | autonumber | ||
+ | |||
+ | shop -> girocheckout: | ||
+ | girocheckout -> cc: | ||
+ | cc -> girocheckout: | ||
+ | girocheckout -> shop: | ||
+ | |||
+ | center footer (c)2022 by S-Public Services GmbH | ||
+ | </ | ||
+ | |||
+ | - Shop sends reference to previous credit card transaction | ||
+ | - GiroCheckout sends transaction to credit card processor | ||
+ | - credit card processor transmits result to GiroCheckout | ||
+ | - Shop receives reply on transaction outcome ([[en: | ||
+ | |||
+ | ==== Capture ==== | ||
+ | {{page> | ||
+ | |||
+ | ==== Refund ==== | ||
+ | {{page> | ||
+ | |||
+ | === POST Parameters === | ||
+ | URL CAPTURE: https:// | ||
+ | URL REFUND: https:// | ||
+ | |||
+ | ^Name | ||
+ | |merchantId | ||
+ | |projectId | ||
+ | |merchantTxId | ||
+ | |amount | ||
+ | |currency | ||
+ | |reference | ||
+ | |purpose | ||
+ | |hash | ||
+ | |||
+ | == Example == | ||
+ | {{page> | ||
+ | |||
+ | === Reply === | ||
+ | The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialized. The response also includes a transaction id and other information about the transaction. | ||
+ | |||
+ | == Parameters == | ||
+ | ^Name | ||
+ | |rc | ||
+ | |msg |yes | ||
+ | |reference | ||
+ | |merchantTxId | ||
+ | |backendTxId | ||
+ | |amount | ||
+ | |currency | ||
+ | |resultPayment | ||
+ | ^HEADER parameter^^^^ | ||
+ | |hash | ||
+ | |||
+ | == Example in case of success == | ||
+ | {{page> | ||
+ | |||
+ | == Example in case of error == | ||
+ | {{page> | ||
- | All 3 URLs are called using the POST method and contain the same parameters described above for the notification call. | ||
- |