Table of Contents

Paydirekt

Test data

For login on https://sandbox.paydirekt.de/checkout/#/checkout in order to authorize a test transaction:

User Condition User name Password
Standard Buyer TESTGiroSolution_SDE-KaeuferSDE-Kaeufer2$
Age - Buyer under 18 TESTGiroSolution_unterAchtzehnunterAchtzehn2$
Buyer invalidated at paydirekt KaeuferGesperrtKaeuferGesperrt2$
Buyer invalidated at his bank TESTGiroSolution_SperreKBSperreKB2$

Please take into account the following test cases:

  • Normal payment (0,01 Euros < Amount < 500 Euros), except the amounts specified below
  • Payment is not authorized (Amount > 500 Euros)
  • Payment with two factor authentication (Amount 1 EUR=iTAN, 2 EUR=mTAN, 3 EUR=Phooto-TAN, 4 EUR=Chip-TAN or 5 EUR=App-confirmation), please note warning about this below.
  • Amounts 158,72 EUR - 99,77 EUR - 301,50 EUR - 300,50 EUR: Internal test cases at Paydirekt, please don't use!

2FA = Second Factor (authentication through a second channel)
Not all of the mentioned 2FA methods are usable with all of the test accounts and may lead to payment aborts. Generally, no useful test cases for merchants may be derived from these test amounts (because these processes run entirely on Paydirekt side).

Transaction types

Detailed information regarding Transaction types.

SALEAUTHREFUNDCAPTUREREFUND

Initialization of a Paydirekt payment

A successful initialization generates a reference number and a redirect link, which are both returned to the merchant. The redirect link will lead the customer to the payment form, so the merchant must ensure the proper redirection. This may be accomplished through an HTTP redirect header, an HTML page with a corresponding meta tag or via Javascript.

Provided by: GiroCheckout
Called by: Merchant

Workflow

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

  1. Customer chooses payment method Paydirekt
  2. Shop initiates Paydirekt transaction (Initialization)
  3. GiroCheckout initializes transaction at Paydirekt
  4. Paydirekt sends result to GiroCheckout
  5. Shop receives feedback on initialization result (transaction ends on error)
  6. Shop sends redirect URL to customer browser
  7. Customer browser redirects to Paydirekt
  8. Paydirekt display payment form
  9. Customer authorizes transaction
  10. Paydirekt carries out the transaction
  11. Paydirekt transmits result to GiroCheckout
  12. GiroCheckout informs Shop about transaction result (Notification)
  13. Shop processes transaction result
  14. Shop sends HTTP status code to GiroCheckout
  15. GiroCheckout sends merchant return address to Paydirekt
  16. Customer clicks “Back to Shop” (Return)

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

AUTHcapturerefund

Reservation/Booking (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

SALErefund

POST Parameters

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

Name Mandatory Type Description
AUTH SALE
merchantId Yes Yes Integer Merchant ID of a Paydirekt project
projectId Yes Yes Integer Project ID of a Paydirekt project
merchantTxId Yes Yes String(255) The merchant's unique transaction ID. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount Yes Yes Integer For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny
currency Yes Yes String(3) Currency of the transaction according to ISO 4217.
EUR = Euro
purpose Yes Yes String(37) Purpose of the transaction. This information appears on the accounting reports.
type Yes Optional String(4) Transaction type (see Transaction types)
SALE = Sale is booked immediately (default)
AUTH = Reservation of the amount
securedAuth Optional n/a Integer Allows the creation of a secured reservation. This setting only makes sense when type=AUTH and is otherwise ignored. 1 = create secured reservation/order, 0 = create standard reservation/authorization (default).
With reference to a secured reservation with partial payments, one or more captures may be triggered immediately afterwards or at a later point. A payment guarantee for the specified time frame (max. 15 calendar days, see securedAuthUntil) is granted to the merchant for a secured reservation. Captures (partial or full) will always be executed within the warranty period.
securedAuthUntil Optional n/a String(10) Maximum date for the secured reservation, i.e. the date until which the reservation is secured. The specified date may not be further in the future than 15 calendar days. Format: YYYY-MM-DD. This option only makes sense, if type=AUTH and securedAuth=1.
shoppingCartType Optional Optional String(19) Type of the shopping cart. The following values are permitted:
PHYSICAL = All items in the cart are physical (this is the default value if the parameter is not specified),
DIGITAL = All items in the cart are digital (so they don't require a dispatch service),
MIXED = The cart contains both physical and digital items,
ANONYMOUS_DONATION = This is an anonymous donation (no adress data required),
AUTHORITIES_PAYMENT = This is a payment operation to the authorities (e-Government, no address data required)
customerId Optional Optional String(20) Customer number , max. length: 20
shippingAmount Optional Optional Integer Shipping costs. For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny
shippingAddresseFirstName (see descr.) (see descr.) String(100) First name of the receiver, mandatory for cart types MIXED, PHYSICAL and DIGITAL, 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.
shippingAddresseLastName (see descr.) (see descr.) String(100) Last name of the receiver, mandatory for cart types MIXED, PHYSICAL and DIGITAL, optional for ANONYMOUS_DONATION and AUTHORITIES_PAYMENT. Permitted characters, see shippingAddresseFirstName.
shippingCompany Optional Optional String(100) Company name. Permitted characters, see shippingAddresseFirstName.
shippingAdditionalAddressInformation Optional Optional String(199) Additional address info. Permitted characters, see shippingAddresseFirstName.
shippingStreet Optional Optional String(100) Street of the receiver's address. Permitted characters, see shippingAddresseFirstName.
shippingStreetNumber Optional Optional String(10) Street number of the receiver's address. Permitted characters, see shippingAddresseFirstName.
shippingZipCode (see descr.) (see descr.) String(10) Zip code of the receiver's address. This field is mandatory for carts of type PHYSICAL and MIXED, optional for the others. Permitted characters, see shippingAddresseFirstName.
shippingCity (see descr.) (see descr.) String(100) City of the receiver's address. This field is mandatory for carts of type PHYSICAL and MIXED, optional for the others. Permitted characters, see shippingAddresseFirstName.
shippingCountry (see descr.) (see descr.) String(2) Country code (ISO 3166-1). This field is mandatory for carts of type PHYSICAL and MIXED, optional for the others.
shippingEmail (see descr.) (see descr.) String(255) Email address of the buyer. This field is mandatory for carts of type DIGITAL only, optional for the others.
merchantReconciliationReferenceNumber Optional String(30) Additional information for the payment reconciliation that is shown in the purpose on bank statements (only for type=SALE)
orderAmount Optional Optional Integer Amount of the order (excluding shipping costs), for currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny
orderId Yes Yes String(20) Order number, allowed characters: A-Z a-z 0-9 + ? / - : ( ) . , ' (blank)
cart Optional Optional JSON String All elements contained in the shopping cart in the following format: Cart
invoiceId Optional Optional String(20) Invoice number
customerMail Optional Optional String(255) Customer email address
minimumAge Optional OptionalInteger Minimum customer age required for the transaction, if any
urlRedirect Yes Yes String(2048) URL where the customer is to be redirected after the payment.
urlNotify Yes Yes String(2048) URL where the payment result should be informed (notify).
kassenzeichen Optional 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 Yes String(32) HMAC MD5 hash on all the valus of the request. See Generate hash
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=10000" \
     -d "currency=EUR" \
     -d "purpose=Beispieltransaktion" \
     -d "type=SALE" \
     -d "shoppingCartType=PHYSICAL" \
     -d "customerId=1234567" \
     -d "shippingAmount=500" \
     -d "shippingAddresseFirstName=Otto" \
     -d "shippingAddresseLastName=Mustermann" \
     -d "shippingZipCode=12345" \
     -d "shippingCity=Frankfurt" \
     -d "shippingCountry=DE" \
     -d "merchantReconciliationReferenceNumber=1234567890" \
     -d "orderAmount=9500" \
     -d "orderId=123456789" \
     -d 'cart=[{"name":"Bobbycar","ean":"800001303","quantity":1,"grossAmount":9500}]' \
     -d "invoiceId=9876543" \
     -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \
     -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \
     -d "hash=d74e7cb6e5bd4eeacc63ff3d5ab53af2" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Cart

JSON Array with item objects:

Name Mandatory Type Description
name Yes String(100) Product (article) name
ean Optional String(100) International article 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
[ {
    "name" : "Kids bike",
    "ean" : "800001303",
    "quantity" : 3,
    "grossAmount" : 2599
  }, {
    "name" : "Helmet",
    "quantity" : 1,
    "grossAmount" : 1853
  } ]

Response

The response is a JSON object. The field rc returns an error code. If rc = 0 is returned, the transaction was successfully initialized. You will receive a transaction number and the redirect URL leading to the Paydirekt payment confirmation page in the response.

Parameters

Name Mandatory Type Description
rc Yes Integer Error codes
msg Yes String(255) Additional information in case of error
reference Optional String(36) Unique GiroCheckout transaction ID
redirect Optional String(2048) URL to redirect customer to Paydirekt
HEADER Parameters
hash Yes String(32) HMAC MD5 Hash of all values of the response. See Response hash
Example of success

hash : ad1e0df28e2797a39c05ca08be654ef2

{"reference":"dd724940-5e86-4072-8442-2c2ba2aebc79","redirect":"https://sandbox.paydirekt.de/checkout/#/checkout/016edd33-6181-4392-9dff-5ee80dfb119a","rc":"0","msg":""}
Example of failure

hash : f55ce87e132ebb7eb20004c6b186ce09

{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}

Notification of payment result

The result of a payment is transmitted to the URL specified in the urlNotify parameter. This notification serves the purpose of informing the merchant about the outcome of the transaction. This enables the merchant to update his transaction status.

The result of the transaction's payment is contained in the field gcResultPayment.

Request

URL: notifyUrl from transaction initialization
Provided by: Merchant
Called by: GiroCheckout

GET Parameters

Name Mandatory Type Description
gcReference Yes String(36) GiroCheckout transaction ID
gcMerchantTxId Yes String(255) Merchant transaction ID
gcBackendTxId Yes String(36) Transaction ID of payment provider
gcAmount Yes Integer For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny
gcCurrency Yes String(3) Currency
gcResultPayment Yes Integer Payment result codes
gcHash Yes String(32) HMAC MD5 hash of all the values of the request. See Generate hash

Response

As a response 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 didn't process the notification and doesn't want to be notified again.
All others The notification is repeated for a maximum of 10 times every 30 minutes, until the merchant returns either HTTP 200 or 400.

Returning the customer to the merchant

Once the payment is finished, the customer may return to the merchant via a link. A redirection does not take place until the customer has clicked the “Cancel” or “Return to Shop” button. This redirect is not done automatically.

Request

URL: redirectUrl from transaction initialization
Provided by: Merchant
Called by: GiroCheckout

GET Parameters
Name Mandatory Type Description
gcReference Yes String(36) GiroCheckout transaction ID
gcMerchantTxId Yes String(255) Merchant transaction ID
gcBackendTxId Yes String(36) Transaction ID of the payment provider
gcAmount Yes Integer For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny
gcCurrency Yes String(3) Currency
gcResultPayment Yes Integer Payment result
gcHash Yes String(32) HMAC MD5 hash of all the values in the request. See Generate hash

Other transaction types

These transactions refer to a previous transaction. They are based on a server to server communication and require no customer intervention (in terms if data entry).

Provided by: GiroCheckout
Called by: Merchant

Workflow

ShopGiroCheckoutPaydirekt1 2 3 4 (c)2016 by GiroSolution AG

  1. Shop sends referencing transaction
  2. GiroCheckout routes transaction to Paydirekt
  3. Paydirekt transmits result to GiroCheckout
  4. Shop receives reply regarding transaction result (Notification)

Booking (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

AUTHauthCAPTURE

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

SALEAUTHsaleREFUNDauthREFUND

POST Parameters

CAPTURE URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture
REFUND URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund

Name MandatoryType Description
CAPTURE REFUND
merchantId Yes Yes Integer Merchant ID of a Paydirekt project
projectId Yes Yes Integer Project ID of a Paydirekt project
merchantTxId Yes Yes String(255) Unique merchant transaction ID. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount Yes Yes Integer Full or partial amount. For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny
currency Yes Yes String(3) Transaction currency, see ISO 4217.
EUR = Euro
purpose Yes Yes String(27) Transaction purpose. This information is displayed on the accounting reports.
reference Yes Yes String(36) GiroCheckout transaction ID of the underlying AUTH transaction.
merchantReconciliationReferenceNumber Optional Optional String(30) Additional information for the payment reconciliation that is shown in the purpose on bank statements.
final Optional Boolean CAPTURE ONLY. Last CAPTURE for a reservation. After this, no further CAPTURE may be done on the referenced reservation.
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 Yes String(32) HMAC MD5 hash of all the values in the call. See Generate hash
Example
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "merchantTxId=1234567890" \
     -d "amount=10000" \
     -d "currency=EUR" \
     -d "purpose=Beispiel-Capture" \
     -d "reference=dd724940-5e86-4072-8442-2c2ba2aebc79" \
     -d "final=true" \
     -d "hash=e4e57b71b094d7fa197374f4fbdd4ca9" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/capture

Response

The response is a JSON object. The field resultPayment returns an error code. If resultPayment = 4000 is returned, the transaction was carried out successfully. You receive a transaction number in the reply.

Parameters
Name Mandatory Type Description
reference Yes String(36) GiroCheckout transaction ID
merchantTxId Yes String(255) Merchant transaction ID
backendTxId Yes String(36) Transaction ID of the payment provider
amount Yes Integer For currencies that use decimals, specify amount in the smallest unit, e.g. Cent, Penny
currency Yes String(3) Currency
resultPayment Yes Integer Payment result
hash Yes String(32) HMAC MD5 hash of all the values of the call. Siehe Generate hash
Example of success case

hash : 36dc1f4622d0c1260fe5da76fe83fbd3

{"reference":"ehd82947-5e86-4072-8442-2c2ba2ae74a","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}
Example of failure

hash : c7dcb2d7d5e6719c6a51d81705bfc3af

{"reference":null,"rc":5030,"msg":"Betrag ungültig"}

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 paydirekt project
projectId Yes Integer Project ID of a paydirekt 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(36) 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"}