Girocheckout API

User Tools

Site Tools

Trace:
en:girocheckout:paypage: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:paypage:start [2017/03/20 15:27]
michaelheumann 		en:girocheckout:paypage:start [2025/06/04 14:44] (current)
michaelheumann
Line 1: Line 1:
 ~~NOCACHE~~ ~~NOCACHE~~
 ====== Payment Page ====== ====== Payment Page ======
 +
 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 8:
 **Example** **Example**
  
-{{:en:girocheckout:paypage:paypageen.png?600|Example Payment Page}}+{{:en:girocheckout:paypage:screenshotapi_en.png?800|Example Payment Page}} 
 + 
 + 
 +<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, by removing forbidden characters and crop the text to the maximum allowed length (please also see the documentations of the corresponding payment methods). For example, the final result for giropay will only contain characters that conform to the SEPA specification (see [[en:girocheckout:paypage:start#sepa_compliant_characters|SEPA compliant characters]]). 
 +</WRAP> 
 + 
 + 
 +==== Notes on 3-D Secure 2.0 ==== 
 + 
 +Since January 21st 2021, the 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 "tds2"), see [[en:girocheckout:paypage:start#payment_initialization_through_the_payment_page|transaction initialization]] further below. 
 + 
 +**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 + 
-  * eps +^ Payment method ^ Code ^ 
-  * iDEAL +| eps | 2 | 
-  * credit card +| iDEAL | 12 | 
-  * direct debit +| Credit card | 11 | 
-  * direct debit with block file +| Direct debit | 6 | 
-  * direct debit with guarantee +| Direct debit with lock file | 7 | 
-  * PayPal +| Bluecode | 26 | 
-  * paydirekt +| Maestro | 33 | 
-  * SOFORT Überweisung+| PayPal | 14 | 
 +| Klarna | 38 |  
 +| Direktüberweisung| 37 | 
 +| Apple Pay| 36 | 
 +| Google Pay| 39 | 
  
 ===== Payment initialization through the payment page ===== ===== Payment initialization through the payment page =====
Line 54: Line 76:
 shop -> customer: shop -> customer:
  
-center footer (c)2017 by GiroSolution AG+center footer (c)2022 by S-Public Services GmbH
 </uml> </uml>
  
   - Customer visits checkout section of the shop in order to pay for his order   - Customer visits checkout section of the shop in order to pay for his order
-  - Shop initializes a paypage transaction ([[girocheckout:paypage:start#initialization|Initialization]])+  - Shop initializes a paypage transaction ([[en:girocheckout:paypage:start#initialization|Initialization]])
   - GiroCheckout initializes transaction internally and returns paypage URL   - GiroCheckout initializes transaction internally and returns paypage URL
   - Shop redirects customer to the paypage, customer selects payment method   - Shop redirects customer to the paypage, customer selects payment method
Line 64: Line 86:
   - GiroCheckout returns URL of the payment form to the paypage   - GiroCheckout returns URL of the payment form to the paypage
   - Paypage redirects customer to the payment form of the payment processor, customer enters data and pays   - Paypage redirects customer to the payment form of the payment processor, customer enters data and pays
-  - Payment processor informs GiroCheckout about  Transaktionsausgang +  - Payment processor informs GiroCheckout about transaction result 
-  - GiroCheckout benachrichtigt Shop über Transaktionsausgang ([[girocheckout:paypage:start#benachrichtigung_ueber_den_zahlungsausgang|Benachrichtigung]]) +  - GiroCheckout notifies shop about transaction result ([[en:girocheckout:paypage:start#notification_about_transaction_result|Notification]]) 
-  - Shop verarbeitet Transaktionsausgang +  - Shop processes transaction result 
-  - Shop sendet HTTP Statuscode an GiroCheckout +  - Shop sends HTTP status code to GiroCheckout 
-  - GiroCheckout leitet Käufer zurück auf den Shop +  - GiroCheckout redirects customer back to the shop 
-  - Shop zeigt Kunde Ergebnis an+  - Shop displays result to customer
  
-===== API-Funktionen =====+===== API functions =====
  
-==== Initialisierung =====+==== Project request ==== 
 +In case you have the requirement of only offering in your payment or donation page payment methods associated to certain projects in your GiroCockpit, and letting someone choose these methods programmatically, you may use this request to obtain a list of all your projects. 
 +  
 +**URL:** https://payment.girosolution.de/girocheckout/api/v2/paypage/projects \\ 
 +**Provided by:** S-Public Services GmbH \\ 
 +**Called by:** Merchant
  
-=== POST Parameter ===+== POST Parameters == 
 +^Name           ^Mandatory  ^Type      ^Description   ^ 
 +|merchantId     |Yes  |Integer     |Merchant ID of a Paypage project | 
 +|projectId      |Yes  |Integer     |Project ID of a Paypage project | 
 +|hash           |Yes  |String(32)      |HMAC MD5 hash of all the parameter values in the call. See  [[en:girocheckout:general:start#hash_generation|hash generation]] | 
 + 
 +== Example == 
 +{{page>codesamples:paypage#projects.request&noheader&nofooter}} 
 + 
 +=== Response === 
 +The response consists of a JSON object. The field rc returns an error code. If rc = 0 is returned, the call was successful. In the response, you receive the element "projects" that contains the available projects. 
 + 
 +== Parameters == 
 +^Name           ^Mandatory  ^Type      ^Description   ^ 
 +|rc             |Yes       |Integer   |[[en:girocheckout:errorcodes|Error codes]] | 
 +|msg            |Yes       |String(255)    |Additional information in case of an error | 
 +|projects       |Optional |Array     |List of the GiroCockpit projects with the elements Project Id (id), Projekt name (name), the number of the corresponding payment method (paymethod, see [[en:girocheckout:paypage:start#supported_payment_methods|List of payment methods]]) and the mode (mode) = TEST or LIVE. | 
 +^HEADER Parameters^^^^ 
 +|hash           |Yes       |String(32)    |HMAC MD5 hash of all values of the response. See [[en:girocheckout:general:start#API_call_reply_to_the_merchant|hash on response]] | 
 + 
 +== Example == 
 +{{page>codesamples:paypage#projects.response&noheader&nofooter}} 
 + 
 + 
 +==== Initialization ===== 
 + 
 +=== POST Parameters ===
 URL https://payment.girosolution.de/girocheckout/api/v2/paypage/init  URL https://payment.girosolution.de/girocheckout/api/v2/paypage/init 
  
-^Name           ^Pflicht  ^Type        ^Beschreibung   ^ +^Name           ^Mandatory  ^Type        ^Description   ^ 
-|merchantId     |Ja  |Integer     |Händler-ID eines Maestro-Projekts | +|merchantId     |Yes  |Integer     |Merchant ID of a Paypage project | 
-|projectId      |Ja  |Integer     |Projekt-ID eines Maestro-Projekts | +|projectId      |Yes  |Integer     |Project ID of a Paypage project | 
-|merchantTxId   |Ja  |String(255) |Eindeutige Transaktions-ID des Händlers | +|merchantTxId   |Yes  |String(255) |Merchant's unique transaction ID. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /  | 
-|amount         |Ja  |Integer     |Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny | +|amount         |Yes  |Integer     |For currencies with decimals, specify the amount in the smallest currency unit, such as Cent, Penny, without decimals. This parameter is MANDATORY, except for donation pages with free amount entry or with at least one fixed amount (meaning it is optional if pagetype == 2 and (freeamount=1 or fixedvalues not empty)). | 
-|currency       |Ja  |String(3)   |Währung der Transaktion, gemäß [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]].\\ EUR = Euro | +|currency       |Yes  |String(3)   |Currency of the transaction, according to [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]].\\ EUR = Euro | 
-|purpose        |Ja  |String(20)  |Verwendungszweck der Transaktion. Diese Information erscheint auf der Kartenabrechnung bzw. dem Kontoauszug. Es sind nur SEPA-konforme Zeichen zulässig (s. [[girocheckout:paypage:start#sepa-konforme_zeichen|SEPA-konforme Zeichen]]) | +|purpose        |Yes  |String(50)  |Purpose of the transaction. This information is displayed on the card settlement or bank statement.  If pagetype=2 and projectlist is not empty, the placeholder {SPENDENPROJEKT} may be used, which is then filled with the name of the user-selected project. \\ Please note regarding maximum field length: 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 for giropay. \\ The final purpose text may be adapted by the payment page to fit the requirements, by removing forbidden characters and crop the text to the maximum allowed length (please also see the documentations of the corresponding payment methods). | 
-|description    |Optional |String(120)   |Beschreibung für die Bezahlung. Wird nur auf der Payment Page angezeigt. Zulässige Zeichen s. [[girocheckout:paypage:start#zulässige_beschreibungszeichen|Zulässige Beschreibungszeichen]]| +|description    |Optional |String(120)   |Description for the payment. Is only displayed on the payment page. Allowed characters see [[en:girocheckout:paypage:start#allowed_description_characters|Allowed description characters]]| 
-|type           |Optional |String(4) |Transaktionsart (siehe [[girocheckout:transactiontypes:start]]) \\ SALE = Verkauf wird sofort gebucht (default) \\ AUTH = Reservierung des Betrags (nicht bei allen Zahlarten verfügbar)| +|pagetype       |Optional |Integer |Type of the payment page to be generated: 0=normal API-Paypage (compatible to previous paymnent pages, default), 1=Payment page, 2=Donation page | 
-|locale         |Optional |String(4)   |Sprache der Payment Page \\ de = deutsch (default) \\ en = englisch | +|expirydate     |Optional |String(10) | Expiration date: \\  * Empty = payment page is always valid, \\  * YYYY-MM-DD = Date in format Year-Month-Day, payment page will be valid up to this date (until 23:59:59). \\  * YYYY-MM-DD hh:mm:ss = Date in format "Year-Month-Day Hour:Minute:Second" (where the time component is assumed to be for the CET timezone, or CEST in the European summer), payment page will be valid up to this date and time. \\ Only works for pagetype 1 or 2. \\ The option 'once' is **deprecated** and shouldn't be used anymore because it will not be available in a future API version.  Please use single=2 instead.| 
-|paymethods     |Optional |String    |Kommaseparierte Liste der Zahlarten, die angezeigt werden sollen. Wird hier nichts angegeben, werden alle beim Händler unterstützen Zahlarten zur Auswahl angeboten. Jede Zahlungsart ist als Zahl anzugeben, s. [[girocheckout:paypage:start#zahlungsarten|Zahlungsarten]]| +|single         |Optional |Integer   | Controls, whether and how the link may be reused. \\ 0 = Link may be used as often as needed (default) \\ 1 = Allows only one payment attempt for this payment link, no matter if successful or not \\ 2 = Payment page may only be used for one successful payment, afterwards it will be invalidated | 
-|pkn            |Optional |String    |Das Feld dient dazu eine erneute Transaktion, ohne erneute Eingabe der Kreditkarten- oder Lastschriftdaten, zu starten. \\ create = neue Pseudo-Kartennummer für die verwendete Kreditkarte/Kontoverbindung generieren. | +|timeout        |Optional | Integer | Allows to specify a timeout for the selection of a payment method on the payment page. The timeout is specified in seconds and becomes active, as soon as the page is loaded. It is displayed to the user as a countdown and forwards to an error page when it expires.  Reloading the page does NOT reset the timer, this can only be archieved by deleting the cookies. If the payment page was initialized with the parameter single=1, the link will be invalidated upon timeout expiration.  For certain payment methods (direct debit, Paypal, credit card), the timer is hidden as soon as the tile for that method is selected. In the background, it continues running, though, and becomes visible again if the user selects another payment method. For the mentioned 3 payment methods, there are separate timeout values that may be configured for each method through GiroCockpit (administrative users of GS only). | 
-|test           |Ja  |Integer     |1 = Zahlarten im Test-Modus werden angezeigt \\ 0 = Zahlarten im LIVE-Modus werden angezeigt | +|type           |Optional |String(4) |Transaction type (see [[en:girocheckout:transactiontypes:start]]) \\ SALE = Immediate payment (default) \\ AUTH = Amount reservation (not available for all payment methods)| 
-|successUrl     |Ja  |String      |URL, an die der Kunde nach erfolgreicher Zahlung weitergeleitet wird. | +|locale         |Optional |String(4)   |Language of the payment page \\ de = German (default) \\ en = English | 
-|backUrl        |Ja  |String      |URL, an die der Kunde weitergeleitet wird, wenn er auf Zurück klickt. | +|paymethods     |Optional |String    |Comma-separated list of the payment methods to be offered. If parameter is empty or not specified, all methods enabled by the merchant in GiroCockpit will be displayed. Specify each payment method as a number, see [[en:girocheckout:paypage:start#payment_methods|Payment methods]]| 
-|failUrl        |Ja  |String      |URL, an die der Kunde nach erfolgloser Zahlung weitergeleitet wird. | +|payprojects    |Optional |String    |Comma-separated list of the project IDs, whose payment methods are to be available on the payment page. If nothing is specified here, all projects of the merchant are used. The project IDs may either be obtained manually through GiroCockpit, or programatically via a call to the function [[girocheckout:paypage:start#project_request|Project Request]].| 
-|notifyUrl      |Optional  |String      |URL, an die in einer Server-to-Server-Verbindung die Payment Notification geschickt wird. | +|organization   |Optional |String(70)|Name of the organization offering the payment or donation page. If none specified, the merchant name from GiroCockpit is used.| 
-|hash           |Ja  |String      |HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |+|freeamount     |Optional |Integer   |Defines whether the payment page user may freely enter an amount (=1) or not (=0, default). | 
 +|fixedvalues    |Optional |JSON String    |JSON-encoded string that contains an array of all the amounts among which the user may select the one to be paid/donated, e.g. '["10000","20000","50050"]', all amounts are to be specified in cents.  If this field is empty, the content of the amount field is used as a only possible value. If this field contains values, the amount field is ignored! | 
 +|minamount      |Optional |Integer   |Minimum accepted value if free amount entry is allowed, i.e. freeamount=1. Specify the amount in the smallest currency unit, such as Cent, Penny, thus, without decimals. If this value is omitted, the default is 100 (meaning 1,00). | 
 +|maxamount      |Optional |Integer   |Maximum accepted value if free amount entry is allowed, i.e. freeamount=1. Specify the amount in the smallest currency unit, such as Cent, Penny, thus, without decimals. | 
 +|orderid        |Optional |String(20) |Only used when payment method is Paydirekt. If empty, the orderid is generated from the purpose field. Only sepa-compliant characters are allowed (see [[girocheckout:paypage:start#sepa_compliant_characters|SEPA-compliant characters]]) | 
 +|projectlist    |Optional |JSON String    |JSON-encoded string, that contains an array of projects (strings=project names), for which the donation page accepts donations. Only makes sense if pagetype=2. | 
 +|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           |Yes  |Integer     |1 = Display payment methods that are in test mode \\ 0 = Display payment methods that are in Live mode | 
 +|certdata       |Optional  | Integer | 1 = Offer form for entering donation certificate data \\ 0 = Do not offer the form (default) | 
 +|otherpayments  |Optional  | JSON String  | JSON-formatted array of objects, that allows for the integration of external payment methods into the payment page. Clicking on this payment method within the payment page, will redirect to the specified link directly, instead of being processed via the GiroCheckout gateway as in the case of the rest of the methods. Currently, only payment methods listed in the list of already supported payment methods are allowed here (see [[en:girocheckout:paypage:start#supported_payment_methods|Payment methods]]). \\ **Fields of the objects:** \\ **id**: Number of the payment method according to the list mentioned above. \\ **url**: Link to which the browser will be redirected on click. This link must contain everything that is required on behalf of the external payment provider (such as PayPal), so that the payment can be processed. The payment page does not carry out any string replacements or so. \\ **position**: Position that the new payment method will have within the full list of available payment methods on the page (>=1) \\ **Example (PayPal and credit card):** \\ <nowiki>[{"id":14, "url": "https://www.paypal.de/process/123456&param1=48399", "position":1}, {"id":11, "url":"https://www.visa.com/whatever", "position":2}]</nowiki> | 
 +|paydirektShoppingCartType |Optional | String(19)    |Type of the shopping cart for giropay and paydirekt payments (only new giropay-payments). 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). \\ If this parameter is not specified during initialization, but the buyer selects giropay or paydirekt as payment method, the following process is applied to set a default value: \\ 1) If this is a donation page as opposed to a payment page (pagetype=2), ANONYMOUS_DONATION is assumed. \\ 2) If the merchant is registered with S-Public Services as an authority, AUTHORITIES_PAYMENT is assumed. \\ 3) If the paydirekt address fields for first name, last name, postal code, city and country are set, MIXED is assumed. \\ 4) If none of the cases 1-3 are a match, MIXED is assumed as default and the fields mentioned above for MIXED expected to be given as well. | 
 +|paydirektShippingFirstName |Optional  | String(100)  | First name for shipping address (only for giropay and paydirekt payments, **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. |  
 +|paydirektShippingLastName  |Optional  | String(100)  | Last name for shipping address (only for giropay and paydirekt payments, **Mandatory** for shopping cart types PHYSICAL, DIGITAL and MIXED, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT). Permitted characters, see paydirektShippingFirstName. | 
 +|paydirektShippingCompany      |Optional   |String (100)   | Company name for shipping address (only for giropay and paydirekt payments). Permitted characters, see paydirektShippingFirstName. | 
 +|paydirektShippingAdditionalAddressInformation |Optional       |String(100) | Additional address information for shipping address (only for giropay and paydirekt payments). Permitted characters, see paydirektShippingFirstName. | 
 +|paydirektShippingStreet       |Optional      |String(100)    | Street name for shipping address (only for giropay and paydirekt payments). Permitted characters, see paydirektShippingFirstName. | 
 +|paydirektShippingStreetNumber |Optional    |String(10)    | Street number for shipping address (only for giropay and paydirekt payments). Permitted characters, see paydirektShippingFirstName. | 
 +|paydirektShippingZipCode  |Optional  | String(10)  | Zip code for shipping address (only for giropay and paydirekt payments, **Mandatory** for shopping cart types PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT). Permitted characters, see paydirektShippingFirstName. | 
 +|paydirektShippingCity  |Optional  | String(100)  | City for shipping address (only for giropay and paydirekt payments, **Mandatory** for shopping cart types PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT). Permitted characters, see paydirektShippingFirstName. | 
 +|paydirektShippingCountry  |Optional  | String(2)  | Country code (ISO 2 chars) for shipping address (only for giropay and paydirekt payments, **Mandatory** for shopping cart types PHYSICAL and MIXED, optional for DIGITAL, ANONYMOUS_DONATION and AUTHORITIES_PAYMENT). | 
 +|paydirektShippingEmail    |Optional  |String(255)   | Email address of the buyer (only for giropay and paydirekt payments, **Mandatory** for DIGITAL shopping carts, optional for all others) | 
 +|paydirektMerchantOrderReferenceNumber  |Optional         |String(20)    | Only for giropay payments. Additional information for the payment reconciliation for giropay payments, that is shown in the purpose on bank statements (only for type=SALE). Only characters that conform to the SEPA specification (see [[en:girocheckout:paypage:start#sepa_compliant_characters|SEPA compliant characters]]) are allowed. | 
 +|paydirektCart           |Optional      |JSON String | Only for giropay and paydirekt payments: All products in the shopping cart in the following format: [[en:girocheckout:paypage:start#cart_field|Description of cart field]] | 
 +|paydirektDeliveryType |Optional | String(12)    | Only for giropay payments. 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. | 
 +|successUrl     |Optional  |String(2048)      |URL where the customer is redirected to after successful payment. | 
 +|backUrl        |Optional  |String(2048)      |URL where the customer is redirected to after clicking the Back button. | 
 +|failUrl        |Optional  |String(2048)      |URL where the customer is redirected to after a failed payment. | 
 +|notifyUrl      |Optional  |String(2048)      |URL where the payment notification is sent to via server to server communication. | 
 +|tds2Address |optional |String(50) | For 3D Secure 2.0: Main address line (usually street and number) of the card holder's billing address, Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50. When specified, you must also specify the tds2-fields, except for tds2Optional.  | 
 +|tds2Postcode |optional |String(10) | For 3D Secure 2.0: Postal code of the card holder's billing address, Format A-Z, a-z, 0-9, Blank, [-], max. 11. When specified, you must also specify the tds2-fields, except for tds2Optional.  | 
 +|tds2City |optional |String(50) | For 3D Secure 2.0: City of the card holder's billing address, Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50. When specified, you must also specify the tds2-fields, except for tds2Optional.  | 
 +|tds2Country |optional |String(2) | For 3D Secure 2.0: Country of the card holder's billing address, Format A-Z, max. 2. Zweibuchstabiges Länderkürzel nach dem aktuell gültigen Standard ISO 3166. When specified, you must also specify the tds2-fields, except for tds2Optional. | 
 +|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:girocheckout:paypage:start#d_secure_20_optional_fields_tds2optional|3D Secure 2.0 Optional Fields (tds2Optional)]]. | 
 +|mandateReference | optional |String(35)  | mandate reference \\ if nothing is specified, a unique number is generated. The reply includes the mandate reference number. \\ 
 +    numbers: 0 – 9   
 +    characters: A – Z and a – z   
 +    special characters: & \ / = + , : ; . _ \ - ! ?  
 +| 
 +|mandateSignedOn | optional |String(10)| date (YYYY-MM-DD), when the SEPA mandate was placed. If no date is specified the current date will be used. | 
 +|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> <strong> <ul> <ol> <li> <dl> <dt> <dd>. It is important to know that - if the text contains an <a> tag - this link must include the protocol (http:%%//%% or https:%%//%%) and also a target attribute (usually target="_blank"),  The maximum length of the text (excluding the tags) is 300.\\ The aspect of the information box can be customized a little, but this requires the creation of a custom design of the Payment Page for this particular customer.  Please contact our support for more information about this. | 
 +|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. | 
 +|qrcodeReturn  |Optional |Integer      |Optional field that causes the generation of a QR code for the payment link. The code is then returned as a base64 encoded string (PNG image) in the return parameter "qrcode".  The value of qrcodeReturn is an integer between 1 and 20 and defines the size of the QR code (1=smallest size, 20=largest size). | 
 +|billingAddress  |Optional | JSON-String | Optional field for Klarna, Apple Pay and Google Pay that can contain the buyer's billing address. The individual fields can be found in the [[en:girocheckout:klarna:start#json_object_for_addresses|description on our Klarna page]]. | 
 +|shippingAddress |Optional | JSON-String | Optional field for Klarna, Apple Pay and Google Pay that can contain the buyer's shipping address. If this information is missing, the billing address will be used as the shipping address. The individual fields can be found in the [[en:girocheckout:klarna:start#json_object_for_addresses|description on our Klarna page]]. | 
 +|customerInfo    |Optional | JSON-String | Optional field for Klarna, Apple Pay and Google Pay that can contain additional information about the buyer. The individual fields can be found in the [[en:girocheckout:klarna:start#json_object_customerinfo|description on our Klarna page]]. | 
 +|basket          |Optional (mandatory for Klarna, Apple Pay and Google Pay)      | JSON-String | Mandatory field for Klarna, Apple Pay and Google Pay that describes the shopping cart. The individual fields can be found in the [[en:girocheckout:klarna:start#json_object_basket|description on our Klarna page]]. | 
 +|hash           |Yes  |String(32)      |HMAC MD5 hash of all the parameter values in the call. See  [[en:girocheckout:general:start#hash_generation|hash generation]] |
  
-=== SEPA-konforme Zeichen === +=== SEPA compliant characters === 
-{{page>girocheckout:paypage:sepa:start&noheader&nofooter}}+{{page>en:resources:sepa-chars&noheader&nofooter}}
  
-=== Zulässige Beschreibungszeichen === +=== Allowed description characters === 
-Folgende Zeichen sind für den Beschreibungstext (Feld description) zulässig: +The following characters are allowed in the description text (field description): 
-  * Alle Buchstaben aller Sprachen, also auch Umlaute und spanische Sonderzeichen usw. +  * All characrters of all languages, including German umlauts, Spanisch accented characters and so on. 
-  * Alle Satzzeichen +  * All punctuation characters 
-  * Alle Ziffern +  * All numerical digits 
-  * Symbole, die sich auf Währungen beziehen (also $ und € usw.) +  * Symbols referring to currencies (e.g. $ and € etc.) 
-  * Länge zwischen 1 und 60 Zeichen+  * Length between 1 and 60 characters
  
-=== Zahlungsarten === +=== 3D Secure 2.0 Optional Fields (tds2Optional) === 
-Dies sind die zulässigen Werten für die im Parameter paymethods anzugebenden Zahlungsarten:+This is a JSON formatted object that has a hierarchical structure (2 levels) and contains the following sub-objects:
  
-^ID           ^Zahlungsart   ^ +  * billingAddress 
-|1    | giropay | +  * shippingddress 
-|2    | eps | +  * homePhoneNumber 
-|6    | Lastschrift | +  * mobilePhoneNumber  
-|7    | Lastschrift mit Sperrdatei | +  * workPhoneNumber 
-|8    | Garantierte Lastschrift | +  * cardholderAccountInfo 
-|11   | Kreditkarte | +  * tdsMerchantRiskIndicators 
-|12   | iDEAL | +  * tdsRequestorAuthenticationInformation 
-|14   | PayPal | +  * tdsTransactionAttributes
-|23   | paydirekt | +
-|27   | SOFORT Überweisung |+
  
-== Beispiel ==+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's email address, Format A-Z, a-z, 0-9, [_.+-@], max. 254. | 
 +|addressesMatch |Boolean  | Specifies if the shipping address and billing address are the same (true) or not (false). Not a sub-object but a field directly in the main object. | 
 +^**//billingAddress//**  ^^^ 
 +|billingAddress.line2 |String(50) | Second line of the billing address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 | 
 +|billingAddress.line3 |String(50) | Third line of the billing address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 | 
 +|billingAddress.state |String(3) | Subdivision (state, province or the like) of a country according to ISO 3166-2. Format A-Z, max. 3. | 
 +^**//shippingAddress//**  ^^^ 
 +|shippingAddress.line1 |String(50) | First line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 | 
 +|shippingAddress.line2 |String(50) | Second line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 | 
 +|shippingAddress.line3 |String(50) | Third line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 | 
 +|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, [-/().,&'], max. 50 | 
 +|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//**  ^^^ 
 +|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//**  ^^^ 
 +|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//**  ^^^ 
 +|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//**  ^^^ 
 +|cardholderAccountInfo.accountAgeIndicator |String(12) | Indicates when the customer's payment account was created. Possible values: "never" - customer has no payment account, is e.g. shopping as a guest, "now" - customer created the payment account during the current shopping session, "less30" - payment account created less than 30 days ago, "more30less60" - payment account created at least 30 but less than 60 days ago, "more60" - payment account created at least 60 days ago. | 
 +|cardholderAccountInfo.passwordChangeIndicator |String(12) | Indicates when the password of the customer account was changed the last time. Possible values: "never" - the customer never changed his password, "now" - password changed during the current shopping session, "less30" - password changed less than 30 days ago, "more30less60" - password changed at least 30 but less than 60 days ago, "more60" - password has not been chan- ged for at least 60 days. | 
 +|cardholderAccountInfo.paymentAccountAgeIndicator |String(12) | Indicates when the customer's payment account was created. Possible values: "never" - customer has no payment account, is e.g. shopping as a guest, "now" - customer created the payment account during the current shopping session, "less30" - payment account created less than 30 days ago, "more30less60" - payment account created at least 30 but less than 60 days ago, "more60" - payment account created at least 60 days ago. | 
 +|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: "now" - Customer has changed his account during the current purchase, "less30" - Account was modified less than 30 days ago, "more30less60" - Account was modified at least 30 days ago but less than 60 days ago, "more60" - Customer account hasn't been changed in at least 60 days. | 
 +|cardholderAccountInfo.shippingAddressAgeIndicator |String(12) | Indicates when the customer first used the current shipping address. Possible values: "now" - customer uses shipping address for the first time, "less30" - shipping address first used less than 30 days ago, "more30less60" - shipping address first used at least 30 but less than 60 days ago, "more60" - shipping address first used at least 60 days ago. | 
 +|cardholderAccountInfo.shippingNameIndicator |String(9) | Specifies if the card holder's name is the same as the name of the shipping address. Possible values: "identical" - names are identical, "different" - names are different. | 
 +|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//**  ^^^ 
 +|tdsMerchantRiskIndicators.deliveryTimeframe |String(14) | Indicates when the customer will receive the merchandise. Possible values: "electronic" - immediate electronic delivery, "moreThanOneDay", "over- night", "sameDay". | 
 +|tdsMerchantRiskIndicators.deliveryEmailAddress |String(254) | Delivery email address of the customer in case of an electronic delivery. Format A-Z, a-z, 0-9, [_.+-@], max. 254. | 
 +|tdsMerchantRiskIndicators.giftCardAmount |Integer | Amount of a gift card in major currency unit, e.g. 123,45 EUR is 123. Format 0-9, max. 10. | 
 +|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: "available" - the merchandise is already available, "future" - the merchandise will be available in the future.| 
 +|tdsMerchantRiskIndicators.reorderItemsIndicator |String(9) | Indicates if the customer is reordering previously purchased merchandise: "first" - first time ordered, "reordered". | 
 +|tdsMerchantRiskIndicators.shippingIndicator |String(16) | Specifies where the merchandise is delivered to. Possible values: "digital" - di- gital delivery, "billingAddress" - to the billing address, "differentAddress" - to a different address, "verifiedAddress" - to a verfied address, "store" - to a store, "other" - something else. | 
 +^**//tdsRequestorAuthenticationInformation//**  ^^^ 
 +|tdsRequestorAuthenticationInformation.authenticationData |String(2048) | Authentication data of the customer. Format A-Z, a-z, 0-9 [!"#$%$'()*+,./:;<=>?@[\]%%^%%`{%%|%%}~-], max. 2048 | 
 +|tdsRequestorAuthenticationInformation.authenticationTimestamp |DateTime | Date and time when the customer authenticated in the shop. Format JJJJ-MM-TTTHH:mm:ss | 
 +|tdsRequestorAuthenticationInformation.authenticationMethod |String(17) | Specifies how the customer authenticated to the shop. Possile values: "none" - not at all, e.g. the customer is shopping as a guest, "ownCredentials" - the customer authenticated with his credentials, e.g. login name and password, "federatedId", "issuerCredentials", "thirdParty", "fido", "fidoSigned", "srcAs- surance". | 
 +^**//tdsTransactionAttributes//**  ^^^ 
 +|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: "purchase", "checkAccep- tance", "accountFunding", "quasiCash", "prepaidActivation". | 
 + 
 +== Example of a tds2Optional string (formatted for demonstration purposes, should normally be specified in one line) == 
 +<code> 
 +{ 
 +  "email": "myemail@example.com", 
 +  "addressesMatch": "false", 
 +  "billingAddress": { 
 +    "line2": "Beim Nachbarn klingeln", 
 +    "line3": "zw. 22-24 Uhr", 
 +    "state": "BW" 
 +  }, 
 +  "shippingAddress": { 
 +    "city": "Berlin", 
 +    "country": "DE", 
 +    "line1": "Unter den Linden 1", 
 +    "line2": "Brandenburger Tor", 
 +    "line3": "(linker Bogen)", 
 +    "state": "BER" 
 +  }, 
 +  "homePhoneNumber": { 
 +    "country": "49", 
 +    "regional": "75519209309" 
 +  }, 
 +  "mobilePhoneNumber": { 
 +    "country": "49", 
 +    "regional": "17093902978" 
 +  }, 
 +  "workPhoneNumber": { 
 +    "country": "49", 
 +    "regional": "8938928938" 
 +  }, 
 +  "cardholderAccountInfo": { 
 +    "accountAgeIndicator": "more30less60", 
 +    "passwordChangeIndicator": "never", 
 +    "paymentAccountAgeIndicator": "less30", 
 +    "accountChange": "now", 
 +    "shippingAddressAgeIndicator": "more60", 
 +    "shippingNameIndicator": "different", 
 +    "suspiciousAccountActivity": "false", 
 +    "provisioningDayCount": 10 
 +  }, 
 +  "tdsMerchantRiskIndicators": { 
 +    "deliveryTimeframe": "overnight", 
 +    "deliveryEmailAddress": "hans-mueller@example.com", 
 +    "giftCardAmount": 0, 
 +    "giftCardCount": 2, 
 +    "giftCardCurrency": "EUR", 
 +    "preOrderDate": "2020-12-20", 
 +    "preOrderPurchaseIndicator": "available", 
 +    "reorderItemsIndicator": "first", 
 +    "shippingIndicator": "store" 
 +  }, 
 +  "tdsRequestorAuthenticationInformation": { 
 +    "authenticationData": "123Hdajkd/dasjdkk", 
 +    "authenticationTimestamp": "2020-11-09T12:09:09", 
 +    "authenticationMethod": "ownCredentials" 
 +  }, 
 +  "tdsTransactionAttributes": { 
 +    "purchaseInstalmentData": 2, 
 +    "recurringExpiry": "2020-11-30", 
 +    "recurringFrequency": 1234, 
 +    "type": "quasiCash" 
 +  } 
 +} 
 +</code> 
 + 
 +== Example ==
 {{page>codesamples:paypage#transactionstart.request&noheader&nofooter}} {{page>codesamples:paypage#transactionstart.request&noheader&nofooter}}
  
-=== Antwort === +=== Response === 
-Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, wurde die Transaktion erfolgreich initialisiert. Sie bekommen als Antwort eine Referenznummer für die Payment Page und die redirectURL zum Formular zurück.+The response consists of a JSON object. The field rc returns an error code. If rc = 0 is returned, the transaction was successfully initialized. As a response, you receive a reference number for the payment page and the redirect URL that leads to the form.
  
-== Parameter ==  +== Parameters ==  
-^Name           ^Pflicht  ^Type      ^Beschreibung   ^ +^Name           ^Mandatory  ^Type      ^Description   ^ 
-|rc             |Ja       |Integer   |[[girocheckout:errorcodes|Fehlernummer]] | +|rc             |Yes       |Integer   |[[en:girocheckout:errorcodes|Error codes]] | 
-|msg            |Ja       |String    |zusätzliche Informationen im Fehlerfall | +|msg            |Yes       |String(255)    |Additional information in case of an error | 
-|reference      |Optional |String    |eindeutige Payment Page ID | +|reference      |Optional  |String(36)    |Unique payment page ID | 
-|redirect       |Optional |String    |URL zur Payment Page, an die der Kunde weitergeleitet werden muss.| +|url            |Optional  |String(255)    |URL to the payment page, that the customer is to be redirected to.| 
-^HEADER Parameter^^^^ +|qrcode         |Optional  |String    |Base64 encoded string, that contains a PNG image file with the QR code of the URL (see previous field). This field is only present when the parameter "qrcodeReturn" is specified during initialization. The size of the QR code is defined by a numerical value of 1-20 given in qrcodeReturn. | 
-|hash           |Ja       |String    |HMAC MD5 hash über alle Werte der Rückmeldung. Siehe [[girocheckout:general:start#uebermittlung_von_daten_ueber_einen_schnittstellenaufruf_an_den_haendler|hash der Rückantwort]] |+^HEADER Parameters^^^^ 
 +|hash           |Yes       |String(32)    |HMAC MD5 hash of all values of the response. See [[en:girocheckout:general:start#API_call_reply_to_the_merchant|hash on response]] |
  
-== Beispiel im Erfolgsfall ==+== Example in case of success ==
 {{page>codesamples:paypage#transactionstart.response.true&noheader&nofooter}} {{page>codesamples:paypage#transactionstart.response.true&noheader&nofooter}}
  
-== Beispiel im Fehlerfall ==+== Example in case of failure ==
 {{page>codesamples:paypage#transactionstart.response.false&noheader&nofooter}} {{page>codesamples:paypage#transactionstart.response.false&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>
 +
 +==== Notification about transaction result ====
 +
 +The result of a transaction is transmitted on 2 parallel paths. The notification and the redirect.
 +
 +=== Notification ===
 +
 +The first communication path is a host to host message sent to the URL specified in the parameter notifyUrl. This notification is used to inform the merchant about the result of the transaction, even if the buyer does not return to the shop page. This information can and should be used to update the transaction status in the shop. The result of the transaction can be found in the field gcResultPayment. 
 +
 +== Request ==
 +**URL:** notifyUrl from the payment page initialization \\
 +**Provided by:** Merchant \\
 +**Called by:** GiroCheckout \\
 +**Method:** GET
 +
 +^Name             ^Mandatory    ^  Type        ^Description   ^
 +|gcPaymethod      |Yes       |Integer     | ID of the payment method of the transaction, see [[en:girocheckout:paypage:start#payment_methods|Payment methods]] |
 +|gcType           |Yes       |String(4)      | Transaction type: \\ SALE \\ AUTH |
 +|gcProjectId      |Yes       |String(10)      | GiroCheckout project ID used for the transaction. |
 +|gcReference      |Yes       |String(36)      | GiroCheckout transaction ID |
 +|gcMerchantTxId   |Yes       |String(255)      | Merchant transaction ID |
 +|gcBackendTxId    |Yes       |String(36)      | Payment processor transaction ID |
 +|gcAmount         |Yes       |Integer     | For currencies with decimals, specify the amount in the smallest currency unit, such as Cent, Penny |
 +|gcCurrency       |Yes       |String(3)      | Currency |
 +|gcResultPayment  |Yes       |Integer     | [[en:girocheckout:resultcodes|Payment result codes]]|
 +|gcPkn            |Optional |String(50)      | Pseudo card number if pkn is active |
 +|gcCardnumber     |Optional |String(19)      | Masked credit card number if pkn is active |
 +|gcCardExpDate    |Optional |String(8)      | Credit card expiration date in the format month/year if pkn is active |
 +|gcAccountHolder  |Optional |String(255)      | Account holder for direct debit if pkn is active |
 +|gcIban           |Optional |String(36)      | IBAN for direct debit if pkn is active |
 +|gcHash           |Yes       |String(32)      | HMAC MD5 hash on all values of the call. See  [[en:girocheckout:general:start#hash_generation|hash generation]] |
 +
 +=== Redirect ===
 +
 +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: Is redirected to after successful payments.
 +  * failUrl: Is redirected to when the payment was not successful or the customer clicked the cancel button on the page of the payment provider (bank, credit card processor etc.).
 +  * backUrl: Is redirected to when the buyer has chosen not to go through with the payment and has clicked the back button on the payment page (please don't confuse this button with the cancel button of the payment method in the form displayed AFTER payment method selection, because that cancellation would then be a transaction abort that will be redirected to the failUrl).
 +
 +The success and fail URL are called via the POST method and obtain the same parameters specified for the notification above.  In case of the backUrl no payment method has been chosen yet and no transaction has been initialized, so in case of this URL it is only a regular browser redirect without further parameters.
 +
 +
 +===== Other transaction types =====
 +These transactions reference a previous transaction.  They are based on a server to server communication and require no customer interaction (data entry).
 +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), the same reference number may be used to trigger the capture of the reserved amount. However, if the customer made the payment with giropay instead, where there is no reservation or refund, these attempts will be denied with an error message.
 +
 +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 'txreference' must be specified, that will then contain the precise reference number of the payment transaction.  Remember that this number is returned in both notification and redirect of the payment transaction in the parameters 'gcReference' and 'reference', respectively).
 +
 +**Provided by:** GiroCheckout \\
 +**Called by:** Merchant \\
 +
 +==== Workflow ====
 +
 +<uml>
 +hide footbox
 +
 +participant "Shop" as shop
 +participant "GiroCheckout" as girocheckout
 +participant "Credit Card Processor" as cc
 +
 +autonumber
 +
 +shop -> girocheckout: 
 +girocheckout -> cc: 
 +cc -> girocheckout: 
 +girocheckout -> shop: 
 +
 +center footer (c)2022 by S-Public Services GmbH
 +</uml>
 +
 +  - 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:girocheckout:creditcard:start#notification_about_the_payment_result|Notification]])
 +
 +==== Capture ====
 +{{page>en:girocheckout:transactiontypes:descriptions#capture.desc&noheader&nofooter}}
 +
 +==== Refund ====
 +{{page>en:girocheckout:transactiontypes:descriptions#refund.desc&noheader&nofooter}}
 +
 +=== POST Parameters ===
 +URL CAPTURE: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture \\
 +URL REFUND: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund
 +
 +^Name           ^Mandatory  ^Type        ^Description   ^
 +|merchantId     |yes       |Integer     |Merchant ID |
 +|projectId      |yes       |Integer     |Project ID|
 +|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 & = + , : ; . _ ! ? # / |
 +|amount         |yes       |Integer     |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 according to [[http://de.wikipedia.org/wiki/ISO_4217#Aktuell_g.C3.BCltige_W.C3.A4hrungen|ISO 4217]].\\ EUR = Euro |
 +|reference      |yes       |String(36)      |GiroCheckout transaction ID from a previous transaction, which the capture or refund is for |
 +|purpose        |optional  |String(27)  |Purpose of the refund or capture. This information is printed on the credit card statement.|
 +|hash           |yes       |String(32)      |HMAC MD5 hash on the complete call. See [[en:girocheckout:general:start#hash_generation|hash generation]] |
 +
 +== Example ==
 +{{page>codesamples:creditcard#capture.request&noheader&nofooter}}
  
-==== Benachrichtigung über den Transaktionsausgang ====+=== 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.
  
-Der Ausgang einer Transaktion wird an die im successUrl- oder failUrl-Parameter angegebene URL übermittelt. Diese Rückmeldung dient dazu, dem Händler den Ausgang der Transaktion mitzuteilen. Durch diese Information kann der Transaktionsstatus beim Händler geändert werden.  +== Parameters == 
-Der Zahlungsausgang einer Transaktion steht im Feld gcResultPayment. +^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 | 
 +|merchantTxId   |yes       |String(255)      | Unique transaction id of the merchant | 
 +|backendTxId    |yes       |String(36)      | Payment processor transaction ID | 
 +|amount         |yes       |Integer     | 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]]) |
  
-=== Anfrage === +== Example in case of success == 
-**URL:** successUrl und failUrl aus der Payment-Page-Initialisierung \\ +{{page>codesamples:creditcard#capture.response.true&noheader&nofooter}}
-**Bereitzustellen von:** Händler \\ +
-**Aufzurufen von:** GiroCheckout +
-**Methode:** POST+
  
-^Name             ^Pflicht    ^  Typ        ^Beschreibung   ^ +== Example in case of error == 
-|gcPaymethod      |Ja       |Integer     | ID der Zahlungsart der Transaktion | +{{page>codesamples:creditcard#capture.response.false&noheader&nofooter}}
-|gcType           |Ja       |String      | Transaktionsart: \\ SALE \\ AUTH | +
-|gcProjectId      |Ja       |String      | GiroCheckout Projekt-Id, über die die Transaktion abgewickelt wurde. | +
-|gcReference      |Ja       |String      | GiroCheckout Transaktions-ID | +
-|gcMerchantTxId   |Ja       |String      | Händler Transaktions-ID | +
-|gcBackendTxId    |Ja       |String      | Zahlungsabwickler Transaktions-ID | +
-|gcAmount         |Ja       |Integer     | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny | +
-|gcCurrency       |Ja       |String      | Währung | +
-|gcResultPayment  |Ja       |Integer     | [[girocheckout:resultcodes#zahlungsausgang|Ergebniscodes der Zahlung]]| +
-|gcPkn            |Optional |String      | Pseudokartennummer, wenn pkn aktiv | +
-|gcCardnumber     |Optional |String      | Maskierte Kreditkartennummer, wenn pkn aktiv | +
-|gcCardExpDate    |Optional |String      | Gültigkeitsdatum der Kreditkarte im Format Monat/Jahr, wenn pkn aktiv | +
-|gcAccountHolder  |Optional |String      | Kontoinhaber bei Lastschrift, wenn pkn aktiv | +
-|gcIban           |Optional |String      | IBAN bei Lastschrift, wenn pkn aktiv | +
-|gcHash           |Ja       |String      | HMAC MD5 hash über alle Werte des Aufrufs. Siehe  [[girocheckout:general:start#hash_generieren|hash generieren]] |+
  
en/girocheckout/paypage/start.1490020068.txt.gz · Last modified: 2021/04/12 14:33

Page Tools