User Tools

Site Tools


Translations of this page:
en:girocheckout:creditcard:start

Credit Card

Notes on 3-D Secure 2.0

Since January 1st 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 (field names beginning with “tds2”), see transaction initialization further below.

The parameters related to 3D Secure 2.0 are subject to changes due to modifications in the EMVCo 3-D Secure specs.

Test data

3-D Secure 2.0

Since 3-D Secure 2.0, please use the following 3DS2 enabled cards.

Case Card number
Without card holder authorisation 4012001037167778
With card holder authorisation 4012001037664444
With 3DS Method 4005559876540
With 3DS Method and card holder authorisation 4012001036853337

Card holder: Any
Card verification code (CVC2/CVV): any 3-digit number (is not validated)
Expiration date: any future date

When asked for address data in the credit card form, any data may be entered into all fields. This data is not validated in test mode.

Transaction results

Result code Answer Description
4000 Successful transaction After entering the above data and considering the following information, the transaction is successful:
Integer amount between 1,00 and 99,00
4502 Aborted transaction After clicking the button cancel you create an aborted transaction.

Transaction types

Detailed information on the transaction types.

Reservation (AUTH)

A reservation is to be used when the actual fulfillment of an order takes place at a later time, but the order amount for the presented card (for credit card transactions) or the given account information (for Paydirekt payments and others) needs to be authorized beforehand at the time of the order. Once the reservation period has expired, the reservation is either booked or voided.

  • initial Transaction

AUTHCAPTUREVOIDREFUND

Sale

Use sale when the business case is complete, e.g. a shopping cart was offered, ordered and delivered to the customer. The customer's payment method is debited with the amount of the sale.

  • initial Transaction

SALEREFUNDVOID

Initialize credit card payment

After a successful initialization the merchant receives a reference number and a redirect link. The redirect link leads to the payment page. The customer (buyer) must be redirected to this link. This can be achieved by an HTTP redirect header, an HTML page with a corresponding meta tag or a JavaScript redirect.

Provided by: GiroCheckout
Called by: merchant

Workflow

CustomerShopGiroCheckoutCredit Card Processor1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 (c)2016 by GiroSolution AG

  1. Buyer selects payment type “credit card”
  2. Shop initializes credit card transaction (Initialization)
  3. GiroCheckout initializes transaction at CC processor
  4. Credit card processor transmits result to GiroCheckout
  5. Shop receives response about transaction outcome (transaction ends in case of error)
  6. Shop sends redirect URL to customer browser
  7. Customer browser redirects to credit card processor
  8. Credit card processor displays payment form
  9. Customer authorizes transaction
  10. Credit card processor carries out transaction
  11. Credit card processor transmits result to GiroCheckout
  12. GiroCheckout notifies Shop about transaction outcome (Notification)
  13. Shop processes transaction outcome
  14. Shop sends HTTP status code to GiroCheckout
  15. GiroCheckout sends merchant redirect (return to merchant page) to Credit card processor
  16. Customer clicks “Back to shop” (Return)

API functions

Overview

As shown in the workflow, different API calls are involved in a credit card transaction. During the payment process a 3D-Secure check may be applied as well, but this depends solely on the credit card issuing institute and does not affect merchant or PSP in any way.

  1. Initialize transaction
  2. 3D-Secure check (optional)
  3. Payment result notification to merchant
  4. Buyer redirection to the merchant (triggered by buyer)

Reservation/Sale

POST parameters

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, eg. Cent, Penny
currency yes String(3) currency
EUR = Euro
purpose yes String(40) purpose
type optional String(4) transaction type (see Transaction types)
SALE = Immediate booking (default)
AUTH = Reservation of amount
locale optional String(4) language of the credit card payment page
de = German (default)
en = English
es = Spanish
fr = French
it = Italian
ja = Japanese
pt = Portuguese
nl = Dutch
cs = Czech
sv = Swedish
da = Danish
pl = Polish
spde = German donation
spen = English donation
de_DE_stadtn = German communes
mobile optional Boolean optimised payment page for mobile devices
0 = no (default)
1 = yes
pkn optional String(50) This field is used process a transaction without re-entering the card data.
create = generate a new pseudo card number
[pseudo card number] = pkn of the masked card data (see pseudo card number)
recurring optional Boolean recurring payment
0 = no (default)
1 = yes
urlRedirect yes String(2048) URL, where the buyer has to be sent after payment
urlNotify yes String(2048) URL, where the notification has to be sent after payment
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 3D Secure 2.0 Optional Fields (tds2Optional).
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.
hash yes String (32) HMAC MD5 hash (see hash generation)

3D Secure 2.0 Optional Fields (tds2Optional)

This is a JSON formatted object that has a hierarchical structure (2 levels) and contains the following sub-objects:

  • billingAddress
  • shippingddress
  • homePhoneNumber
  • mobilePhoneNumber
  • workPhoneNumber
  • cardholderAccountInfo
  • tdsMerchantRiskIndicators
  • tdsRequestorAuthenticationInformation
  • tdsTransactionAttributes

Generally, the following fields (all optional) are available (fields in sub-objects are displayed as [sub-object name].[field]):

Name Type Description
email String(254) 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(245) 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(2048) 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(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)
{
  "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"
  }
}
Example of a transaction initialization
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "locale=de" \
     -d "mobile=0" \
     -d "pkn=create" \
     -d "recurring=0" \
     -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \
     -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \
     -d "hash=26fbe72bcc0b7cd0b024b2282e974583" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

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 a redirect URL to the payment page.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) additional information about the response code
reference optional String(36) unique GiroCheckout transaction ID
redirect optional String(2048) redirect URL to the payment page
HEADER parameter
hash yes String(36) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=wrlIRO9O30S4NNAO9h6uHwhyWibDFKUWeoWy7mPLDDyZ","rc":"0","msg":""}
Example in case of error
{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}

Notification about the payment result

The result of an initialized transaction will be submitted to the merchant through URL specified in the urlNotify parameter. This notification should be used to update the order status in the merchant's system.

The result of the payment is contained in the field gcResultPayment.

Request

URL: notifyUrl of the previous init transaction call
Provided by: Merchant
Called by: GiroCheckout

GET parameters
Name Mandatory Type Description
gcReference yes String(36) unique GiroCheckout transaction ID
gcMerchantTxId yes String(255) merchant transaction ID
gcBackendTxId yes String(22) payment processor transaction ID
gcAmount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
gcCurrency yes String(3) currency
gcResultPayment yes Integer Payment result codes
gcHash yes String(32) HMAC MD5 hash (see hash generation)

Reply

As a reply to the GET request, one of the following HTTP status codes is expected.

HTTP status code Description
200 (OK) The notification was processed correctly.
400 (Bad Request) The merchant did not process the notification and does not wish to be notified again.
All others The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400.

Redirection of the customer to merchant

After completing the payment, the customer may return to the merchant through a link. This return only happens once the customer clicks the “cancel” or “return to shop” button and is not done automatically.

Request

URL: redirectUrl of the previous init transaction call
Provided by: Merchant
Called by: GiroCheckout

GET parameters
Name Mandatory Type Description
gcReference yes String(36) unique GiroCheckout transaction ID
gcMerchantTxId yes String(255) merchant transaction ID
gcBackendTxId yes String(22) payment processor transaction ID
gcAmount yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, e.g. Cent, Penny
gcCurrency yes String(3) Currency
gcResultPayment yes Integer Payment result codes
gcHash yes String(32) HMAC MD5 hash (see hash generation)

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).

Provided by: GiroCheckout
Called by: Merchant

Workflow

ShopGiroCheckoutCredit Card Processor1 2 3 4 (c)2016 by GiroSolution AG

  1. Shop sends reference to previous credit card transaction
  2. GiroCheckout sends transaction to credit card processor
  3. credit card processor transmits result to GiroCheckout
  4. Shop receives reply on transaction outcome (Notification)

Capture

When booking, the customer account is debited with an amount and the merchant account is credited. This model is based on the assumption that the associated business case has been completed, e.g. a shopping cart was offered, ordered and delivered to the customer.

  • Condition: only reserved transactions may be booked
  • Amount ⇐ Reservation amount
  • Partial bookings are possible

Refund

A refund is to be used when a previous payment is to be returned fully or partially to the customer.

  • Condition: may only be applied to the following transaction types:
    • Reservation
    • Reservation/Booking
  • Amount ⇐ Transaction amount of the previous transaction

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 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.
kassenzeichen optional String(255) (Capture only) 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.
hash yes String(32) HMAC MD5 hash on the complete call. See hash generation
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/capture

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 Mandatory Type Description
rc yes Integer 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(22) 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 Payment result codes
HEADER parameter
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"7f18859d-7246-4181-8fb5-30ce7958f309","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1196307_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}
Example in case of error
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":"5200","rc":0,"msg":"Transaktion nicht akzeptiert"}

Void

Void is to be used when an already accepted transaction is not to be executed.

  • Condition: may only be applied to the following transaction types:
    • Reservation (as long as booking has not been done and reservation hasn't expired)
    • Reservation/Booking (only on the same day)
    • Refund (only on the same day)

POST Parameters

URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Name Mandatory Type Description
merchantId Yes Integer Merchant ID of a credit card project
projectId Yes Integer Project ID of a credit card project
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 & = + , : ; . _ ! ? # /
reference Yes String(36) GiroCheckout transaction ID that is to be voided
hash Yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Reply

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the call was successful. The response includes a transaction number and other information.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) Additional information about the response code
reference yes String(36) Unique GiroCheckout transaction ID
referenceParent yes String(36) GiroCheckout transaction ID of the original base transaction
merchantTxId yes String(255) Unique transaction id of the merchant
backendTxId yes String(22) Payment processor transaction ID
amount yes Integer Voided amount, 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 Payment result codes
HEADER parameter
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"ef27303f-87b3-465e-9c39-fabfb749d253","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1226723_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}
Example in case of failure
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}

Pseudo card numbers (PKN)

This function requires a separate implementation on PSP side which also generate a one-time implementation fee.

A pseudo card number is a reference to a credit card that has been used recently by the buyer (card number and expiration date). This reference allows the merchant to offer a previously used credit card for reuse by the customer. If the PKN is transmitted along during the initialization of a credit card transaction, the card number and expiration date is pre-filled in the payment form. The customer needs only to enter the validation code and may then carry out the payment.

Query pseudo card information

This function allows access to PKN information. It returns as a result both the PKN and the saved credit card information (masked credit card number, expiration date), which were used for a previous transaction.

URL: https://payment.girosolution.de/girocheckout/api/v2/creditcard/pkninfo
Provided by: GiroCheckout
Called by: Merchant

POST Parameters

Name Mandatory Type Description
merchantId yes Integer Merchant ID
projectId yes Integer Project ID
reference yes String(36) Unique reference to a GiroCheckout transaction
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "reference=6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f" \
     -d "hash=dc1686b621c9cc15bd271390c694258d" \
     https://payment.girosolution.de/girocheckout/api/v2/creditcard/pkninfo

Reply

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the call was successful. The response includes the PKN number, the (masked) credit card number and the expiration date.

Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) Additional information about the response code
pkn yes String(50) Pseudo card number
cardnumber yes String(19) Masked credit card number, e.g. 411111******1111
expiremonth yes String(2) Month of the credit card's expiration date
expireyear yes String(4) Year of the credit card's expiration date
HEADER Parameter
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"pkn":"ad5c386b38cc9aeb839705d1d10da499","cardnumber":"411111******1111","expiremonth":"2","expireyear":"2016","rc":0,"msg":""}
Example in case of error
{"pkn":null,"cardnumber":null,"expiremonth":null,"expireyear":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}

Recurring credit card payment

The transaction data is transmitted and the result of the credit card payment is returned immediately. This function is used for recurring credit card payments, such as subscriptions.

The following steps are necessary to implement a recurring payment:

  1. Carry out a normal credit card transaction (see Initialize Payment)
  2. Obtain pseudo card number (PKN) (see Query PKN information)
  3. Store this PKN
  4. On the next recurring payment, initialize a payment transaction (use correct end point, see Recurring or PKN transaction), but set parameter pkn and let recurring=1.

Recurring transaction

In order to carry out a recurring payment without customer intervention, use the following function.

POST Parameters

URL https://payment.girosolution.de/girocheckout/api/v2/transaction/payment

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, eg. Cent, Penny
currency yes String(3) currency
EUR = Euro
purpose yes String(40) purpose
type optional String(4) transaction type (see Transaction types)
SALE = Immediate booking (default)
AUTH = Reservation of amount
pkn optional String(50) This field is used process a transaction without re-entering the card data.
[pseudo card number] = pkn of the masked card data (see pseudo card number)
recurring optional Boolean recurring payment
0 = no (default)
1 = yes
urlNotify yes String(2048) URL, where the notification has to be sent after payment
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.
hash yes String(32) HMAC MD5 hash (see hash generation)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "pkn=ad5c386b38cc9aeb839705d1d10da499" \
     -d "recurring=0" \
     -d "hash=0361f14f7b1be9be16326b2edd925853" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/payment

Reply

The reply is a JSON encoded string. The field rc contains the response code. If it is 0 the call was successful.

Parameters

Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) Additional information about the response code
reference yes String(36) Unique GiroCheckout transaction ID
backendTxId yes String(22) Payment processor transaction ID
resultPayment yes Integer Payment result codes
HEADER parameter
hash yes String(32) HMAC MD5 hash on the complete JSON string. (see api call reply)
Example in case of success
{"reference":"7f18859d-7246-4181-8fb5-30ce7958f309","backendTxId":"1196307_01","resultPayment":"4000","rc":0,"msg":""}
Example in case of error
{"reference":"fb70602d-c137-4413-8432-7dcc69a9d891","backendTxId":"","resultPayment":"4106","rc":0,"msg":"Pseudo-Kartennummer ungültig "}

Retrieve sender information

This service allows the retrieval of the information associated to the sender of a completed transaction. As a response to the given reference number, the account holder, masked card number, expiration date and card brand of the customer card are returned.

API call

URL: https://payment.girosolution.de/girocheckout/api/v2/creditcard/senderinfo
Provided by: GiroCheckout
Called by: Merchant

POST Parameters
Name Mandatory Type Description
merchantId Yes Integer merchant ID of a creditcard project
projectId Yes Integer project ID of a creditcard project
reference Yes String(36)GiroCheckout transaction ID
hash Yes String(32)HMAC MD5 hash of the full JSON string. (see api call reply)
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "reference=9ce6c641-4082-4f75-ae54-333309febcc5" \
     -d "hash=246d1fa2ed97ecff895de974c560f9ec" \
     https://payment.girosolution.de/girocheckout/api/v2/creditcard/senderinfo

Response

The response is a JSON object. The rc field returns an error code. If rc = 0 is returned, the corresponding fields contain the sender information.

JSON Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String(255) additional information about the response code in case of error
accountholder Optional String(255) Account holder of the sender account
pan Optional String(50) Masked credit card number
expdate Optional String(7) Expiration date of the card (format mm/yyyy)
brand Optional String(7) Brand name of the card, such as VISA
HEADER parameter
hash yes String(32) HMAC MD5 hash of the full JSON string. (see api call reply)
Example in case of success

hash : cde71b6b98e8dae709fdc1e17aef885f

{"accountholder":"Max Mustermann","pan":"401200******4444","expdate":"09/2023","brand":"VISA","rc":0,"msg":""}
Example in case of error

hash : f1d186103b8c4cb59c54ae7b987a9d4c

{"accountholder":null,"pan":null,"expdate":null,"brand":"","rc":5034,"msg":"Transaktion nicht vorhanden"}
en/girocheckout/creditcard/start.txt · Last modified: 2023/05/08 04:04

Page Tools