Introduction

giropay is the payment method for German private banks, co-operative banks and credit unions (Raiffeisenbanken, Volksbanken) and savings banks (Sparkassen).

The purpose of this document is to describe the interfaces (REST API) in order to fully integrate the payment method for giropay payment service providers (giropay PSP), directly connected merchants and technical payment service providers (PSPs).

With this integration of the new and improved full giropay Checkout API you are capable to provide your customers with the three following giropay authorization methods:

  • giropay-Login (payment is authorized via the customers giropay account)

  • Online-Überweisung (payment is authorized with the customer’s online banking credentials)

  • Digitale girocard (Payment is authorized with a digitalized girocard on a customers smartphone banking app)

Being able to provide your customers with all three methods depends purely on the checkout you are creating. In general all three methods are possible if you use the checkout type “DIRECT_SALE”. More information will be provided in the part of the checkout creation.

Endpoint

The giropay interfaces can be reached via the following URL:

https://api.paydirekt.de

A test environment (sandbox) with the following endpoint is available for testing the interface. The giropay system does not perform any payments in its sandbox, neither to real bank accounts, nor for simulated test banks.

https://api.sandbox.paydirekt.de

The static IP addresses of the endpoints are:

Production: 213.95.157.133
Sandbox: 213.95.255.167

The static IP addresses from which callback URLs are fetched are:

Production: 213.95.26.236
Sandbox: 213.95.26.164

Transport Layer Security (TLS)

giropay can only be accessed via encrypted endpoints (HTTPS). The Payment Card Industry Security Standards Council already recommends the use of TLS 1.2 for API connections. The following cipher suites are recommended for TLS 1.2: ECDHE-RSA-AES256-GCM-SHA384

Explanation:

  • This cipher suite is recommended by the BSI and can be used at least until 2021 and beyond.

  • ECDHE offers Perfect Forward Secrecy.

  • ECDHE requires fewer resources than DHE.

  • AES256 is a strong encryption standard.

  • RSA is the underlying method for the private/public key material.

  • SHA384 is a secure fast hash function for signatures.

  • SHA384 provides protection even against length extension attacks (unlike SHA256).

  • GCM is a modern cipher block mode for AES that prevents certain attack vectors possible with the alternative CBC.

  • GCM establishes Authenticated Encryption.

For an overview of which older versions of TLS are currently still supported, see this page.

If Java is used, the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files must be installed.

REST principles

The giropay system provides a REST interface for integrating payments in webshops.

The API follows the HATEOAS principles, based on the HAL specification, and uses JSON as the data format.

HTTP methods

The REST API defines resources that correspond to business objects and are referenced by URL. Standard HTTP methods according to RFC 2616 are used to create, modify, and retrieve data from these resources:

Method Type Description

GET

Query

Returns the representation of one or more business objects. No changes are made to this resource.

POST

Command

Creates a new business object.

PATCH

Command

Updates an existing business object.

PUT

Command

Updates a business object by replacing it.

DELETE

Command

Deletes a business object.

HTTP header fields

The following headers must be included in all service calls except for the access token endpoint.

Header field Value Example

Authorization

Access token from the OAuth2 call

Bearer <accessTokenValue>

X-Request-ID

Unique request ID, used for logging. If none is set in the request, one is generated on the server side and returned inside the HTTP response.
If a request ID is specified on the client side, the format version-4 UUID (random) should be used.
Optional.

8eb5d811-ad7f-4e08-94e4-5dcfa03a4b15

Content-Type

The Internet Media Type of the request body. Only application/hal+json is supported.
Mandatory field for command methods.

application/hal+json

Accept

The accepted and expected Internet Media Types of the response. Only application/hal+json is supported.
Mandatory field for calls with response body.

application/hal+json

Date

Date and time when the request was sent. Format according to [RFC 7231] IMF-fixdate.
Mandatory.

Fri, 28 May 2021 09:46:48 GMT

HTTP status codes and error messages

The following general status codes can potentially occur in all service calls and must be handled accordingly. Special features for a resource are explained in each case in the return codes section.

HTTP status code Description

200 (OK)

The request has succeeded.

201 (Created)

The request has succeeded. A new resource has been created as a result. It can be reached at the location stored in the header.
This status code comes after a certain successful POST to a resource URL.

204 (No Content)

The request has succeeded. There is no content to send for this request.

400 (Bad Request)

The request was not accepted. Details are in the response body.

401 (Unauthorized)

An attempt was made to access a resource that is protected. Either the API key is incorrect, the OAuth2 token is missing or expired, or access to the resource is denied.

403 (Forbidden)

Access is not allowed to this resource with the HTTP method used.

404 (Not Found)

The server does not know any resource at this URL.

410 (Gone)

This version of the API is no longer available.

422 (Unprocessable Entity)

The server could not process the request for semantic reasons. Details are in the response body.

500 (Internal Server Error)

A server-side error has occurred. Details are in the response body.

503 (Service Unavailable)

The giropay system is temporarily unavailable (e.g., due to maintenance).

Error messages

If an error occurs, then in addition to the HTTP status code, details of the error are returned in an array of message objects named messages in the response body.

Messages have a defined, unique message code (field code) and an error level (severity). In addition, the attribute logref may be included, which uniquely references the error and simplifies error analysis. Please always include this logref in support requests.

The possible message codes are listed in the return codes section.

A default behaviour must be implemented for unknown or missing message codes in the case of a 4xx or 5xx status code.

Attribute Type Description

messages

List of messages

A list of all errors that have occurred.

Special case: validation error

Validation errors are also returned in the previously described form, along with the HTTP status code 400.

The path of an affected attribute is specified in the path field. Complex objects are separated by dots. Arrays are referenced using [n].

In addition, a detailed cause of the validation message can be specified in another optional field, reasonCode.

The following reason codes are currently defined for the message code VALIDATION_ERROR:

Reason code Description

INVALID_FORMAT

The value does not match the format specifications.

MANDATORY_VALUE_MISSING

One or more mandatory fields are not specified.

INVALID_ENUM_VALUE

A value was used that is not included in the specified enumeration type.

Links

Links to other resources may be included in the response data. The links are dependent on the context and status of the resource and can indicate actions that are currently possible for a resource. It may be that a link is no longer included, for example after a certain period of time, because the action is no longer possible.

The return data follows the Hypertext Application Language (HAL) format.

It is strongly recommended to always use links to perform actions.

Additional fields

Additional fields that are transmitted during requests or responses and are not described in this document will be ignored by the giropay system. An error or warning will not be returned in the process.

Authenticate as merchant, PSP, or giropay PSP

An API key procedure in conjunction with OAuth2 is used to authenticate merchants, PSPs, and giropay PSPs.

Directly connected merchants require an API key and API secret pair for the shop on behalf of which they want to send requests to the giropay system. API keys and secrets for one of the merchant’s shops can be generated in the merchant portal.

Technical PSPs require an API key and secret pair of their own. If they want to send checkout requests on behalf of a shop, they additionally need the shop’s API key and secret pair.

Giropay PSPs require an API key and secret pair of their own. If they want to send checkout requests on behalf of a shop, they additionally need the shop’s merchant authorization reference.

PSPs and giropay PSPs can create their API keys and secrets in the intermediary portal.

For each entity (merchants, PSPs, and giropay PSPs) with their respective set of credentials, an access token can be obtained. This access token can be used to send authenticated requests to the giropay system.

Definition of terms

API key

The API key is used to identify a merchant, technical PSP, or giropay PSP. An API key can be created and deactivated in the merchant portal (merchant), or intermediary portal (technical PSP, giropay PSP). Several API keys can be valid at the same time. In the sandbox, the first 8 digits of newly created API keys are always "00000000".

An API key is generated by the giropay system and has the following format:
Length: 36 characters
Encoding: version-4 UUID (random) [RFC 4122]
Example: 87dbc6cd-91d2-4574-bcb5-2aaaf924386d
Example in the sandbox: 000000-91d2-4574-bcb5-2aaaf924386d

API secret

The API secret is used to authenticate the merchant, technical PSP, or giropay PSP. It is used to generate a signature of the authentication request. The API secret itself is never transmitted in the communication, which significantly increases security. An API secret is assigned to exactly one API key and is managed together with it.

An API secret is generated by the giropay system and has the following format:
Length: 44 characters
Encoding: Base64 URL encoding [RFC 4648 Section 5] with Base64 padding
Example: 9Tth0qty_9zplTyY0d_QbHYvKM4iSngjoipWO6VxAao=

Access token

An OAuth2 access token [RFC 6749 1.4] is required for all requests against the giropay API. The authentication information of the caller is stored in this token. An access token is generated by calling the access token endpoint by specifying the grant type api_key and is specified as Bearer in the Authorization request header for all subsequent requests:

Authorization: Bearer <accessToken>

The access token has a limited validity period of one hour. After the validity period has expired, a new access token can simply be obtained. The validity period is returned in the response of the access token.

If required, the calling system can use several access tokens simultaneously. If the calling system consists of several nodes, each node can use its own access token for its requests. However, for performance reasons, it is not permitted to request a new access token for each individual request.

Grant type

The grant type defines the method a user or a system uses to authenticate itself to the giropay system. For the REST API, the grant type api_key is used.

Signature (Auth-Code)

The signature (Auth-Code) confirms that the merchant, technical PSP, or giropay PSP is in possession of the API secret and is allowed to send valid requests to the giropay system.

The signature is generated from a string-to-sign and an API secret. The following values are fed into the string-to-sign in the sequence shown here:

No. Value Source Format Example

1.

Request ID

Request header X-Request-ID

version-4 UUID (random) [RFC 4122]

ec85749b-aa36-412a-a397-2b40200c119c

2.

Date

Request header X-Date. Important: The time must correspond to the UTC time zone!

yyyyMMddHHmmss

20210622235859

3.

API key

Request header X-Auth-Key (Merchant), Request Header X-Auth-Key-PSP (PSP, giropay PSP)

version-4 UUID (random) [RFC 4122]

4c15310a-7936-4a19-8d80-f2b7bd95dc9b

4.

Random Nonce

Request body field randomNonce

Base64 URL encoding [RFC 4648 Section 5]

Ns0WLCI3qA2AMH98wUYyhqALyVlzS0q7n Hh7NdeMyvUgKJoyF0rNXkgq5fq2VNJs

The random nonce must be randomly generated by the calling system for each request. It is included in the signature and transferred to the giropay system in the request body field randomNonce.

From the values specified above, first the so-called string-to-sign is formed. For this purpose, the values are connected in the specified order, separated using : as the delimiter, to form a string (string concatenation). The separator is inserted only if another value follows. None of the values may be missing or coded as null.

Format example for a string-to-sign ‘Z’:

Z = ec85749b-aa36-412a-a397-2b40200c119c:20210622235859:4c15310a-7936-4a19-8d80-f2b7bd95dc9b:Ns0WLCI3qA2AMH98wUYyhqALyVlzS0q7nHh7NdeMyvUgKJoyF0rNXkgq5fq2VNJs

Based on a string-to-sign Z for a request R and the API secret S, the signature of the request is formed using the HMAC-SHA-256 [RFC 2104] function:

Signature(Request) = new String(encodeBase64URLCompatible(HMAC-SHA-256(getBytes(Z, "UTF-8"), decodeBase64URLCompatible(getBytes(S, "UTF-8")))), "UTF-8")
The signature is encoded using Base64 URL Encoding [RFC 4648 Section 5]. The problematic characters + and / are replaced by - (minus) and _ (underscore).

This signature is given in the request header X-Auth-Code in case of a merchant, X-Auth-Code-PSP in case of a technical PSP or giropay PSP.

By comparison with basic auth or a simple hash signature, the HMAC-based API key procedure provides a significantly higher degree of security, since the signature cannot be counterfeited or reused and the secret is never transmitted in the communication.

Access token

POST /api/merchantintegration/v1/token/obtain

An access token is issued via this endpoint, as described above.

Depending on your role different request fields have to be provided to obtain an access token, X-Auth-Key and X-Auth-Code in case of merchants, X-Auth-Key-PSP and X-Auth-Code-PSP in case of technical PSPs and giropay PSPs.

When acting on behalf of a shop, e.g. creating checkouts, technical PSPs additionally need to provide the X-Auth-Key and X-Auth-Code of the shop. giropay PSPs need to additionally provide the X-Auth-Merchant-Ref of the shop, which can be retrieved from the shop’s data, see Managed giropay Merchant API.

Request

Field Type Characteristics Description

General Header fields

X-Request-ID

String

Mandatory.
36 characters.

Randomly generated UUID of the request
Purpose: Logging, log statement correlation, and debugging
Format: version-4 UUID (random)
Example: ec85749b-aa36-412a-a397-2b40200c119c

X-Date

String

Mandatory.

Date and time when the request was sent
Format: [RFC 7231] IMF-fixdate
Example: Fri, 28 May 2021 09:46:48 GMT

Content-Type

String

Mandatory.

Always application/hal+json;charset=utf-8

Additional header fields (directly connected merchant)

X-Auth-Key

String

Mandatory.
36 characters.

API key of the shop
Purpose: Identification
Format: version-4 UUID (random) [RFC 4122]
Example: 4c15310a-7936-4a19-8d80-f2b7bd95dc9b

X-Auth-Code

String

Mandatory.
Maximum 44 characters.

The request’s Signature (Auth-Code)
Purpose: Authentication
Encoding: Base64 URL encoding [RFC 4648 Section 5]
Example: Im6MZB4ht8Dp8mXIBzPjqdgaQSZVl5CzoVzmoCnQAfk=

Additional header fields (technical PSP)

X-Auth-Key-PSP

String

Mandatory.
36 characters.

API key of the PSP
Purpose: Identification
Format: version-4 UUID (random) [RFC 4122]
Example: 4c15310a-7936-4a19-8d80-f2b7bd95dc9b

X-Auth-Code-PSP

String

Mandatory.
Maximum 44 characters.

Signature of the request regarding the PSP
Purpose: Authentication
Encoding: Base64 URL encoding [RFC 4648 Section 5]
Example: Im6MZB4ht8Dp8mXIBzPjqdgaQSZVl5CzoVzmoCnQAfk=

X-Auth-Key

String

Mandatory when acting on behalf of a shop.
36 characters.

API key of the shop
Purpose: Identification
Format: version-4 UUID (random) [RFC 4122]
Example: 4c15310a-7936-4a19-8d80-f2b7bd95dc9b

X-Auth-Code

String

Mandatory when acting on behalf of a shop.
Maximum 44 characters.

The request’s Signature (Auth-Code)
Purpose: Authentication
Encoding: Base64 URL encoding [RFC 4648 Section 5]
Example: Im6MZB4ht8Dp8mXIBzPjqdgaQSZVl5CzoVzmoCnQAfk=

Additional header fields (giropay PSP)

X-Auth-Key-PSP

String

Mandatory.
36 characters.

API key of the giropay PSP.
Purpose: Identification
Format: version-4 UUID (random) [RFC 4122]
Example: 4c15310a-7936-4a19-8d80-f2b7bd95dc9b

X-Auth-Code-PSP

String

Mandatory.
Maximum 44 characters.

The request’s Signature (Auth-Code)
Purpose: Authentication
Encoding: Base64 URL encoding [RFC 4648 Section 5]
Example: Im6MZB4ht8Dp8mXIBzPjqdgaQSZVl5CzoVzmoCnQAfk=

X-Auth-Merchant-Ref

String

Mandatory when acting on behalf of a shop.
Maximum 44 characters.

Identification token for a merchant shop. Purpose: Permission extension of the issued token with the possibility to perform actions on behalf of this merchant/shop. Can be retrieved from the shop data of the merchant.

Body fields

grantType

String

Mandatory.

Always api_key

randomNonce

String

Mandatory.
64 characters.

Random string for diversification of request body content
Purpose: Increasing the security of the process
Encoding: Base64 URL encoding [RFC 4648 Section 5]
Example: Ns0WLCI3qA2AMH98wUYyhqALyVlzS0q7nHh7NdeMyvUgKJoyF0rNXkgq5fq2VNJs

Response

Field

Type

Characteristics

Description

access_token

String

Always present.

OAuth2 access token for requests to the giropay API. The token length is dependent on the data fields coded in it, and no maximum length is defined. It should therefore not be limited when implementing the client.

token_type

String

Always present.

Always bearer.

expires_in

Number

Always present.

Validity period of the access token in seconds for information.

scope

String

Always present.

Validity range of the access token for information.

aid

String

Always present.

UUID consisting of 36 characters for unique identification of the token.

jti

String

Always present.

JSON Web Token ID of the access token for debugging purposes.

Return codes

Status code Message code Description

200 (Ok)

Access token was successfully created.

400 (Bad Request)

INVALID_GRANT

X-Auth-Key / X-Auth-Key-PSP or X-Auth-Code / X-Auth-Code-PSP is missing or invalid.

401 (Unauthorized)

API_KEY_IN_REQUEST_UNKNOWN

The API key is not stored in the giropay system.

401 (Unauthorized)

API_KEY_REQUEST_HEADER_INVALID

The request contains more than one X-Auth-Key / X-Auth-Key-PSP.

401 (Unauthorized)

API_KEY_IN_REQUEST_INACTIVE

The API key is disabled.

401 (Unauthorized)

API_KEY_REQUEST_SIGNATURE_INVALID

The X-Auth-Code / X-Auth-Code-PSP is false or empty.

Example

POST /api/merchantintegration/v1/token/obtain HTTP/1.1
Date: Mon Jan 23 13:06:19 CET 2021
X-Request-ID: 1e2c7830-e001-4eb3-a705-38efacf3cd01
Accept: application/hal+json
Content-Type: application/hal+json;charset=utf-8
X-Auth-Key-PSP: ee3f9f0e-17fd-4ff3-bebc-3a16a867fd98
X-Auth-Code-PSP: AYLRvNW-zp2Z9RVF6KYYezN9DMHI5Wo8rcQdT02TOMg=
X-Auth-Merchant-Ref: P_piZRwAxsaGBiXQ6gz0d2sC0dkAAIpLZhdwca-XppY=
Host: api.paydirekt.de
Content-Length: 115

{
  "grantType" : "api_key",
  "randomNonce" : "0Lt5zqnh4w3IR1w1crv3jsg5UuZcpBc7kPzJ25KNATYN8CCfp0EZ0mtrLBPZz7Cb"
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8
Content-Length: 1344

{
  "access_token" : "w8d2D2wd...",
  "token_type" : "bearer",
  "expires_in" : 3599,
  "scope" : "checkout reporting intermediary",
  "jti" : "842f0703-db73-4132-ac8e-005103f07d8a"
}

Example (Wrong auth code)

POST /api/merchantintegration/v1/token/obtain HTTP/1.1
X-Request-ID: 2346b3bd-174d-41d3-a82a-1730dabb1592
Content-Type: application/json;charset=utf-8
X-Auth-Key-PSP: 96a57c6a-ae4e-4c96-9952-2bf830d42031
X-Auth-Code-PSP: 2KXQl8oSV-m1hUWUhDGmYV8HtTXXTRcyXz3SdZGOQlw=
X-Auth-Merchant-Ref: P_piZRwAxsaGBiXQ6gz0d2sC0dkAAIpLZhdwca-XppY=
Host: api.paydirekt.de
Content-Length: 115
X-Date: Mon, 23 Jan 2021 12:06:20 GMT

{
  "grantType" : "api_key",
  "randomNonce" : "KVGQy-bAtKTFhNesYLzFIyUHK_iUA7Qlfw0z7YzFUMqrE3_PB8cOOrlNPScY8S_N"
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
Content-Length: 170

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "API_KEY_REQUEST_SIGNATURE_INVALID",
    "logref" : "2346b3bd-174d-41d3-a82a-1730dabb1592:9eLz9fnG9ok"
  } ]
}

Resource access

With the valid access token, the API can now be accessed, e.g. to create a new checkout or to retrieve an existing one. The giropay system identifies the caller using this token.

The access token is specified in the Authorization header field with the prefix Bearer (see HTTP header fields).

The access token is valid for a limited time (see expires_in) and should be used for all requests within this validity for performance reasons. The time limit is specified in access token.

Example (Expired access token)

Shortly before this time expires, a new access token should be requested. In case the validity of an access token has expired due to the time limit, the giropay system responds with the HTTP status code 401 with the message code ACCESS_TOKEN_EXPIRED. The calling system must obtain a new access token at this point and repeat the request.

In addition to the message structure, the body of the HTTP response also contains the error and error_description fields, which are defined in [RFC 6749].

GET /api/merchantintegration/v1/some-endpoint HTTP/1.1
Date: Mon Jul 24 13:53:18 CEST 2023
Host: api.paydirekt.de
Authorization: Bearer lO3uuUom...
HTTP/1.1 401 Unauthorized
Content-Type: application/hal+json;charset=utf-8
Content-Length: 197

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "ACCESS_TOKEN_EXPIRED",
    "logref" : "4FEewfJnKJN"
  } ],
  "error" : "invalid_token",
  "error_description" : "Access token expired"
}

Checkout

A checkout represents the entire payment operation. The following sections describe how checkouts are created and how the data stored on a payment operation can be queried. A distinction is made here between the types one-time payment and preorder.

With this integration of the new and improved full giropay Checkout API you are capable to provide your customers with the three following giropay authorization methods:

  • giropay-Login (payment is authorized via the customers giropay account)

  • Online-Überweisung (payment is authorized with the customer’s online banking credentials)

  • Digitale girocard (payment is authorized with a digitalized girocard on the customer’s smartphone)

Being able to provide your customers with all three methods depends purely on the checkout type you are creating. In general, all three methods are possible if you use the checkout type “DIRECT_SALE”.

Checkout success status

The successful completion of the payment does not depend on the successful transmission of the status. The completion and status of the transaction should therefore always be ensured by the merchant system via a final GET call of the checkout.

In particular, a merchant must not rely on the calls to the status callback URLs see Checkout Callback or the redirection to one of the redirect URLs see Checkout Request-Fields specified during the creation of the request to evaluate the checkout result.

Background: the redirect can fail due to connection errors after a successful checkout or the buyer cancels the redirect. Status feedback is asynchronous and relies on availability of the merchant endpoint. In both cases, it is not guaranteed that the outcome of a checkout can always be determined reliably and promptly.

In addition, neither the redirect URL nor the status callback URL calls are secured against manipulation or attempted misuse.

Create a checkout

POST /api/checkout/v1/checkouts

In addition to the authentication endpoint, this is the only endpoint which must be definitively stored in the web shop. All other resources can be addressed via corresponding links.

Request

Field Type Characteristics Description

type

String

Mandatory.

Type of the order. One of DIRECT_SALE, ORDER, or ORDER_SECURED.

In case of a DIRECT_SALE (direct order with one-time payment), a payment authorization is generated automatically.
The merchant immediately receives a payment guarantee.
For an ORDER (preorder or order with partial payments), one or more captures can be initiated directly afterwards or later.
No payment guarantee is issued to the merchant for an order.
The payment is guaranteed only for a (successful) capture.
For an ORDER_SECURED (secured preorder or order with partial payments), one or more captures can be initiated directly afterwards or later.
For a secured preorder, a payment guarantee is issued to the merchant for the selected period (maximum 15 calendar days).
Captures (partial payments) are always executed within the guarantee period.
For more information about orders and captures, see the Capture chapter.

scheme

String

Optional.

To enable this feature, an additional agreement is needed.
Allowed value: EPS
EPS is the Electronic Payment Standard by PSA (Payment Services Austria). Austrian banks that are selectable for payment will be displayed to the customer on a separate bank selection page.

totalAmount

Number

Mandatory.
Between 0.01 and 50000.
Maximum two decimal places.

The total amount of the order, including all delivery costs, for which a payment will be initiated.
In case of a DIRECT_SALE, a payment for this amount will be initiated.
In case of an ORDER, captures can be initiated up to a maximum of this amount.

shippingAmount

Number

Optional. Minimum 0.00.
Maximum two decimal places.

The shipping cost of the order.
This value is not used for any calculation, it is provided for information only.

orderAmount

Number

Optional.
Between 0.01 and 50000.
Maximum two decimal places.

The value of goods of the order, excluding shipping costs.
This value is not used for any calculation, it is provided for information only.

refundLimit

Number

Optional.
Between 100 and 200.
Set to 200 if not specified, which means a maximum of two times the amount of the order can be refunded.

Maximum refundable amount as a percentage of the total amount of the order.

overcapture

Boolean

Optional.
(Standard: false)
Overcapture is a specific feature for directly connected merchants and must be explicitly approved as a function for your merchant account. Regarding this, please contact haendler@giropay.de.

Flag for overcapture checkouts.
In an overcapture checkout, the total amount of captures may exceed the merchandise value of the order by up to 10%.
When this flag is enabled, the finalCapture field of the last capture must be set to true.
overcapture must be enabled only if the checkout is of type ORDER.
Can only be used by merchants who have been enabled for this feature.

currency

String

Mandatory.

The currency of the total amount. Currently, only EUR is supported.

items

Array of items

Optional.

The individual items of the shopping cart. It is recommended to pass these values.

shoppingCartType

String

Optional.

Categorizes the shopping cart of a checkout based on the properties of the goods it contains. The default value is MIXED.
PHYSICAL: The shopping cart contains only physical goods.
DIGITAL: The shopping cart contains only digital goods.
MIXED: The shopping cart contains physical goods as well as digital goods.
ANONYMOUS_DONATION: The shopping cart contains exclusively an anonymous donation.
AUTHORITIES_PAYMENT: The shopping cart contains exclusively payments to authorities.

deliveryType

String

Optional.

The destination of a shipment. The default value is STANDARD.
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.

shippingAddress

ShippingAddress

Optional for AUTHORITIES_PAYMENT and ANONYMOUS_DONATION checkouts, otherwise mandatory.

The shipping address of the recipient. This address is displayed to the customer for verification.

merchantCustomerNumber

String

Optional.
Maximum 50 characters.

Merchant-internal customer number of the buyer.

merchantOrderReferenceNumber

String

Mandatory.
Maximum 20 characters. SEPA-compliant characters only.

Merchant-internal, unique order number for this checkout process. Displayed to the customer in the transaction overview. Displayed to the merchant in the transaction overview. The order number is used in the debit note as instructionId and in the merchant’s and buyer’s payment reference.

merchantInvoiceReferenceNumber

String

Optional.
Maximum 100 characters.

Merchant-internal, unique invoice number for this purchase or payment transaction. Displayed to the merchant in the transaction overview.

merchantReconciliationReferenceNumber

String

Optional.
Maximum 30 characters.

Reconciliation number. This value will be inserted in the payment reference of the merchant payment.

sha256hashedEmailAddress

String

Optional.
Maximum 64 characters.

The buyer’s email address as a Base64-encoded SHA-256 hash value without padding, if available. Pseudo-code: sha256hashedEmailAddress = toStringUTF8(base64(sha256(toBytesUTF8(emailAddress)))). Example: The email address max@muster.de must result in exactly the following hash value: 6JL4VUgVxkq2m+a9I6ScfW2ofJP5y6wsvSaHIsX+iLs=. This information is used for fraud prevention.

redirectUrlAfterSuccess

String

Mandatory, except for oneKlick checkouts.
Maximum 2000 characters.

The return address of the webshop (including reference to the order), which is called after successful payment. See Checkout success status.

redirectUrlAfterCancellation

String

Mandatory, except for oneKlick checkouts.
Maximum 2000 characters.

The return address of the webshop (including reference to the order), which is called in the event of a cancellation or technical error. See Checkout success status.

redirectUrlAfterRejection

String

Mandatory, except for oneKlick checkouts.
Maximum 2000 characters.

The return address of the webshop (including reference to the order), which is called in case of a payment rejection. If the webshop system does not support a distinction between redirectUrlAfterCancellation and redirectUrlAfterRejection, the same URL can be specified in both fields. See Checkout success status.

callbackUrlStatusUpdates

String

Optional.
Maximum 2000 characters.

URL of the endpoint that should receive notifications about checkout status updates.

minimumAge

Number

Optional.
Using the field minimum age will result in the single option "giropay-Login" for the customers, because an age verification at the time is solely possible with an existing giropay account.

The minimum age (in years) that the buyer must have reached in order to be able to complete the order, for example, because it contains items that are subject to an age restriction (movies, computer games, etc.). If this field is filled, an age verification is automatically assigned to this transaction. The verification takes place directly after the buyer logs into the giropay system. If the verification is successful, the process continues as usual without any further message. In case of unsuccessful verification, i.e., the customer has not yet reached the required minimum age, a redirection to the URL of the field redirectUrlAfterAgeVerificationFailure takes place (see below). If this value is not specified, no age verification will be performed.

redirectUrlAfterAgeVerificationFailure

String

Mandatory if minimumAge is set.
Maximum 2000 characters.

The redirect URL of the webshop in case of an unsuccessful age verification. Currently, no URL can be specified for this in the giropay system. In the future, this must be set when age verification is performed within the transaction. If no age verification is required, this field should be omitted.

note

String

Optional.
Maximum 37 characters.

Free text field that appears on the bank statement in the payment reference (DIRECT_SALE only).

expiryTime

Number

Optional.
Minimum 120 or 660.
Maximum 1800.

Duration in seconds for which the checkout is valid. Starting from creation in seconds. If not specified, 1800 seconds will be assumed.
Giropay authorization Online-Überweisung can not be selected by the customer if the expiry time is less than 660 seconds.

deliveryInformation

Object

Optional.

Contains information about the delivery.

deliveryInformation.expectedShippingDate

String

Optional.
Timestamp in ISO 8601 format.

Expected shipping date.

deliveryInformation.logisticsProvider

String

Optional.

Parcel service provider.

deliveryInformation.trackingNumber

String

Optional.

Shipment number.

requestedPreauthorizationValidity

String

Optional.
Date in the format yyyy-mm-dd.
Maximum 15 calendar days in the future (corresponds to the default value if not filled).

Desired guarantee period (maximum 15 calendar days) for a secured preorder (ORDER_SECURED).

Response

The created checkout is returned in the response. The structure is identical to the checkout endpoint GET call.

The URL of the created checkout resource is contained in the HTTP header Location, including the checkoutId. The checkoutId also is returned in the response body.

Links

Relation Description

self

Link to this resource.

approve

Link to the giropay website to which the buyer must be redirected via HTTP code 302 to confirm the payment. The redirection must not be done via an HTML form (using the approve link in the action attribute of the form tag). The confirmation by the customer must be done within 30 minutes. This link is only present if the checkout has not been authorized by the customer yet. The structure or parameters of the link may change due to internal developments. Therefore, use only the link returned by our system at runtime.

updateDeliveryInformation

Link to update the delivery information. This link is only available if the update period for the checkout has not yet expired.

updateMerchantInvoiceReferenceNumber

Link to update the invoice reference number. This link is only available if the update period for the checkout has not yet expired.

The approve link indicates the page to which the user must be forwarded via an HTTP Redirect (302) in order to confirm the payment.

Return codes

Status code Message code Description

201 (Created)

The checkout has been created. Afterwards, a redirect to the approve link stored in the resource must be performed.

400 (Bad Request)

VALIDATION_ERROR

The request is syntactically invalid.

400 (Bad Request)

CONVERSION_ERROR

The request contains invalid characters. The most common reason for this is that the request is not correctly UTF-8 encoded. If the invalid characters can be found in an attribute in the request, this attribute is named in the field path and the invalid value is transmitted in the field content.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

401 (Unauthorized)

UNAUTHORIZED

Access has been denied. Please contact giropay support.

422 (Unprocessable Entity)

MERCHANT_BANKACCOUNT_LOCKED

The merchant’s bank account has been blocked, and no new checkouts or captures can be created. The merchant should contact giropay support.

422 (Unprocessable Entity)

PSP_LOCKED

The Payment Service Provider (PSP) is locked, and no new checkouts or captures can be created.

422 (Unprocessable Entity)

EPS_NOT_ENABLED_FOR_ACQUIRER_AGREEMENT_SET

EPS is not enabled for the Acquirer Agreement Set. Please contact giropay support.

422 (Unprocessable Entity)

ACQUIRER_AGREEMENT_SET_MISSING

No acquirer agreement set can be found for the reference at the merchant.

422 (Unprocessable Entity)

NO_AUTHORIZATION_METHOD_AVAILABLE

This checkout could not be approved by a buyer and is denied. The reason is usually that a feature was requested that is incompatible with authorization via online banking credentials, which is the only authorization method available for eps checkouts.

Example (Direct Sale, including age verification)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "DIRECT_SALE",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "currency" : "EUR",
  "overcapture" : false,
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "deliveryInformation" : {
    "expectedShippingDate" : "2023-01-20T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "note" : "Your purchase at Toy-Car-Delivery.",
  "sha256hashedEmailAddress" : "GB16eI6lWfIeYeFBoUqUpNsynYZJCv97Uxev4tfZaCg",
  "minimumAge" : 18,
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://toy-car-delivery.com/order/123/ageverificationfailed",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "13630104-531d-4874-bda4-05ee5ab7a870",
  "type" : "DIRECT_SALE",
  "status" : "OPEN",
  "creationTimestamp" : "2023-07-25T10:42:00.995Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "note" : "Your purchase at Toy-Car-Delivery.",
  "minimumAge" : 18,
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://toy-car-delivery.com/order/123/ageverificationfailed",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2023-01-20T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "expiryTimestamp" : "2023-07-25T11:12:00.995Z",
  "_links" : {
    "approve" : {
      "href" : "https://localhost/checkout/?p=13630104-531d-4874-bda4-05ee5ab7a870#/checkout/13630104-531d-4874-bda4-05ee5ab7a870"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870"
    }
  }
}

Example (Order)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "ORDER",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "PHYSICAL",
  "deliveryType" : "STANDARD",
  "currency" : "EUR",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9",
  "type" : "ORDER",
  "status" : "OPEN",
  "creationTimestamp" : "2023-07-25T10:42:32.815Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "PHYSICAL",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "expiryTimestamp" : "2023-07-25T11:12:32.815Z",
  "_links" : {
    "approve" : {
      "href" : "https://localhost/checkout/?p=4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9#/checkout/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9"
    }
  }
}

Example (Order secured)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "ORDER_SECURED",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "PHYSICAL",
  "deliveryType" : "STANDARD",
  "currency" : "EUR",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "requestedPreauthorizationValidity" : "2023-07-28"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "47debe70-54db-4b9e-8d61-9a06de50f3f2",
  "type" : "ORDER_SECURED",
  "status" : "OPEN",
  "creationTimestamp" : "2023-07-25T10:43:29.456Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "PHYSICAL",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "expiryTimestamp" : "2023-07-25T11:13:29.456Z",
  "_links" : {
    "approve" : {
      "href" : "https://localhost/checkout/?p=47debe70-54db-4b9e-8d61-9a06de50f3f2#/checkout/47debe70-54db-4b9e-8d61-9a06de50f3f2"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2"
    }
  }
}

Example (Validation error)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "DIRECT_SALE",
  "totalAmount" : 100.0,
  "shippingAmount" : 5.999,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "currency" : "EUR",
  "overcapture" : false,
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "note" : "Your purchase at Toy-Car-Delivery.",
  "sha256hashedEmailAddress" : "GB16eI6lWfIeYeFBoUqUpNsynYZJCv97Uxev4tfZaCg",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://toy-car-delivery.com/order/123/underAge",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "VALIDATION_ERROR",
    "path" : "shippingAmount",
    "reasonCode" : "INVALID_FORMAT",
    "logref" : "83b40487-0c4c-4c11-9007-009b70e3ccb4:4TYPRvTZXTx"
  } ]
}

Example (Semantic error)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "DIRECT_SALE",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "currency" : "EUR",
  "overcapture" : false,
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "note" : "Your purchase at Toy-Car-Delivery.",
  "sha256hashedEmailAddress" : "GB16eI6lWfIeYeFBoUqUpNsynYZJCv97Uxev4tfZaCg",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://toy-car-delivery.com/order/123/underAge",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status"
}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=utf-8

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "MERCHANT_BANKACCOUNT_LOCKED",
    "logref" : "d120bc41-dd4a-4e96-bf65-287efe8081e8:KYBRxPovJG"
  } ]
}

Example (Conversion error)

POST /api/checkout/v1/checkouts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "type" : "DIRECT_SALE",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "currency" : "EUR",
  "overcapture" : false,
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "ungültige Zeichen sind z.B.: €¥£˚\\˙¯⁀",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantCustomerNumber" : "cust-732477",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "note" : "Your purchase at Toy-Car-Delivery.",
  "sha256hashedEmailAddress" : "GB16eI6lWfIeYeFBoUqUpNsynYZJCv97Uxev4tfZaCg",
  "expiryTime" : 1800,
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://toy-car-delivery.com/order/123/underAge",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8

{
  "messages" : [ {
    "severity" : "ERROR",
    "code" : "CONVERSION_ERROR",
    "path" : "shippingAddress.company",
    "reasonCode" : "HTTP_MESSAGE_NOT_READABLE",
    "logref" : "fab48619-5e39-40c1-9045-a020b94f0850:4WElzcotNAk",
    "content" : "ungültige Zeichen sind z.B.: €¥£˚\\˙¯⁀"
  } ]
}

Read a checkout

GET /api/checkout/v1/checkouts/{checkoutId}

A previously created checkout can be called up via the GET method in order to query the status of the payment and other properties, and to determine the links to other resources, e.g., captures and refunds.

Response

Field Type Characteristics Description

checkoutId

String

Always present.

UUID consisting of 36 characters for this checkout process. Assigned by the giropay system.

type

String

Always present.

Type of the order. One of DIRECT_SALE, ORDER, or ORDER_SECURED.

In case of a DIRECT_SALE (direct order with one-time payment), a payment authorization is generated automatically.
The merchant immediately receives a payment guarantee.
For an ORDER (preorder or order with partial payments), one or more captures can be initiated directly afterwards or later.
No payment guarantee is issued to the merchant for an order.
The payment is guaranteed only for a (successful) capture.
For an ORDER_SECURED (secured preorder or order with partial payments), one or more captures can be initiated directly afterwards or later.
For a secured preorder, a payment guarantee is issued to the merchant for the selected period (maximum 15 calendar days).
Captures (partial payments) are always executed within the guarantee period.
For more information about orders and captures, see the Capture chapter.

scheme

String

Present if provided at time of creation.

To enable this feature, an additional agreement is needed.
Allowed value: EPS
EPS is the Electronic Payment Standard by PSA (Payment Services Austria). Austrian banks that are selectable for payment will be displayed to the customer on a separate bank selection page.

status

String

Always present.

Status of the checkout. One of OPEN, APPROVED, REJECTED, CANCELED, CLOSED, or EXPIRED.
OPEN: The checkout was newly created and not yet confirmed by the customer.
APPROVED: The checkout has been confirmed by the customer and approved by the system. In the case of an ORDER, captures can now be created.
REJECTED: The checkout was rejected by the system. The payment was not successful. It is unlikely that the payment will succeed if tried again by this customer.
CANCELED: The checkout was canceled by the customer, or a technical error occurred. The checkout cannot be processed further.
CLOSED: Only ORDER: The order has been closed, it is not possible to create new captures. Refunds are still possible.
EXPIRED: The checkout has expired and cannot be used further. The customer has not confirmed the checkout within 30 minutes.

correlationId

String

Available as soon as a customer has logged in. UUID consisting of 36 characters.

UUID of the checkout and all associated transactions.

creationTimestamp

String

Always present.

The creation time of the checkout. Assigned by the giropay system. Formatting according to ISO 8601 by the Java DateTimeFormatter standard. Deviating from this, three decimal places are always output for the milliseconds.

expiryTimestamp

String

Always present.

Checkout is valid up until this timestamp. Can be configured on creation via the field expiryTime. If not specified, 1800 seconds will be assumed. Formatting according to ISO 8601 by the Java DateTimeFormatter standard. Deviating from this, three decimal places are always output for the milliseconds.

totalAmount

Number

Always present.

The total amount of the order, including all delivery costs, for which a payment will be initiated.
In case of a DIRECT_SALE, a payment for this amount will be initiated.
In case of an ORDER, captures can be initiated up to a maximum of this amount.

shippingAmount

Number

Present if provided at time of creation.

The shipping cost of the order.
This value is not used for any calculation, it is provided for information only.

orderAmount

Number

Present if provided at time of creation.

The value of goods of the order, excluding shipping costs.
This value is not used for any calculation, it is provided for information only.

refundLimit

Number

Present if provided at time of creation.

Maximum refundable amount as a percentage of the total amount of the order.

overcapture

Boolean

Present if provided at time of creation.

Flag for overcapture checkouts.
In an overcapture checkout, the total amount of captures may exceed the merchandise value of the order by up to 10%.
When this flag is enabled, the finalCapture field of the last capture must be set to true.
overcapture must be enabled only if the checkout is of type ORDER.
Can only be used by merchants who have been enabled for this feature.

maxCapturableAmount

Number

Available if overcapture flag is set.

If the overcapture flag is set, this field contains the maximum amount that can be retrieved in total.

maxOvercaptureDifference

Number

Available if overcapture flag is set.

If the overcapture flag is set, this field contains the amount additional to the total amount that can be retrieved in total.

currency

String

Always present.

The currency of the total amount. Currently, only EUR is supported.

items

Array von Items

Present if provided at time of creation.

The individual items of the shopping cart. It is recommended to pass these values.

shoppingCartType

String

Present if provided at time of creation.

Categorizes the shopping cart of a checkout based on the properties of the goods it contains. The default value is MIXED.
PHYSICAL: The shopping cart contains only physical goods.
DIGITAL: The shopping cart contains only digital goods.
MIXED: The shopping cart contains physical goods as well as digital goods.
ANONYMOUS_DONATION: The shopping cart contains exclusively an anonymous donation.
AUTHORITIES_PAYMENT: The shopping cart contains exclusively payments to authorities.

deliveryType

String

Present if provided at time of creation.

The destination of a shipment. The default value is STANDARD.
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.

shippingAddress

ShippingAddress

Present if provided at time of creation.

The shipping address of the recipient. This address is displayed to the customer for verification.

merchantCustomerNumber

String

Present if provided at time of creation.

Merchant-internal customer number of the buyer.

merchantOrderReferenceNumber

String

Always present.

Merchant-internal, unique order number for this checkout process. Displayed to the customer in the transaction overview. Displayed to the merchant in the transaction overview. The order number is used in the debit note as instructionId and in the merchant’s and buyer’s payment reference.

merchantInvoiceReferenceNumber

String

Present if provided at time of creation.

Merchant-internal, unique invoice number for this purchase or payment transaction. Displayed to the merchant in the transaction overview.

merchantReconciliationReferenceNumber

String

Present if provided at time of creation.

Reconciliation number. This value will be inserted in the payment reference of the merchant payment.

redirectUrlAfterSuccess

String

Always present, except for oneKlick checkouts.

The return address of the webshop (including reference to the order), which is called after successful payment. See Checkout success status.

redirectUrlAfterCancellation

String

Always present, except for oneKlick checkouts.

The return address of the webshop (including reference to the order), which is called in the event of a cancellation or technical error. See Checkout success status.

redirectUrlAfterRejection

String

Always present, except for oneKlick checkouts.

The return address of the webshop (including reference to the order), which is called in case of a payment rejection. If the webshop system does not support a distinction between redirectUrlAfterCancellation and redirectUrlAfterRejection, the same URL can be specified in both fields. See Checkout success status.

callbackUrlStatusUpdates

String

Present if provided at time of creation.

URL of the endpoint that should receive notifications about checkout status updates.

minimumAge

Number

Present if provided at time of creation.

The minimum age (in years) that the buyer must have reached in order to be able to complete the order, for example, because it contains items that are subject to an age restriction (movies, computer games, etc.). If this field is filled, an age verification is automatically assigned to this transaction. The verification takes place directly after the buyer logs into the giropay system. If the verification is successful, the process continues as usual without any further message. In case of unsuccessful verification, i.e., the customer has not yet reached the required minimum age, a redirection to the URL of the field redirectUrlAfterAgeVerificationFailure takes place (see below). If this value is not specified, no age verification will be performed.

redirectUrlAfterAgeVerificationFailure

String

Present if provided at time of creation.

The redirect URL of the webshop in case of an unsuccessful age verification. Currently, no URL can be specified for this in the giropay system. In the future, this must be set when age verification is performed within the transaction. If no age verification is required, this field should be omitted.

note

String

Present if provided at time of creation.

Free text field that appears on the bank statement in the payment reference (DIRECT_SALE only).

deliveryInformation

Object

Present if provided at time of creation.

Contains information about the delivery.

deliveryInformation.expectedShippingDate

String

Present if provided at time of creation.

Expected shipping date.

deliveryInformation.logisticsProvider

String

Present if provided at time of creation.

Parcel service provider.

deliveryInformation.trackingNumber

String

Present if provided at time of creation.

Shipment number.

preauthorizationValidity

String

Always present for checkout type ORDER_SECURED.

Guarantee period for the secured pre-order (ORDER_SECURED). Captures within this period are guaranteed for the merchant.

_embedded

Object

Embedded resources

Links

Relation Description

self

Link to this resource.

approve

Link to the giropay website to which the buyer must be redirected via HTTP code 302 to confirm the payment. The redirection must not be done via an HTML form (using the approve link in the action attribute of the form tag). The confirmation by the customer must be done within 30 minutes. This link is only present if the checkout has not been authorized by the customer yet. The structure or parameters of the link may change due to internal developments. Therefore, use only the link returned by our system at runtime.

close

Link to close the open order. This link is available only if the checkout is of type ORDER, and if it is in status APPROVED.

captures

Link to captures. This link is only present if a capture is possible for this order.

refunds

Link to the refunds. This link is only available if a refund is possible for this order, i.e., if there is at least one capture with the status SUCCESSFUL. If the link is not present, no refunds are possible.

updateDeliveryInformation

Link to update the delivery information. This link is only available if the update period for the checkout has not yet expired.

updateMerchantInvoiceReferenceNumber

Link to update the invoice reference number. This link is only available if the update period for the checkout has not yet expired.

Embedded resources

Resource Description

captures

Array of captures if captures are available for this checkout.

refunds

Array of refunds if refunds are available for this checkout.

Return codes

Status code Message code Description

200 (Ok)

The checkout has been found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

CHECKOUT_NOT_FOUND

The requested checkout does not exist.

Example (Direct sale after approval by customer)

GET /api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "checkoutId" : "13630104-531d-4874-bda4-05ee5ab7a870",
  "type" : "DIRECT_SALE",
  "status" : "APPROVED",
  "correlationId" : "ext0815-00000140",
  "creationTimestamp" : "2023-07-25T10:42:00.995Z",
  "totalAmount" : 100.0,
  "shippingAmount" : 3.5,
  "orderAmount" : 96.5,
  "refundLimit" : 200,
  "currency" : "EUR",
  "items" : [ {
    "quantity" : 3,
    "name" : "Bobbycar",
    "ean" : "800001303",
    "price" : 25.99
  }, {
    "quantity" : 1,
    "name" : "Helm",
    "price" : 18.53
  } ],
  "shoppingCartType" : "MIXED",
  "deliveryType" : "STANDARD",
  "shippingAddress" : {
    "addresseeGivenName" : "Marie",
    "addresseeLastName" : "Schmitt",
    "company" : "Construction and Building Ltd.",
    "street" : "Chestnut-Avenue",
    "streetNr" : "999",
    "additionalAddressInformation" : "Flat 4",
    "zip" : "90402",
    "city" : "Springfield",
    "countryCode" : "DE",
    "state" : "Bavaria"
  },
  "merchantOrderReferenceNumber" : "order-A12223412",
  "merchantCustomerNumber" : "cust-732477",
  "merchantInvoiceReferenceNumber" : "20230118334345",
  "merchantReconciliationReferenceNumber" : "recon-A12223412",
  "note" : "Your purchase at Toy-Car-Delivery.",
  "minimumAge" : 18,
  "redirectUrlAfterSuccess" : "https://toy-car-delivery.com/order/123/success",
  "redirectUrlAfterCancellation" : "https://toy-car-delivery.com/order/123/cancellation",
  "redirectUrlAfterAgeVerificationFailure" : "https://toy-car-delivery.com/order/123/ageverificationfailed",
  "redirectUrlAfterRejection" : "https://toy-car-delivery.com/order/123/rejection",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2023-01-20T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "expiryTimestamp" : "2023-07-25T11:12:00.995Z",
  "_links" : {
    "refunds" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870/refunds"
    },
    "updateDeliveryInformation" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870/deliveryInformation"
    },
    "updateMerchantInvoiceReferenceNumber" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870/merchantInvoiceReferenceNumber"
    },
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870"
    }
  },
  "_embedded" : {
    "captures" : [ {
      "type" : "CAPTURE_DIRECT_SALE",
      "transactionId" : "3212bdba-2dfe-45f5-b412-8214a8262797",
      "amount" : 100.0,
      "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
      "deliveryInformation" : {
        "expectedShippingDate" : "2023-01-20T12:00:00.000Z",
        "logisticsProvider" : "DHL",
        "trackingNumber" : "1234567890"
      },
      "status" : "SUCCESSFUL",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/13630104-531d-4874-bda4-05ee5ab7a870/captures/3212bdba-2dfe-45f5-b412-8214a8262797"
        }
      }
    } ]
  }
}

Callback for status updates

If merchants/PSPs pass a callback URL callbackUrlStatusUpdates when creating checkouts, the giropay system sends an HTTP request to this URL when the status of the checkout changes. Status updates are also sent for the embedded capture. In case of DIRECT_SALE status updates are also sent for the embedded capture. In case of connection errors or responses with an HTTP status code of 5xx, the giropay system will repeat the transmission of the status change up to 5 times within a time window of 24 hours. Status changes are always transmitted in the order in which they occurred at the checkout. If a status change cannot be transmitted, all subsequent status changes are also not transmitted until either the failed transmission could be made up for or all repeated attempts have failed.

POST callbackUrlStatusUpdates

Request

Field Type Characteristics Description

checkoutId

String

Always present.

UUID consisting of 36 characters for this checkout process. Assigned by the giropay system.

merchantOrderReferenceNumber

String

Always present.
Maximum 20 characters. SEPA-compliant characters only.

Merchant-internal, unique order number for this checkout process. Displayed to the customer in the transaction overview. Displayed to the merchant in the transaction overview. The order number is used in the debit note as instructionId and in the merchant’s and buyer’s payment reference.

checkoutStatus

String

Always present.

Status of the checkout. One of OPEN, APPROVED, REJECTED, CANCELED, CLOSED, or EXPIRED.
OPEN: The checkout was newly created and not yet confirmed by the customer.
APPROVED: The checkout has been confirmed by the customer and approved by the system. In the case of an ORDER, captures can now be created.
REJECTED: The checkout was rejected by the system. The payment was not successful. It is unlikely that the payment will succeed if tried again by this customer.
CANCELED: The checkout was canceled by the customer, or a technical error occurred. The checkout cannot be processed further.
CLOSED: Only ORDER: The order has been closed, it is not possible to create new captures. Refunds are still possible.
EXPIRED: The checkout has expired and cannot be used further. The customer has not confirmed the checkout within 30 minutes.

statusUpdateTimestamp

String

Always present.

Timestamp of the status update.

sequenceNumber

Number

Always present.

Sequence number of the status update. Using the sequence number, a shop can track the order of status updates and identify missing status updates if any are present.
Example
POST /webhooktest/v1/checkout/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "070f4dfd-e9ac-4375-b38f-564100cc8ad9",
  "checkoutStatus" : "APPROVED",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
  "sequenceNumber" : 4
}

Response

The response does not contain a body and is not processed further by the giropay system. The HTTP status code should nevertheless allow conclusions to be drawn about the processing of the status notification for any service requests.

Example
HTTP/1.1 200 OK

Update the shipping conditions

PUT /api/checkout/v1/checkouts/{checkoutId}/deliveryInformation

The shipping conditions for an already-created checkout can be updated via this endpoint. All fields indicated in the request are overwritten on the checkout resource. The value in the resource remains unaffected for all fields not included in the request. The current shipping conditions of the checkout are visible for the purchaser. Updates are only permitted up to 25 days following the last capture on the checkout.

Request

Field Type Characteristics Description

expectedShippingDate

String

Optional.
Timestamp in ISO 8601 format.

Expected shipping date.

logisticsProvider

String

Optional.

Parcel service provider.

trackingNumber

String

Optional.

Shipment number.

Response

The updated checkout is returned in the response. The structure is identical to the checkout endpoint GET call.

Return codes

Status code Message code Description

200 (Ok)

The checkout was found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

CHECKOUT_NOT_FOUND

The checkout to be updated does not exist.

422 (Unprocessable Entity)

CHECKOUT_UPDATE_TIMEFRAME_EXPIRED

The checkout can no longer be updated since more than 25 days have elapsed since the last capture.

Example request

PUT /api/checkout/v1/checkouts/0a66b872-4204-48d1-853f-5a97f9817c0a/deliveryInformation HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "expectedShippingDate" : "2016-10-19T12:00:00Z",
  "logisticsProvider" : "DHL",
  "trackingNumber" : "1234567890"
}

Update the invoice reference

PUT /api/checkout/v1/checkouts/{checkoutId}/merchantInvoiceReferenceNumber

The invoice reference of an already-created checkout can be updated via this endpoint. The current invoice reference of the checkout is not visible for purchasers. Updates are only permitted up to 25 days following the last capture on the checkout.

Request

Field Type Characteristics Description

merchantInvoiceReferenceNumber

String

Optional.
Maximum 100 characters.

Merchant-internal, unique invoice number for this purchase or payment transaction. Displayed to the merchant in the transaction overview.

Response

The updated checkout is returned in the response. The structure is identical to the checkout endpoint GET call.

Return codes

Status code Message code Description

200 (Ok)

The checkout was found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

CHECKOUT_NOT_FOUND

The checkout to be updated does not exist.

422 (Unprocessable Entity)

CHECKOUT_UPDATE_TIMEFRAME_EXPIRED

The checkout can no longer be updated since more than 25 days have elapsed since the last capture.

Example request

PUT /api/checkout/v1/checkouts/2f9c6ad6-548a-443a-9106-e30870b3dfca/merchantInvoiceReferenceNumber HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "merchantInvoiceReferenceNumber" : "12345678"
}

Capture

Using a capture, the purchaser’s account is debited by a given sum and the retailer is issued with a payment guarantee.

Each capture is authorized by the purchaser’s bank. A successful bank authorization results in a payment guarantee for the sum requested and a corresponding post to the account. Depending on the outcome, this results in a final status SUCCESSFUL or REJECTED.

The following types of captures exist:

CAPTURE_DIRECT_SALE

This is created automatically if the purchaser confirms a checkout of the type DIRECT_SALE and if the authorization by the purchaser’s bank was successful.

CAPTURE_ORDER

After successful creation of a checkout of the type ORDER, for up to a maximum of 182 days after creating the order the merchant can create one or more captures of the type CAPTURE_ORDER. During this period, the number of captures is unlimited. The maximum total of all captures is limited to the checkout amount (totalAmount). The last capture should be given a flag finalCapture, in order to close the order for the customer.

CAPTURE_ORDER_SECURED

For an ORDER_SECURED one or more captures can be triggered directly afterwards or later. One or more captures can be initiated. For a secured pre-order, a payment guarantee is issued to the merchant for the selected period (maximum 15 calendar days). Captures (partial payments) within the guarantee period are always executed.

An order of the type ORDER or ORDER_SECURED is displayed as open to the customer in the transaction overview until

  • the full amount of the order was called up and the order is automatically closed as a result, or

  • a capture was marked using finalCapture, or

  • the order was explicitly closed, or

  • 182 days have elapsed.

If the precise amount of the order sum is not determined when the order is created, the

  • Overcapture functionality can be used (see relevant field description in Create a checkout), or

  • a corresponding shopping basket item can be used to increase the checkout amount, or

  • a higher checkout amount (totalAmount) can be indicated (without separate shopping basket item).

In any case, the merchant should point out this fact to the customer in the shop already. The purchaser always authorizes the total checkout amount including a possible increase.

Create a capture

POST /api/checkout/v1/checkouts/{checkoutId}/captures
The endpoint for creating a capture is included as a captures link in the checkout resource, where it relates to an ORDER and the creation of further captures is still possible. It is recommended to always use the link from the checkout resource.

A new capture is triggered to call off an amount. The capture is initially in status PENDING after being generated until a check has been performed by the purchaser’s bank, which generally takes less than one second.

Request

Field Type Characteristics Description

amount

Number

Mandatory.
Between 0.01 and 50000.
Maximum two decimal places.

The payment amount in the currency of the original order. The maximum amount possible is EUR 50000.00.

finalCapture

Boolean

Optional.
Flag must be set to true for the last Capture of a [checkout] with activated overcapture flag.

Indicates whether the last amount was retrieved by this capture, especially if the amount of this payment is less than the total amount of the underlying order. The order is thus considered fully paid and is accordingly displayed to the customer as closed. Further captures are no longer possible for this order.

note

String

Optional.
Maximum 37 characters.

Free text field that appears on the bank statement in the payment reference.

merchantCaptureReferenceNumber

String

Optional.
Maximum 30 characters.

Merchant-internal reference number for this capture process.

merchantReconciliationReferenceNumber

String

Optional.
Maximum 30 characters.

Reconciliation number. This value will be inserted in the payment reference of the merchant payment.

captureInvoiceReferenceNumber

String

Optional.
Maximum 100 characters.

Merchant-internal unique invoice number for this capture process.

callbackUrlStatusUpdates

String

Optional.
Maximum 2000 characters.

URL of an endpoint of the merchant that giropay is going to call in order to notify about status updates.

deliveryInformation

Object

Optional.

Contains information about the delivery.

deliveryInformation.expectedShippingDate

String

Optional.
Timestamp in ISO 8601 format.

Expected shipping date.

deliveryInformation.logisticsProvider

String

Optional.

Parcel service provider.

deliveryInformation.trackingNumber

String

Optional.

Shipment number.

Response

The created capture is returned in the response. The structure is identical to the capture endpoint GET call.

In the HTTP header field Location, the URL of the created capture resource, including the transactionId, is included. The transactionId is similarly returned in the response body.

Return codes

Status code Message code Description

201 (Created)

The capture was created successfully.

400 (Bad Request)

VALIDATION_ERROR

The request is syntactically invalid.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

401 (Unauthorized)

UNAUTHORIZED

Access has been denied. Please contact giropay support.

404 (Not Found)

CHECKOUT_NOT_FOUND

The checkout was not found.

422 (Unprocessable Entity)

CAPTURE_AMOUNT_EXCEEDED

The total amount of all captures exceeds the total amount of the checkout.

422 (Unprocessable Entity)

CAPTURE_CHECKOUT_WRONG_TYPE

It is not possible to create a capture for this checkout type.

422 (Unprocessable Entity)

CAPTURE_ORDER_CLOSED

It is not possible to create a capture for a checkout that is already closed.

422 (Unprocessable Entity)

CAPTURE_ORDER_NOT_APPROVED

It is not possible to create a capture for an order that has not been confirmed by the buyer.

422 (Unprocessable Entity)

CAPTURE_NOT_AUTHORIZED

The amount of the capture is not authorized by the buyer’s bank.

422 (Unprocessable Entity)

MERCHANT_BANKACCOUNT_LOCKED

Your merchant account is blocked. Please contact giropay support.

422 (Unprocessable Entity)

CHECKOUT_REJECTED

The checkout was rejected. No capture can be created.

422 (Unprocessable Entity)

ACCOUNT_DEBOARDED

It is not possible to create a capture for a customer who is no longer participating in giropay.

Example

POST /api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2/captures HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "amount" : 10,
  "finalCapture" : false,
  "note" : "Thanks for shopping.",
  "merchantCaptureReferenceNumber" : "capture-21323",
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "captureInvoiceReferenceNumber" : "invoice-1234",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2023-01-20T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  }
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2/captures/eeced96a-2bd4-454d-a5ec-cb5dbcc8ea39
Content-Type: application/hal+json;charset=utf-8

{
  "type" : "CAPTURE_ORDER",
  "transactionId" : "eeced96a-2bd4-454d-a5ec-cb5dbcc8ea39",
  "amount" : 10,
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "finalCapture" : false,
  "merchantCaptureReferenceNumber" : "capture-21323",
  "captureInvoiceReferenceNumber" : "invoice-1234",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2023-01-20T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "status" : "SUCCESSFUL",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2/captures/eeced96a-2bd4-454d-a5ec-cb5dbcc8ea39"
    }
  }
}

Read a capture

GET /api/checkout/v1/checkouts/{checkoutId}/captures/{captureId}

The request provides the data of a specific capture. The capture transactions are embedded in the checkout resource. An explicit query of a capture transaction is generally not necessary.

Response

Field Type Characteristics Description

type

String

Always present.

Type of the capture transaction. Either CAPTURE_DIRECT_SALE or CAPTURE_ORDER. The value is automatically determined by the type of checkout.

transactionId

String

Always present.

Unique transaction ID of this capture (UUID consisting of 36 characters). The value is assigned by the giropay system.

amount

Number

Always present.

The payment amount in the currency of the original order. The maximum amount possible is EUR 50000.00.

finalCapture

Boolean

Present if provided at time of creation.

Indicates whether the last amount was retrieved by this capture, especially if the amount of this payment is less than the total amount of the underlying order. The order is thus considered fully paid and is accordingly displayed to the customer as closed. Further captures are no longer possible for this order.

merchantCaptureReferenceNumber

String

Present if provided at time of creation.

Merchant-internal reference number for this capture process.

merchantReconciliationReferenceNumber

String

Present if provided at time of creation.

Reconciliation number. This value will be inserted in the payment reference of the merchant payment.

captureInvoiceReferenceNumber

String

Present if provided at time of creation.

Merchant-internal unique invoice number for this capture process.

callbackUrlStatusUpdates

String

Present if provided at time of creation.

URL of the endpoint that should receive notifications about checkout status updates.

paymentInformationId

String

Does not exist until the transaction has been processed in the payment transaction.

An ID that belongs to this transaction. It is used to assign individual transactions to a collective entry.
UUID consisting of 36 characters.

status

String

Always present.

Indicates whether the authorization by the bank is still pending (PENDING), was successful (SUCCESSFUL), or was rejected (REJECTED). In case of SUCCESSFUL, the payment guarantee is given for this transaction.

deliveryInformation

Object

Present if provided at time of creation.

Contains information about the delivery.

deliveryInformation.expectedShippingDate

String

Present if provided at time of creation.

Expected shipping date.

deliveryInformation.logisticsProvider

String

Present if provided at time of creation.

Parcel service provider.

deliveryInformation.trackingNumber

String

Present if provided at time of creation.

Shipment number.

_links

Object

Links to resources and available actions.

Return codes

Status code Message code Description

200 (Ok)

The capture was successfully sent.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

CHECKOUT_NOT_FOUND

The checkout was not found.

404 (Not Found)

TRANSACTION_NOT_FOUND

The transaction was not found.

Example

GET /api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2/captures/eeced96a-2bd4-454d-a5ec-cb5dbcc8ea39 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "type" : "CAPTURE_ORDER",
  "transactionId" : "eeced96a-2bd4-454d-a5ec-cb5dbcc8ea39",
  "amount" : 10,
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "finalCapture" : false,
  "merchantCaptureReferenceNumber" : "capture-21323",
  "captureInvoiceReferenceNumber" : "invoice-1234",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "deliveryInformation" : {
    "expectedShippingDate" : "2023-01-20T12:00:00.000Z",
    "logisticsProvider" : "DHL",
    "trackingNumber" : "1234567890"
  },
  "status" : "SUCCESSFUL",
  "paymentInformationId" : "0000000-1111-2222-3333-444444444444",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/47debe70-54db-4b9e-8d61-9a06de50f3f2/captures/eeced96a-2bd4-454d-a5ec-cb5dbcc8ea39"
    }
  }
}

Callback for status updates

If merchants/PSPs pass a callback URL callbackUrlStatusUpdates when creating checkouts, the giropay system sends an HTTP request to this URL when the status of the checkout changes. Status updates are also sent for the embedded capture. In case of DIRECT_SALE status updates are also sent for the embedded capture. In case of connection errors or responses with an HTTP status code of 5xx, the giropay system will repeat the transmission of the status change up to 5 times within a time window of 24 hours. Status changes are always transmitted in the order in which they occurred at the checkout. If a status change cannot be transmitted, all subsequent status changes are also not transmitted until either the failed transmission could be made up for or all repeated attempts have failed.

POST callbackUrlStatusUpdates

Request

Field Type Characteristics Description

checkoutId

String

Always present.

UUID consisting of 36 characters for this checkout process. Assigned by the giropay system.

merchantOrderReferenceNumber

String

Always present.
Maximum 20 characters. SEPA-compliant characters only.

Merchant-internal, unique order number for this checkout process. Displayed to the customer in the transaction overview. Displayed to the merchant in the transaction overview. The order number is used in the debit note as instructionId and in the merchant’s and buyer’s payment reference.

transactionId

String

Always present.

Unique transaction ID of this refund (UUID consisting of 36 characters). The value is assigned by the giropay system.

merchantCaptureReferenceNumber

String

Optional.
Maximum 30 characters.

Merchant-internal reference number for this capture process.

captureStatus

String

Always present.

Indicates whether the authorization by the bank is still pending (PENDING), was successful (SUCCESSFUL), or was rejected (REJECTED). In case of SUCCESSFUL, the payment guarantee is given for this transaction.

statusUpdateTimestamp

String

Always present.

Timestamp of the status update.

sequenceNumber

Number

Always present.

Sequence number of the status update. Using the sequence number, a shop can track the order of status updates and identify missing status updates if any are present.
Example
POST /webhooktest/v1/capture/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "57f5fce2-9c06-4888-a150-fc5057ea338b",
  "merchantOrderReferenceNumber" : "order-A12223412",
  "transactionId" : "a65f682d-4152-4f8a-be80-b001509200b1",
  "captureStatus" : "SUCCESSFUL",
  "merchantCaptureReferenceNumber" : "f0972db2-7ffa-4432-ac2b-6af977611200",
  "statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
  "sequenceNumber" : 2
}

Response

The response does not contain a body and is not processed further by the giropay system. The HTTP status code should nevertheless allow conclusions to be drawn about the processing of the status notification for any service requests.

Example
HTTP/1.1 200 OK

Close an order (secured)

POST /api/checkout/v1/checkouts/{checkoutId}/close

Orders of the type ORDER can and should be closed in the giropay system if no further CAPTURE is being carried out for the order. With this, the order is no longer displayed to the customer as open.

Orders can only be closed if they have previously been confirmed by the customer via their account.

Request

The request does not require a request body.

Response

The created checkout is returned in the response. The structure is identical to the checkout endpoint GET call of the checkout.

Return Codes

Status code Message code Description

200 (OK)

The order was successfully closed.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

422 (Unprocessable Entity)

ORDER_NOT_APPROVED

The order has not been confirmed by the customer. Unconfirmed orders cannot be closed.

422 (Unprocessable Entity)

ORDER_ALREADY_CLOSED

The order is already closed.

422 (Unprocessable Entity)

NOT_AN_ORDER

This checkout is not of the type ORDER.

Refund

It is possible to trigger refunds to the customer for their orders.

The creation of a refund always relates to an entire checkout and not to a specific capture.

A refund is only possible following successful direct sales and orders with at least one successful capture. In this situation, a refunds link is present on the checkout resource. The refund amount is limited to a maximum of 200% of the total of the payments made to date.

Refunds are possible with no restriction as to timing and number, provided that the maximum amount to be refunded is not exceeded.

Create a refund

POST /api/checkout/v1/checkouts/{checkoutId}/refunds
The endpoint to create a refund is included as a refunds link in the checkout resource, where the checkout enables a refund. The endpoint should not be called up directly. The link from the checkout resource should always be used.

A refund to the customer is initiated by generating a refund resource.

Request

Field Type Characteristics Description

amount

Number

Mandatory.
Between 0.01 and 100000.
Maximum two decimal places.

The refund amount in the currency of the original order. The sum of refunds for an order is limited by the percentage value of the total value of the order given in the refundLimit field.

note

String

Optional.
Maximum 37 characters.

Free text field that appears on the bank statement in the payment reference (DIRECT_SALE only).

reason

String

Optional.

Reason for the refund
MERCHANT_TECHNICAL_PROBLEM: Technical problem during processing.
MERCHANT_CAN_NOT_DELIVER_GOODS: Merchant cannot deliver the goods.
REFUND_OBLIGINGNESS: Refund as a gesture of goodwill.
CUSTOMER_RETURN_GOODS: Refund due to return of goods.

merchantRefundReferenceNumber

String

Optional.
Maximum 30 characters.

Merchant-internal reference number for this refund process.

merchantReconciliationReferenceNumber

String

Optional.
Maximum 30 characters.

Reconciliation number. This value will be inserted in the payment reference of the merchant payment.

callbackUrlStatusUpdates

String

Optional.
Maximum 2000 characters.

URL of the endpoint that should receive notifications about checkout status updates.

Response

The data of the created refund is returned in the response. The structure is identical to the refund endpoint GET call.

In the HTTP header field Location, the URL of the created refund resource, including transactionId, is included. The transactionId is similarly returned in the response body.

Return codes

Status code Message code Description

201 (Refund created)

The refund was successfully created. It has the status PENDING.

400 (Bad Request)

VALIDATION_ERROR

The request is syntactically invalid.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

401 (Unauthorized)

UNAUTHORIZED

Access has been denied. Please contact giropay support.

404 (Not Found)

CHECKOUT_NOT_FOUND

The checkout was not found, or you do not have access to this checkout.

422 (Unprocessable Entity)

REFUND_AMOUNT_EXCEEDED

The total amount of all refunds exceeds the maximum possible refund amount.

422 (Unprocessable Entity)

USER_DEBOARDED

The buyer’s account was closed permanently.

Example

POST /api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9/refunds HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "amount" : 10,
  "note" : "Your order from 15.01.2023",
  "merchantRefundReferenceNumber" : "refund-99989",
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status"
}
HTTP/1.1 201 Created
Location: https://api.paydirekt.de/api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9/refunds/cb53fa17-b0a8-44da-bc5a-0f113616ae85
Content-Type: application/hal+json;charset=utf-8

{
  "type" : "REFUND",
  "transactionId" : "cb53fa17-b0a8-44da-bc5a-0f113616ae85",
  "amount" : 10,
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "note" : "Your order from 15.01.2023",
  "merchantRefundReferenceNumber" : "refund-99989",
  "status" : "PENDING",
  "reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "merchantRefundSettled" : false,
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9/refunds/cb53fa17-b0a8-44da-bc5a-0f113616ae85"
    }
  }
}

Read a refund

GET /api/checkout/v1/checkouts/{checkoutId}/refunds/{refundId}

Provides the data on a refund. After a refund is initiated, the refund is in the status PENDING for at least one day. It is recommended to read the status once or twice per day until a final status (SUCCESS or FAILED) is reached.

The refund transactions are embedded in the checkout resource. Refund information can therefore also be read via the associated checkout.

Response

Field Type Characteristics Description

type

String

Always present.

Type of the transaction. Here always REFUND.

transactionId

String

Always present.

Unique transaction ID of this refund (UUID consisting of 36 characters). The value is assigned by the giropay system.

amount

Number

Always present.

The refund amount in the currency of the original order. The sum of refunds for an order is limited by the percentage value of the total value of the order given in the refundLimit field.

note

String

Present if provided at time of creation.

Free text field that appears on the bank statement in the payment reference (DIRECT_SALE only).

reason

String

Present if provided at time of creation.

Reason for the refund
MERCHANT_TECHNICAL_PROBLEM: Technical problem during processing.
MERCHANT_CAN_NOT_DELIVER_GOODS: Merchant cannot deliver the goods.
REFUND_OBLIGINGNESS: Refund as a gesture of goodwill.
CUSTOMER_RETURN_GOODS: Refund due to return of goods.
TECHNICAL_PROBLEM: Technical problem during processing/refund.
MERCHANT_CAN_NOT_PROOF_SHIPMENT: Merchant cannot provide proof of the shipment via dispatch note (Dispute).
REFUND_ON_BEHALF_OF_MERCHANT: Refund on behalf of the merchant.
REFUND_NOT_ON_BEHALF_OF_MERCHANT: Refund not on behalf of the merchant.
REFUND_MERCHANT_FRAUD: Refund due to fraud.

merchantRefundReferenceNumber

String

Present if provided at time of creation.

Merchant-internal reference number for this refund process.

merchantReconciliationReferenceNumber

String

Present if provided at time of creation.

Reconciliation number. This value will be inserted in the payment reference of the merchant payment.

paymentInformationId

String

Does not exist until the transaction has been processed in the payment transaction.

An ID that belongs to the transaction. It is used to assign individual transactions to a collective entry.
UUID consisting of 36 characters.

callbackUrlStatusUpdates

String

Present if provided at time of creation.

URL of the endpoint that should receive notifications about checkout status updates.

status

String

Always present.

Status of the refund
PENDING: Initial status. The refund is processed in the payment transaction.
ERROR: The repayment process is temporarily interrupted for technical reasons.
SUCCESSFUL: The refund was successful. The amount has already been transferred to the buyer’s account or is being processed by the buyer’s bank.
FAILED: It was definitely not possible to process the refund in the payment transaction, and it must be re-initiated.

_links

Object

Links to resources and available actions.

Return codes

Status code Message code Description

200 (Ok)

The request was processed correctly.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

CHECKOUT_NOT_FOUND

The checkout was not found, or access to this checkout is not possible.

404 (Not Found)

TRANSACTION_NOT_FOUND

No refund with the provided refundId was found.

Example

GET /api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9/refunds/cb53fa17-b0a8-44da-bc5a-0f113616ae85 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "type" : "REFUND",
  "transactionId" : "cb53fa17-b0a8-44da-bc5a-0f113616ae85",
  "amount" : 10,
  "merchantReconciliationReferenceNumber" : "recon-1234",
  "note" : "Your order from 15.01.2023",
  "merchantRefundReferenceNumber" : "refund-99989",
  "status" : "PENDING",
  "reason" : "MERCHANT_CAN_NOT_DELIVER_GOODS",
  "callbackUrlStatusUpdates" : "https://toy-car-delivery.com/callback/status",
  "merchantRefundSettled" : false,
  "paymentInformationId" : "0000000-1111-2222-3333-444444444444",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/4321bdd2-8ecf-41ec-91c5-6e9bcea45eb9/refunds/cb53fa17-b0a8-44da-bc5a-0f113616ae85"
    }
  }
}

Read buyer account information for eps refunds

GET /api/checkout/v1/checkouts/{checkoutId}/buyeraccount

Can be used to request buyer account information for eps related refund processes. The checkout must be approved, in order for the link to be part of the response.

Response

Field Type Characteristics Description

iban

String

Initially absent, but then always present, once the checkout’s payment has been processed.

The iban of the buyer.

bic

String

Initially absent, but then always present, once the checkout’s payment has been processed.

The bic of the buyer.

owner

String

Initially absent. Optionally present after the checkout’s payment has been processed.

The name of the buyer.

_links

Object

Present if the checkout is approved.

Link to the bank account information of the buyer for a refund. This link is only available if the checkout has been approved by the buyer.

Return codes

Status code Message code Description

200 (Ok)

The request was processed correctly.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

CHECKOUT_NOT_FOUND

The checkout was not found, or access to this checkout is not possible.

422 (Unprocessable Entity)

CHECKOUT_NOT_APPROVED

The checkout has not been approved yet.

Example

GET /api/checkout/v1/checkouts/749b976f-c5cc-47ad-90f3-d733e954f012/buyeraccount HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "iban" : "buyerIban",
  "bic" : "buyerBic",
  "owner" : "buyerName",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/checkout/v1/checkouts/749b976f-c5cc-47ad-90f3-d733e954f012/buyeraccount"
    }
  }
}

Callback for status updates

Merchants/PSPs can transfer a callback URL callbackUrlStatusUpdates when creating a refund. The giropay system sends an HTTP request to that URL in the event of refund status changes. In the case of connection errors or responses with an HTTP status code 5xx, the giropay system will repeat the transmission of the status change up to 5 times in a time window of 20 minutes. If a status change cannot be transmitted, all subsequent status changes are also not transmitted until either the failed transmission could be made up for or all repeated attempts have failed.

POST callbackUrlStatusUpdates

Request

Field Type Characteristics Description

checkoutId

String

Always present.

UUID consisting of 36 characters for this checkout process. Assigned by the giropay system.

transactionId

String

Always present.

Unique transaction ID of this refund (UUID consisting of 36 characters). The value is assigned by the giropay system.

merchantRefundReferenceNumber

String

Optional.
Maximum 30 characters.

Merchant-internal reference number for this refund process.

merchantReconciliationReferenceNumber

String

Optional.
Maximum 30 characters.

Reconciliation number. This value will be inserted in the payment reference of the merchant payment.

refundStatus

String

Always present.

Status of the refund
PENDING: Initial status. The refund is processed in the payment transaction.
ERROR: The repayment process is temporarily interrupted for technical reasons.
SUCCESSFUL: The refund was successful. The amount has already been transferred to the buyer’s account or is being processed by the buyer’s bank.
FAILED: It was definitely not possible to process the refund in the payment transaction, and it must be re-initiated.

statusUpdateTimestamp

String

Always present.

Timestamp of the status update.

sequenceNumber

Number

Always present.

Sequence number of the status update. Using the sequence number, a shop can track the order of status updates and identify missing status updates if any are present.
Example
POST /webhooktest/v1/refund/status HTTP/1.1
Content-Type: application/json;charset=utf-8

{
  "checkoutId" : "c13bfc03-390b-4108-8a79-c43860218828",
  "transactionId" : "f3deab5a-1957-420b-9671-f1efe213348e",
  "merchantRefundReferenceNumber" : "refund-12345",
  "merchantReconciliationReferenceNumber" : "reconciliation-12345",
  "refundStatus" : "SUCCESSFUL",
  "statusUpdateTimestamp" : "2020-01-01T12:00:00.000Z",
  "sequenceNumber" : 2
}

Response

The response does not contain a body and is not processed further by the giropay system. The HTTP status code should nevertheless allow conclusions to be drawn about the processing of the status notification for any service requests.

Example
HTTP/1.1 200 OK

Reports

Merchants, technical PSPs, and giropay PSPs can retrieve reports about the transactions performed by the shops or merchants assigned to them. Technical PSPs can retrieve all their reports or only the reports for a specific shop by providing the shop’s X-Auth-Code and X-Auth-Key when obtaining the access token.

The query can be restricted by optional from and to parameters that specify the time frame of the report. If omitted, to will be set to the current time; from will be set to 30 days before to if not specified.

The report can cover a maximum of 180 days or 100000 transactions. If one of the two values is exceeded, an error is returned. In this occurs, a smaller time frame must be selected.

The format of the report is specified by providing the Accept header. Valid values are application/json and text/csv.

Read transactions (V1)

This endpoint will be deprecated and no longer operated by the end of 2023. Please consider using Read transactions (V2) 
GET /api/reporting/v1/reports/transactions

Request

Name Constraints Description

from

Optional.

Timestamp in ISO 8601 format starting from which transactions are taken into account. If not specified, 30 days since the to timestamp are queried, i.e., the from timestamp is implicitly set to the to timestamp minus 30 days.

to

Optional.

Timestamp in ISO 8601 format until which transactions are taken into account. If not specified, queried up to the current time.

fields

Optional. Possible field identifiers are case-sensitive and enumerated under transactions (v1).

A list of field identifiers for transactions (v1). For the transaction report in CSV format, fields determines the columns included and their order. For the transaction report in JSON format, fields determines the included fields. If fields is not specified, the transaction report will contain all possible fields as enumerated in transactions (v1).

Response

Field Type Characteristics Description

transactions

Array

Always present. Can be an empty list.

List of transactions (v1) that represent the requested report.

Transaction (V1)

Each reporting record represents one transaction. The records are sorted in ascending order by transactionDate.

Field Type Characteristics Description

correlationId

String

UUID consisting of 36 characters.

The transaction number of the checkout to enable a unique assignment.

endToEndReferenceNumber

String

UUID consisting of 32 characters plus prefix PD.

End-to-end checkout reference number.

transactionTypeId

String

1 (Direct Sale),
2 (Refund),
3 (Order),
4 (Rejected capture),
5 (Successful capture of an order),
6 (Canceled order),
7 (Successful overcapture),
8 (Secured order),
11 (Capture of a secured order)

Code of the transaction type.

transactionDate

String

Timestamp in ISO 8601 format.

Time of the transaction.

valueDate

String

Date in ISO 8601 format.

Value date of the transaction.

acquirerId

String

UUID consisting of 36 characters.

Unique ID of the acquirer.

acquirerName

String

Maximum 100 characters.

Name of the acquirer.

agreementSetId

String

UUID consisting of 36 characters.

Unique ID of the acquirer agreement set.

pspId

String

UUID consisting of 36 characters.

Unique ID of the psp.

pspName

String

Maximum 100 characters.

Name of the psp.

contractId

String

UUID consisting of 36 characters.

Unique ID of the merchant contract.

merchantId

String

UUID consisting of 36 characters.

Unique ID of the merchant.

merchantName

String

Maximum 100 characters.

Name of the merchant.

merchantReference

String

Maximum 20 characters. Only SEPA compliant characters.

Merchant-internal, unique order number for this checkout transaction. Corresponds to the merchantOrderReferenceNumber passed when creating the checkout.

merchantIbanRecipientName

String

Maximum 100 characters.

Name of the owner of the merchant’s bank account.

merchantIban

String

Maximum 34 characters, usually 22.

IBAN of the merchant.

merchantBic

String

BIC in ISO 9362 format. Either 8 or 11 characters.

BIC of the merchant.

checkoutId

String

UUID consisting of 36 characters.

Unique ID of the checkout.

checkoutInvoiceNr

String

Maximum 20 characters.

The merchantInvoiceReferenceNumber passed by the PSP when creating the checkout.

merchantTransactionReferenceNumber

String

Merchant-internal, unique order number for this capture or refund transaction. Corresponds to the merchantCaptureReferenceNumber or the merchantRefundReferenceNumber passed at creation, depending on the transaction type.

merchantBankId

String

UUID consisting of 36 characters.

Unique ID of the merchant’s bank.

buyerBankId

String

UUID consisting of 36 characters.

Unique ID of the buyer’s bank.

buyerBankName

String

Maximum 100 characters.

Short name of the buyer’s bank.

transactionAmount

Number

Between 0.01 and 50000.
Maximum two decimal points.

The amount of the transaction.

transactionCurrency

String

Currently, always EUR.

Currency of the transaction.

merchantAgentId

String

UUID consisting of 36 characters.

Unique ID of the merchant concentrator.

merchantAgentName

String

Maximum 100 characters.

Name of the merchant concentrator.

concentratorId

String

UUID consisting of 36 characters.

Unique ID of the buyer’s concentrator.

concentratorName

String

Maximum 100 characters.

Name of the buyer’s concentrator.

shopId

String

UUID consisting of 36 characters.

Unique ID of the shop.

shopName

String

Maximum 100 characters.

Name of the shop.

ageVerificationStatus

String

0 (not checked),
1 (passed),
2 (not passed)

Result of the age verification.

MCC

String

Four-digit number.

MCC (Merchant Category Code) of the merchant.

DBI

String

Four-digit number.

DBI (Details Business Indicator) of the merchant. The field is currently always empty.

paydirektExpress

String

y (express)
n (non-express)

Indicates whether the checkout is an express checkout or not.

paymentInformationId

String

UUID consisting of 36 characters.

Unique ID of the SEPA transaction.

refundReason

String

MERCHANT_TECHNICAL_PROBLEM: Technical problem during processing.
MERCHANT_CAN_NOT_DELIVER_GOODS: Merchant cannot deliver the goods.
REFUND_OBLIGINGNESS: Refund as a gesture of goodwill.
TECHNICAL_PROBLEM: Technical problem during processing/refund.
MERCHANT_CAN_NOT_PROOF_SHIPMENT: Merchant cannot provide proof of shipment via dispatch note (Dispute).
REFUND_ON_BEHALF_OF_MERCHANT: Refund on behalf of the merchant.
REFUND_NOT_ON_BEHALF_OF_MERCHANT: Refund not on behalf of the merchant.
REFUND_MERCHANT_FRAUD: Refund due to fraud.

The reason provided on refund creation.

captureInvoiceNr

String

Maximum 20 characters.

The captureInvoiceReferenceNumber provided by the PSP when creating the capture.

validityDate

String

Date in ISO 8601 format.

Warranty period for secured orders (ORDER_SECURED). Captures within this period are guaranteed for the merchant.

Return codes

Status code Message code Description

200 (Ok)

The request was processed correctly.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

You do not have access to this resource. The authentication may be missing.

422 (Unprocessable Entity)

INVALID_FIELD_NAME

At least one of the field names provided via fields could not be assigned to a transaction field.

422 (Unprocessable Entity)

REPORT_RANGE_TOO_LARGE

The report either exceeded the 180 days limit or contained more than 100000 elements.

Example

GET /api/reporting/v1/reports/transactions?from=2023-02-24T11:12:13.140Z&to=2023-03-06T11:12:13.140Z&fields= HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "transactions" : [ {
    "correlationId" : "4af17d87-456d-4bf5-b459-ed4d972d18bf",
    "endToEndReferenceNumber" : "6209db30-cf60-4a68-9348-32631e5e30f0",
    "transactionTypeId" : "1",
    "transactionDate" : "2023-03-01T11:12:13.140Z",
    "valueDate" : "2023-03-01",
    "acquirerId" : "b07f15ba-c427-49ec-bfcf-cd87ceb1cb0f",
    "acquirerName" : "acquirer name",
    "agreementSetId" : "549b1af4-e3cb-4ad1-8f36-734f13f63d9f",
    "pspId" : "b07f15ba-c427-49ec-bfcf-cd87ceb1cb0f",
    "pspName" : "merchantPspIntermediaryName",
    "merchantId" : "c6e9e6c0-af39-4214-bba0-09f978d46b67",
    "merchantName" : "Some merchant name",
    "merchantReference" : "38cec30b-8b93-4ba3-bf52-dc20402174d8",
    "merchantIbanRecipientName" : "merchantIbanRecipientName",
    "merchantIban" : "merchantIban",
    "merchantBic" : "merchantBic",
    "checkoutId" : "2619da71-0113-4089-b6ae-760642ebc93d",
    "checkoutInvoiceNr" : "2cd56523-aa40-4678-a997-63087013e1c7",
    "merchantBankId" : "f934638a-ed5c-4967-a21f-1dd10b426254",
    "transactionAmount" : "1.00",
    "transactionCurrency" : "transactionCurrency",
    "shopId" : "f117f63d-5da8-4fb5-8f02-29071a5aeb78",
    "shopName" : "some shop name",
    "ageVerificationStatus" : "1",
    "MCC" : "742",
    "paydirektExpress" : "n",
    "paymentInformationId" : "b66d78e8-b701-45e7-b944-97b7a40982f4",
    "refundReason" : "TECHNICAL_PROBLEM",
    "captureInvoiceNr" : "dcb27c42-f95b-49aa-ba9e-4388edf36aa6",
    "validityDate" : "2023-07-29"
  } ]
}

Read transactions (V2)

GET /api/reporting/v2/reports/transactions

Request

Name Constraints Description

from

Optional.

Timestamp in ISO 8601 format starting from which transactions are taken into account. If not specified, 30 days since the to timestamp are queried, i.e., the from timestamp is implicitly set to the to timestamp minus 30 days.

to

Optional.

Timestamp in ISO 8601 format until which transactions are taken into account. If not specified, queried up to the current time.

Response

Field Type Characteristics Description

transactions

Array

Always present. Can be an empty list.

List of transactions (v2) that represent the requested report.

Transaction (V2)

Each reporting record represents one transaction. The records are sorted in ascending order by transactionDate.

The fields transactionFeeNet, fromThatTransactionFeeFixNet, fromThatTransactionOperatorFeePercentageNet, and fromThatTransactionGuaranteeFeePercentageNet are only available from the first day of the following month onwards.
Field Type Characteristics Description

correlationId

String

UUID consisting of 36 characters.

The transaction number of the checkout to enable a unique assignment.

endToEndReferenceNumber

String

UUID consisting of 32 characters plus prefix PD.

End-to-end checkout reference number.

transactionTypeId

String

1 (Direct Sale),
2 (Refund),
3 (Order),
4 (Rejected capture),
5 (Successful capture of an order),
6 (Canceled order),
7 (Successful overcapture),
8 (Secured order),
11 (Capture of a secured order)

Code of the transaction type.

transactionDate

String

Timestamp in ISO 8601 format.

Time of the transaction.

valueDate

String

Date in ISO 8601 format.

Value date of the transaction.

transactionAmount

Number

Between 0.01 and 50000.
Maximum two decimal points.

The amount of the transaction.

transactionCurrency

String

Currently, always EUR.

Currency of the transaction.

paymentInformationId

String

UUID consisting of 36 characters.

Unique ID of the SEPA transaction.

checkoutId

String

UUID consisting of 36 characters.

Unique ID of the checkout.

merchantCustomerNumber

String

Maximum 50 characters.

Merchant-internal customer number of the buyer.

merchantOrderReferenceNumber

String

Maximum 20 characters. SEPA-compliant characters only.

Merchant-internal, unique order number for this checkout process. Displayed to the customer in the transaction overview. Displayed to the merchant in the transaction overview. The order number is used in the debit note as instructionId and in the merchant’s and buyer’s payment reference.

merchantReconciliationReferenceNumber

String

Maximum 30 characters.

Reconciliation number. This value will be inserted in the payment reference of the merchant payment.

merchantInvoiceReferenceNumber

String

Maximum 100 characters.

Merchant-internal, unique invoice number for this purchase or payment transaction. Displayed to the merchant in the transaction overview.

merchantCaptureReferenceNumber

String

Maximum 30 characters.

Merchant-internal reference number for this capture process.

captureInvoiceReferenceNumber

String

Maximum 100 characters.

Merchant-internal unique invoice number for this capture process.

merchantRefundReferenceNumber

String

Maximum 30 characters.

Merchant-internal reference number for this refund process.

refundReason

String

MERCHANT_TECHNICAL_PROBLEM: Technical problem during processing.
MERCHANT_CAN_NOT_DELIVER_GOODS: Merchant cannot deliver the goods.
REFUND_OBLIGINGNESS: Refund as a gesture of goodwill.
TECHNICAL_PROBLEM: Technical problem during processing/refund.
MERCHANT_CAN_NOT_PROOF_SHIPMENT: Merchant cannot provide proof of shipment via dispatch note (Dispute).
REFUND_ON_BEHALF_OF_MERCHANT: Refund on behalf of the merchant.
REFUND_NOT_ON_BEHALF_OF_MERCHANT: Refund not on behalf of the merchant.
REFUND_MERCHANT_FRAUD: Refund due to fraud.

The reason provided on refund creation.

validityDate

String

Date in ISO 8601 format.

Warranty period for secured orders (ORDER_SECURED). Captures within this period are guaranteed for the merchant.

ageVerificationStatus

String

0 (not checked),
1 (passed),
2 (not passed)

Result of the age verification.

transactionFeeNet

Number

Maximum 6 decimal places.

Net amount of the fee for the transaction (fees for the operator and variable fee for the payment guarantee).
Only available from the first day of the following month onwards.

fromThatTransactionFeeFixNet

Number

Maximum 6 decimal places.

Fixed portion of the net amount transaction fee for the operator.
Only available from the first day of the following month onwards.

fromThatTransactionOperatorFeePercentageNet

Number

Maximum 6 decimal places.

Variable portion of the net amount transaction fee for the operator.
Only available from the first day of the following month onwards.

fromThatTransactionGuaranteeFeePercentageNet

Number

Maximum 6 decimal places.

Variable portion of the net amount transaction fee for the payment guarantee.
Only available from the first day of the following month onwards.

shopId

String

UUID consisting of 36 characters.

Unique ID of the shop.

shopName

String

Maximum 100 characters.

Name of the shop.

shopIban

String

Maximum 34 characters, usually 22.

IBAN of the shop.

shopBic

String

BIC in ISO 9362 format. Either 8 or 11 characters.

BIC of the shop.

shopIbanRecipientName

String

Maximum 100 characters.

Name of the owner of the shop’s bank account.

collectingEnabled

Boolean

Either true, false, or null.

Determines if the merchant or the psp is collecting:
true for collecting merchant,
false for collecting psp,
null for non-giropay merchant.

merchantId

String

UUID consisting of 36 characters.

Unique ID of the merchant.

merchantName

String

Maximum 100 characters.

Name of the merchant.

merchantIban

String

Maximum 34 characters, usually 22.

IBAN of the merchant.

merchantCountry

String

Exactly 2 characters.

The country code in alpha-2 format.

MCC

String

Four-digit number.

Merchant Category Code of the merchant.

pspId

String

UUID consisting of 36 characters.

Unique ID of the psp.

pspName

String

Maximum 100 characters.

Name of the psp.

acquirerId

String

UUID consisting of 36 characters.

Unique ID of the acquirer.

acquirerName

String

Maximum 100 characters.

Name of the acquirer.

agreementSetId

String

UUID consisting of 36 characters.

Unique ID of the acquirer agreement set.

agreementSetName

String

Maximum 100 characters.

Name of the acquirer agreement set.

scheme

String

Either EPS or not present.

Indicates whether a transaction is an EPS transaction.

Return codes

Status code Message code Description

200 (Ok)

The request was processed correctly.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

You do not have access to this resource. The authentication may be missing.

422 (Unprocessable Entity)

REPORT_RANGE_TOO_LARGE

The report either exceeded the 180 days limit or contained more than 100000 elements.

Example

GET /api/reporting/v2/reports/transactions?from=2023-02-24T11:12:13.140Z&to=2023-03-06T11:12:13.140Z HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "transactions" : [ {
    "correlationId" : "d61a0d7a-c46c-4201-84d8-00ee2cd1e9f0",
    "endToEndReferenceNumber" : "705248bf-c20d-4644-ba41-5bf4a90d2e6f",
    "transactionTypeId" : "1",
    "transactionDate" : "2023-03-01T11:12:13.140Z",
    "valueDate" : "2023-03-01",
    "transactionAmount" : "1",
    "transactionCurrency" : "transactionCurrency",
    "paymentInformationId" : "d9aafdb1-6af5-47cb-badc-e1282b14d0fa",
    "checkoutId" : "40762464-e6e4-4f40-ad0d-3b0f11a44997",
    "merchantCustomerNumber" : "376f64b1-bc40-4b80-9670-c2b837b6e71a",
    "merchantOrderReferenceNumber" : "39f9ea81-4eec-4db2-a13f-30800798ca70",
    "merchantReconciliationReferenceNumber" : "25b8c965-1172-4271-bc65-daab0512c38c",
    "merchantInvoiceReferenceNumber" : "8ffae84b-939c-49ce-be34-3a63c8b4c4f5",
    "merchantCaptureReferenceNumber" : "7de8e656-ee03-4b04-86ce-a0e20423c8a1",
    "captureInvoiceReferenceNumber" : "e93114e7-33db-483e-a7b9-7be19f48af12",
    "merchantRefundReferenceNumber" : "dd9f24cb-6cc1-4057-a71c-802f20fdf5ed",
    "refundReason" : "TECHNICAL_PROBLEM",
    "validityDate" : "2023-07-29",
    "ageVerificationStatus" : "1",
    "transactionFeeNet" : "0.5",
    "fromThatTransactionFeeFixNet" : "0.2",
    "fromThatTransactionOperatorFeePercentageNet" : "0.1",
    "fromThatTransactionGuaranteeFeePercentageNet" : "0.2",
    "shopId" : "556bce3c-6963-4036-98ea-6b428e748a69",
    "shopName" : "some shop name",
    "shopBic" : "merchantBic",
    "shopIbanRecipientName" : "merchantIbanRecipientName",
    "merchantId" : "8526427e-24de-4106-b313-c8b880a17ae4",
    "merchantName" : "Some merchant name",
    "merchantIban" : "merchantIban",
    "MCC" : "742",
    "pspId" : "aeb07647-ce35-4c56-bc5c-d4e1b25df299",
    "pspName" : "merchantPspIntermediaryName",
    "acquirerId" : "aeb07647-ce35-4c56-bc5c-d4e1b25df299",
    "acquirerName" : "some acquirer name",
    "scheme" : "EPS",
    "acquirerAgreementSetId" : "d2f4cb54-53c4-4df3-8c0c-c842faf50aea",
    "acquirerAgreementSetName" : "some acquirer agreement set name"
  } ]
}

Common data types

Besides the standard JSON data types, there are complex data types that are needed for a correct request.

ShippingAddress

Data type for shipping and billing addresses.

Field Type Characteristics Description

addresseeGivenName

String

Optional for shopping carts categorized as AUTHORITIES_PAYMENT or ANONYMOUS_DONATION. Mandatory otherwise.
Maximum 100 characters.

First name.

addresseeLastName

String

Optional for shopping carts categorized as AUTHORITIES_PAYMENT or ANONYMOUS_DONATION. Mandatory otherwise.
Maximum 100 characters.

Last name.

company

String

Optional.
Maximum 100 characters.

Company name.

additionalAddressInformation

String

Optional.
Maximum 100 characters.

Additional address information.

street

String

Optional.
Maximum 100 characters.

The name of the street, without building number.

streetNr

String

Optional.
Maximum 10 characters.

The building number.

zip

String

Optional for shopping carts categorized as DIGITAL, AUTHORITIES_PAYMENT, or ANONYMOUS_DONATION. Mandatory otherwise.
Maximum 10 characters.

The postal code.

city

String

Optional for shopping carts categorized as DIGITAL, AUTHORITIES_PAYMENT, or ANONYMOUS_DONATION. Mandatory otherwise.
Maximum 100 characters.

The town or city.

countryCode

String

Optional for shopping carts categorized as DIGITAL, AUTHORITIES_PAYMENT, or ANONYMOUS_DONATION. Mandatory otherwise.
2 characters.

The country code in ISO 3166-1 format.

state

String

Optional.
Maximum 100 characters.

State or province. Can be used for addresses outside Germany, for example.

emailAddress

String

Mandatory for shopping carts categorized as DIGITAL. Optional otherwise.
Must be a valid email address.

The email address of the buyer.

 
{
  "addresseeGivenName" : "Patrick",
  "addresseeLastName" : "Schmitt",
  "street" : "Beethovenstr.",
  "streetNr" : "1",
  "zip" : "12345",
  "city" : "Berlin",
  "countryCode" : "DE",
}

Example of an international address with state

{
  "addresseeGivenName" : "John",
  "addresseeLastName" : "Smith",
  "street" : "Main St",
  "streetNr" : "799 E",
  "zip" : "85705",
  "city" : "Tucson",
  "countryCode" : "US",
  "state" : " AZ
}

Item

An item is a shopping cart item.

Field Type Characteristics Description

quantity

Number

Mandatory.
Integer.
Minimum 1.

The number of this kind of item within cart.

name

String

Mandatory.
Maximum 100 characters.

The name of the item.

ean

String

Optional.
Maximum 100 characters.

The International Article Number (EAN or GTIN) of the item.

price

Number

Mandatory.
Positive or negative.
Maximum 2 decimal places.

The unit price of an item, including taxes. In the case of credit notes (e.g., in the form of vouchers or coupons), the amount can also be negative.

 
{
  "quantity" : 3,
  "name" : "Bobbycar",
  "ean" : "800001303",
  "price" : 25.99
}

Message

Messages and especially error messages. For details on error handling see Error messages.

Field Type Characteristics Description

code

String

Mandatory.
Maximum 100 characters.

The unique error code for this error.

severity

String

Mandatory.

The error level. The possible values are: ERROR, WARN and INFO.

path

String

Optional.
Maximum 1000 characters.

The field for which this error was generated. This field is filled in case of a VALIDATION_ERROR (response code 400).

reasonCode

String

Optional.
Maximum 1000 characters.

The reason for this error as a unique code if this is not clear from the code field. The reasonCode is meant mainly for debugging purposes; no logic should be implemented on it.

logref

String

Optional.
Maximum 1000 characters.

A giropay-internal reference number for this error message. Please always quote this reference number in support requests.

content

String

Optional.

The invalid content in case of a CONVERSION_ERROR.

 
{
  "code" : "VALIDATION_ERROR",
  "severity" : "ERROR",
  "path" : "currency",
  "reasonCode" : "INVALID_FORMAT",
  "logref" : "934180ed-ef93-4af1-835a-3071714fdce5:8t1ph9gFha1"
}

Character set

As a general rule, data passed via HTTP request must be UTF-8 encoded. Only the following characters are accepted in String type fields, unless otherwise specified:

  • All letters in the Unicode category Letter

  • All numbers in the Unicode category Number

  • The following special characters: .-!#$%&'*+/=?^_’`´{|}~"(),:;<>@[]

  • Space and non-breaking space

  • Linebreak and line feed

giropay also serves all responses in UTF-8. In general, it should be noted that there is no guarantee that non-SEPA-compliant characters will be displayed correctly, or at all, in all systems (especially on the bank side, e.g. on account statements).

SEPA-compliant characters

In SEPA payments, only characters of the restricted SWIFT Latin character set are allowed according to Annex 3 of the DFÜ Agreement:

  • a b c d e f g h i j k l m n o p q r s t u v w x y z

  • A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

  • 0 1 2 3 4 5 6 7 8 9

  • ' : ? , - ( + . ) /

The restricted character set therefore does not include in particular: Umlauts, the € symbol, certain special characters such as the underscore, the space character or square brackets.

In addition, references, identifications and identifiers are not allowed either to start or to end with a slash „/“ or to contain a double slash „//“.

To ensure that there are no disruptions in payment transactions, only the approved characters may be used for appropriately marked attributes.

In case of use of unauthorized characters or improper use of authorized characters, a payment or even an entire payment container may be rejected.

Changelog

The following table summarizes all changes to this document.

Date Type Description Section

03.07.2023

NEW FEATURE

Added checkout scheme to read checkout.

Read a checkout

09.06.2023

NEW FEATURE

Added field description for scheme.

Transaction (V2)

05.06.2023

NEW FEATURE

Added section Read buyer account information for eps refunds.

EPS refund buyer account information

02.05.2023

NEW INFO

Added information regarding the checkout expiry time of Online-Überweisung.

Create a checkout

14.04.2023

NEW FEATURE

Added checkout scheme to request.

Create a checkout

31.03.2023

FIX

Fixed minor typos
1. Added missing backtick to display monospace correctly.
2. Added usage of correct possessive apostrophe

1. ShippingAddress
2. Several sections of the document

20.03.2023

CHANGE

Added missing field descriptions and reordered field descriptions.

Transactions (V1)

10.03.2023

NEW FEATURE

Added description for version 2 of endpoint.

Read transactions (V2)

10.03.2023

CHANGE

Marked endpoint version 1 as deprecated until end of 2023.

Read transactions (V1)

07.02.2023

CHANGE

Removed transactionTypeId 9 and 10, added transactionTypeId 11.

Reports