Integration
Apple Pay
Bluecode
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal
Tools
Error codes
Result codes
Test data
Apple Pay
Bluecode
Credit Card
Direct Debit
Direktüberweisung
eps
Google Pay
iDEAL
Klarna
Maestro
Payment Page
PayPal
Tools
Error codes
Result codes
Test data
This is an old revision of the document!
This document describes all flows and interfaces that are required for an integration of the GiroCheckout Payment Page.
This payment page allows for a much simpler integration of shops with GiroCheckout, without the need to configure each payment method separately within the shop. The GiroCheckout Payment Page offers the customer all payment methods available to the merchant for selection and then initializes the selected payment accordingly.
Starting this January 21st 2021, the new security procedure for credit card payments “3D Secure 2.0” - introduced within the PSD2 efforts - becomes mandatory for all payment providers. This API documentation already contains the fields necessary for this (starting with “tds2”), but the API itself will likely be only available in the final third of December 2020.
Example
The following payment methods are currently supported:
Payment method | Code |
---|---|
giropay | 1 |
giropay-ID + giropay | 17 |
giropay with payment confirmation | 18 |
eps | 2 |
iDEAL | 12 |
Credit card | 11 |
Direct debit | 6 |
Direct debit with lock file | 7 |
Bluecode | 26 |
Maestro | 33 |
PayPal | 14 |
paydirekt | 23 |
SOFORT-Überweisung | 27 |
A payment page needs to be initialized so that a URL to the payment page can be generated. This payment page URL is the result of a successful payment page initialization. The customer must be redirected to this URL afterwards.
Provided by: GiroCheckout
Called by: Merchant
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: GiroSolution
Called by: Merchant
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 | HMAC MD5 hash of all the parameter values in the call. See hash generation |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \ https://payment.girosolution.de/girocheckout/api/v2/paypage/projects
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.
Name | Mandatory | Type | Description |
---|---|---|---|
rc | Yes | Integer | Error codes |
msg | Yes | String | 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 List of payment methods) and the mode (mode) = TEST or LIVE. |
HEADER Parameters | |||
hash | Yes | String | HMAC MD5 hash of all values of the response. See hash on response |
{"projects":[{"id":"12345","name":"iDEAL - ICEPAY","paymethod":"12","mode":"LIVE"},{"id":"12346","name":"giropay","paymethod":"1","mode":"TEST"},{"id":"12347","name":"Kreditkarte","paymethod":"11","mode":"TEST"}],"rc":0,"msg":""}
URL https://payment.girosolution.de/girocheckout/api/v2/paypage/init
Name | Mandatory | Type | Description |
---|---|---|---|
merchantId | Yes | Integer | Merchant ID of a Paypage project |
projectId | Yes | Integer | Project ID of a Paypage project |
merchantTxId | Yes | String(255) | Merchant's unique transaction ID |
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 | Yes | String(3) | Currency of the transaction, according to ISO 4217. EUR = Euro |
purpose | Yes | String(27) | Purpose of the transaction. This information is displayed on the card settlement or bank statement. Only SEPA compliant characters are allowed (see SEPA compliant characters). 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. The content of this field (first 20 characters) is also used to fill the orderid in case of the payment method Paydirekt, if it is not explicitly specified (see parameter orderid). |
description | Optional | String(120) | Description for the payment. Is only displayed on the payment page. Allowed characters see Allowed description characters |
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 |
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. 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. |
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 |
timeout | Optional | Integer | (Available from API v. 2.1.33) 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). |
type | Optional | String(4) | Transaction type (see Transaction types) SALE = Immediate payment (default) AUTH = Amount reservation (not available for all payment methods) |
locale | Optional | String(4) | Language of the payment page de = German (default) en = English |
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 Payment methods |
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 Project Request. |
organization | Optional | String(70) | Name of the organization offering the payment or donation page. If none specified, the merchant name from GiroCockpit is used. |
freeamount | Optional | Integer | Defines whether the payment page user may freely enter an amount (=1) or not (=0, default). |
fixedvalues | Optional | 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 SEPA-compliant characters) |
projectlist | Optional | 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 | 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 | 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 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): [{"id":14, "url": "https://www.paypal.de/process/123456¶m1=48399", "position":1}, {"id":11, "url":"https://www.visa.com/whatever", "position":2}] |
paydirektShippingFirstName | Optional | String(100) | First name for shipping address (only paydirekt PHYSICAL orders) |
paydirektShippingLastName | Optional | String(100) | Last name for shipping address (only paydirekt PHYSICAL orders) |
paydirektShippingZipCode | Optional | String(10) | Zip code for shipping address (only paydirekt PHYSICAL orders) |
paydirektShippingCity | Optional | String(100) | City for shipping address (only paydirekt PHYSICAL orders) |
paydirektShippingCountry | Optional | String(2) | Country code (ISO 2 chars) for shipping address (only paydirekt PHYSICAL orders) |
successUrl | Optional | String | URL where the customer is redirected to after successful payment. |
backUrl | Optional | String | URL where the customer is redirected to after clicking the Back button. |
failUrl | Optional | String | URL where the customer is redirected to after a failed payment. |
notifyUrl | Optional | String | URL where the payment notification is sent to via server to server communication. |
tds2Address | optional | String | 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 | 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 | 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 | 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. |
tds2Email | optional | String | For Secure 2.0: The card holder's email address, Format A-Z, a-z, 0-9, [_.+-@], max. 254. When specified, you must also specify the tds2-fields, except for tds2Optional. |
tds2Optional | optional | 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 3D Secure 2.0 Optional Fields (tds2Optional). |
hash | Yes | String | HMAC MD5 hash of all the parameter values in the call. See hash generation |
In SEPA payments, according to Annex 3 of this document, only characters of the limited SWIFT Latin characters set are allowed:
The following characters are allowed in the description text (field description):
This is a JSON formatted object that has a hierarchical structure (2 levels) and contains the following sub-objects:
Generally, the following fields (all optional) are available (fields in sub-objects are displayed as [sub-object name].[field]):
Name | Type | Description |
---|---|---|
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 | Second line of the billing address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 |
billingAddress.line3 | String | Third line of the billing address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 |
billingAddress.state | String | Subdivision (state, province or the like) of a country according to ISO 3166-2. Format A-Z, max. 3. |
shippingAddress | ||
shippingAddress.line1 | String | First line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 |
shippingAddress.line2 | String | Second line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 |
shippingAddress.line3 | String | Third line of the shipping address. Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 |
shippingAddress.postcode | String | Postal code of the shipping address, Format A-Z, a-z, 0-9, Blank, [-], max. 11 |
shippingAddress.city | String | City of the shipping address, Format A-Z, a-z, 0-9, Blank, [-/().,&'], max. 50 |
shippingAddress.state | String | Subdivision (state, province or the like) of a country according to ISO 3166-2. Format A-Z, max. 3 |
shippingAddress.country | String | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | Indicates when the customer will receive the merchandise. Possible values: “electronic” - immediate electronic delivery, “moreThanOneDay”, “over- night”, “sameDay”. |
tdsMerchantRiskIndicators.deliveryEmailAddress | String | 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 | Possible values: “available” - the merchandise is already available, “future” - the merchandise will be available in the future. |
tdsMerchantRiskIndicators.reorderItemsIndicator | String | Indicates if the customer is reordering previously purchased merchandise: “first” - first time ordered, “reordered”. |
tdsMerchantRiskIndicators.shippingIndicator | String | 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 | 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 | 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 | Type of 3-D Secure 2.0 payment. Possible values: “purchase”, “checkAccep- tance”, “accountFunding”, “quasiCash”, “prepaidActivation”. |
tdsBrowserData | ||
tdsBrowserData.browserAcceptHeader | String | “Accept” HTTP header of the customer's browser Format A-Z, a-z, 0-9, [/;=-], max. 80. |
tdsBrowserData.browserColorDepth | Integer | Colour depth of the customer's browser in bit. Valid values: 1, 4, 8, 15, 16, 24, 32, 48. |
tdsBrowserData.browserIP | String | IP address (IPv4 or IPv6) of the customer's browser. Format A-Z, a-z, 0-9, [.:], max. 39. |
tdsBrowserData.browserJavaEnabled | Boolean | Specifies if Java is active in the customer's browser (true) or not (false). |
tdsBrowserData.browserJavaScriptEnabled | Boolean | Specifies if JavaScript is active in the customer's browser (true) or not (false). |
tdsBrowserData.browserLanguage | String | Language of the customer's browser. Format A-Z, a-z, [-], Max. 8., Bsp. en-US |
tdsBrowserData.browserScreenHeight | Integer | Height of the customer's screen in pixels. Format 0-9, Max. 6. |
tdsBrowserData.browserScreenWidth | Integer | Width of the customer's screen in pixels. Format 0-9, Max. 6. |
tdsBrowserData.browserTimeZone | Integer | Time zone offset in minutes between UTC and the local time of the custo- mer's browser. Is returned from the getTimezoneOffset() JavaScript method. A value of -120 for example corresponds to the local time zone UTC +2 hours. Format 0-9, [-], Max. 5. |
tdsBrowserData.browserUserAgent | String | “User-Agent” HTTP header of the customer's browser. Format A-Z, a-z, Blank, [().:;/,_-], Max. 2048. |
tdsCommunicationData | ||
tdsCommunicationData.cResNotificationURL | String | URL of the shop, to which the ACS should send the CRes message. Format A-Z, a-z, 0-9, [:./-?;&=%], Max. 2048. |
tdsCommunicationData.methodNotificationURL | String | URL of the shop where the ACS should send the notification about the ”3DS Method”. Format A-Z, a-z, 0-9, [:./-?;&=%], Max. 2048. |
tdsCommunicationData.challengeWindowSize | String | Size of the window which is displayed to the customer to authorise a 3-D Se- cure 2.0 payment. If not submitted, “FullScreen” is used as default value. |
{ "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" }, "tdsBrowserData": { "browserAcceptHeader": "anything", "browserColorDepth": 24, "browserIP": "192.168.0.43", "browserJavaEnabled": "true", "browserJavaScriptEnabled": "true", "browserLanguage": "en-US", "browserScreenHeight": 2048, "browserScreenWidth": 4096, "browserTimeZone": "120", "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0" }, "tdsCommunicationData": { "cResNotificationURL": "https://www.example.com/resnot.php?param1=value1¶m2=value2", "methodNotificationURL": "https://www.example.com/methnot.php?param1=value1¶m2=value2", "challengeWindowSize": "FullScreen" } }
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "amount=100" \ -d "currency=EUR" \ -d "purpose=Beispieltransaktion" \ -d "description=Fahrradleuchte klein" \ -d "type=SALE" \ -d "locale=de" \ -d "paymethods=1,2,6,11,14" \ -d "test=1" \ -d "successUrl=http://www.my-domain.de/girocheckout/success" \ -d "backUrl=http://www.my-domain.de/girocheckout/back" \ -d "failUrl=http://www.my-domain.de/girocheckout/fail" \ -d "notifyUrl=http://www.my-domain.de/girocheckout/notify" \ -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \ https://payment.girosolution.de/girocheckout/api/v2/paypage/init
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.
Name | Mandatory | Type | Description |
---|---|---|---|
rc | Yes | Integer | Error codes |
msg | Yes | String | Additional information in case of an error |
reference | Optional | String | Unique payment page ID |
url | Optional | String | URL to the payment page, that the customer is to be redirected to. |
HEADER Parameters | |||
hash | Yes | String | HMAC MD5 hash of all values of the response. See hash on response |
hash : 6c4da0504e8e6a359c7f2df86cb5318d
{"reference":"4f88b6c8-6209-4c96-a450-b6de22633f6b","url":"http:\/\/pay.girosolution.de\/v1\/paypage\/en\/EG-ddvXSrAHmXRClBeamKGAyzXU-uAYbNYFLQ3uz_zj_J4rYCb0GIrWIQ-H_g8h3_-yf3WvSenh2Dg6TLhmTAA","rc":0,"msg":""}
hash : f55ce87e132ebb7eb20004c6b186ce09
{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}
The result of a transaction is transmitted on 2 parallel paths. The notification and the redirect.
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.
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 |
gcType | Yes | String | Transaction type: SALE AUTH |
gcProjectId | Yes | String | GiroCheckout project ID used for the transaction. |
gcReference | Yes | String | GiroCheckout transaction ID |
gcMerchantTxId | Yes | String | Merchant transaction ID |
gcBackendTxId | Yes | String | 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 | Currency |
gcResultPayment | Yes | Integer | Payment result codes |
gcPkn | Optional | String | Pseudo card number if pkn is active |
gcCardnumber | Optional | String | Masked credit card number if pkn is active |
gcCardExpDate | Optional | String | Credit card expiration date in the format month/year if pkn is active |
gcAccountHolder | Optional | String | Account holder for direct debit if pkn is active |
gcIban | Optional | String | IBAN for direct debit if pkn is active |
gcHash | Yes | String | HMAC MD5 hash on all values of the call. See hash generation |
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 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.