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) for administering giropay merchant data.

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 giropay PSP

The giropay system enables giropay payment service providers (giropay PSPs) to administer their merchants via an API. An existing merchant can be administered by its owning giropay PSP (meaning the PSP that created the merchant via API) and by the giropay psp owning the agreement set which is currently assigned to that merchant (acquirer), see agreement set administration

An API key procedure in conjunction with OAuth2 is used to authenticate a giropay PSP. For this purpose, the giropay PSP must have one of its own API keys and the corresponding API secret. The giropay PSP can have its own API keys and secrets created in the intermediary portal.

To create and handle checkouts on behalf of one of its merchants, the giropay PSP additionally has to provide a corresponding merchant authorization reference during authentication. The merchant authorization reference is automatically generated when creating a shop of a merchant and thus can be obtained via a GET call of the merchant’s shop data (see the sections on creating and reading shops).

For merchant administration, only the API key and API secret of the giropay PSP must be transmitted when issuing the access token. A merchantAuthorizationReference is necessary when processing checkouts to identify the associated merchant.

Definition of terms

API key

The API key is used to identify a giropay PSP. An API key can be created and deactivated in the intermediary portal at any time. 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 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 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-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-PSP in case of a giropay PSP.

By comparison with Basic Auth or a simple hash signature, the HMAC-based API key procedure affords 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.

For the merchant administration, only the fields X-Auth-Key-PSP and X-Auth-Code-PSP have to be passed.

Request

Field Type Characteristics Description

Header fields

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

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-PSP or 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-PSP.

401 (Unauthorized)

API_KEY_IN_REQUEST_INACTIVE

The API key is disabled.

401 (Unauthorized)

API_KEY_REQUEST_SIGNATURE_INVALID

The 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" : "w8d2D2wdoO7CnFrBXAZCIYivneVnUv-uI0kwcfa_1LtS7-ysX3QgeVv2qVGm1Ktz1eDwOQTFFBB6HIr0Mcw656VqwGF0ossAz32jbB-koJaZr_ibCQNxV18kjoCvESTyKrJnI2p8a0D8SPrgYXD-g4likvP0OvCJh0bUvQyFU8ndY2H_o5L-8Kk0i3Gt4GDADb2toHOOyR2d1EKaT-4ON021RZf4_PTe9T2i1qJw4lwsls4GMqgLNyhTd8Y6_kPlMHHefavxzX2jCCyORmwGYD1H8UtVrIuAHpXSNJFIBiAnMJTwxuAUIjZiPB8masXkoF0vib6NINu3ABvqV4VQADVX_PZsDR_cxlma74ovmMgxnwE-QPNzG1zf8zR7kgCmJ4FjB4JyoqO9_XwFDNN23jiKC3CnAnqmnIS_nQB9F52OGyy_6PqmFNMZYIFjI9FxtwrWoa7N_AQuZtub2Bbfh85545Jdd0TX_VeAmqCN1cu5QZF8PwHYacbrdGVSR3XkywIX8KiXRPi2736YnmozGKsHfpqTLGGz-ZFpAjyV5VCjsWDM1YH9TWXUy0cUCTwqonHf3hptfWwJect2S5cn_2nC32LflJUDxWpnU-7BAzIf_qWjC6nqDg9zvmrdRmd1OxfxgGHre1Fc461eIipqemDq7el6YnDTfskuOA6n6KJAMZqwkYEHAK-tb00uEpPASQyjYY5NBIhAAH8YHloDuwednjn3yGnBqr3Gg6RijxZxJL5cF08jqQ_Ihe2ythPfslaXC6_qo16RAL93B6ydHBPGK0PzpEVRk6IKmY_H_yex7GnPYhJbYnxMQcwHkABE-uEe7WGXklOQEkALUgtNrCkllD3Li3Y_Rl6St4SWGIShfkA8PhbGrgVZ7UId-Qy5egsMVtJMVfZi9ltmR38obxg16IQcye3_KOfqi_zDQY7T6j_H2U3C_VYB1KwWLaTyATg5DDd57CmzRvMT_CL_xwjXbP-E26I_xVYl5hMrvw6SR6uVTSAiWlWEOOIJ6W3UDWDdR-IU4vnEbqjA7IkJdVMrXw0C10j-he367DoWdswHzecbuTsp_ncGvtVmpNwdbxzEO8F82TR7DSh4LqXWlbpo36rNKdWOVCDiMpB2b2A9jy8ZzXNZ-kIcvXTAnrAWYNZpuVY311PMVyDRv2Y6w8",
  "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=
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 manage a merchant’s base data, 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 has expired, 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"
}

Base data

The merchant’s base data can be administered via these endpoints.

Create a merchant

POST /api/psp/merchant/v1/merchants

A new merchant can be created through this endpoint.

Request

Field Type Characteristics Description

name

String

Mandatory. Maximum 100 characters.

Name of the merchant.

formOfOrganisation

String

Mandatory.

Legal form, e.g., GmbH, AG, …​

commercialRegisterType

String

Optional.

Type of the commercial register entry (HRA/HRB).

commercialRegisterNumber

String

Optional.

Commercial register number.

parentCorporationId

String

Optional. Maximum 100 characters.

ID of the parent corporation.

valueAddedTaxNumber

String

Optional. Maximum 100 characters.

Value added tax identification number.

merchantType

String

Mandatory. Use GIROPAY_MERCHANT as type identifier for giropay merchants.

Merchant type. Here always GIROPAY_MERCHANT.

marketingEnabled

Boolean

Optional.

Indicates whether the acquirer has granted paydirekt GmbH the right for merchant marketing (default: true).

creditorId

String

Mandatory if the merchant has at least one shop with collectingEnabled set to false.
Must be a valid creditorId (see Creditor Identifier).

Creditor identification number.

Response

In the response, the created merchant base data is returned. The structure is identical to the endpoint for GET calls, in particular the response contains the ID of the created merchant as well as the initial merchant status NOT_ACTIVE and all links relevant for the resource.

Links

Relation Description

self

Link to this resource.

shops

Link to the shops, see also Shops.

agreementSets

Link to the agreement set reference, see also Agreement set references.

contacts

Link to the contacts, see also Contacts.

postalAddress

Link to the postal address, see also Postal address.

downstreamPsps

Link to list all downstream PSPs, useful for finding PSPs which can be authorized, see also Read all available downstream PSPs.

authorizedPsps

Link to list all currently authorized PSPs, see also Read all authorized PSPs.

Return codes

Status code Message code Description

201 (Created)

The merchant was created.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

Example

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

{
  "name" : "someName",
  "formOfOrganisation" : "someForm",
  "commercialRegisterType" : "someCommType",
  "commercialRegisterNumber" : "someCommNumber",
  "parentCorporationId" : "someParentCorp",
  "valueAddedTaxNumber" : "someTaxNumber",
  "merchantType" : "GIROPAY_MERCHANT",
  "creditorId" : "DE98ZZZ09999999999"
}
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=utf-8

{
  "merchantId" : "36785ad5-1ac6-4f45-a7d4-cf73acba07c4",
  "name" : "someName",
  "merchantType" : "GIROPAY_MERCHANT",
  "formOfOrganisation" : "someForm",
  "commercialRegisterType" : "someCommType",
  "commercialRegisterNumber" : "someCommNumber",
  "parentCorporationId" : "someParentCorp",
  "valueAddedTaxNumber" : "someTaxNumber",
  "marketingEnabled" : true,
  "creditorId" : "DE98ZZZ09999999999",
  "checkoutCreationLocked" : false,
  "merchantStatus" : "NOT_ACTIVE",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36785ad5-1ac6-4f45-a7d4-cf73acba07c4"
    },
    "shops" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36785ad5-1ac6-4f45-a7d4-cf73acba07c4/shops"
    },
    "postalAddress" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36785ad5-1ac6-4f45-a7d4-cf73acba07c4/address"
    },
    "agreementSets" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36785ad5-1ac6-4f45-a7d4-cf73acba07c4/agreementsets"
    },
    "contacts" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36785ad5-1ac6-4f45-a7d4-cf73acba07c4/contacts"
    },
    "downstreamPsps" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36785ad5-1ac6-4f45-a7d4-cf73acba07c4/downstreampsps"
    },
    "authorizedPsps" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36785ad5-1ac6-4f45-a7d4-cf73acba07c4/authorizedpsps"
    }
  }
}

Read a merchant

GET /api/psp/merchant/v1/merchants/{merchantId}

The base data of a previously created merchant can be retrieved by using the GET method and providing the merchant ID. The returned resource contains the merchant’s base data as well as links to additional resources, e.g., shops, contacts, etc.

Response

Field Type Characteristics Description

merchantId

String

Always present.

ID of the merchant.

name

String

Always present.

Name of the merchant.

merchantType

String

Always present.

Merchant type. Here always GIROPAY_MERCHANT.

merchantStatus

String

Always present.

Status of the merchant.

formOfOrganisation

String

Always present.

Legal form, e.g., GmbH, AG, …​

commercialRegisterType

String

Optional.

Type of the commercial register entry (HRA/HRB).

commercialRegisterNumber

String

Optional.

Commercial register number.

parentCorporationId

String

Optional.

ID of the parent corporation.

valueAddedTaxNumber

String

Optional.

Value added tax identification number.

marketingEnabled

Boolean

Always present.

Indicates whether the acquirer has granted paydirekt GmbH the right for merchant marketing (default: true).

creditorId

String

Optional.

Creditor identification number.

checkoutCreationLocked

Boolean

Always present.

Indicates whether the creation of checkouts is locked for the shop.

_links

Object

Links to the resources and available actions of the merchant.
Relation Description

self

Link to this resource.

shops

Link to the shops, see also Shops.

agreementSets

Link to the agreement set reference, see also Agreement set references.

contacts

Link to the contacts, see also Contacts.

postalAddress

Link to the postal address, see also Postal address.

downstreamPsps

Link to list all downstream PSPs, useful for finding PSPs which can be authorized, see also Read all available downstream PSPs.

authorizedPsps

Link to list all currently authorized PSPs, see also Read all authorized PSPs.

Return codes

Status code Message code Description

200 (Ok)

The response provides a list of all existing merchant data.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

NOT_FOUND

The requested merchant does not exist.

Example

GET /api/psp/merchant/v1/merchants/79d4355c-efd1-455d-bf08-445ce680b7b7 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

{
  "merchantId" : "79d4355c-efd1-455d-bf08-445ce680b7b7",
  "name" : "ACME Spielwaren-Versand",
  "merchantType" : "GIROPAY_MERCHANT",
  "formOfOrganisation" : "AG",
  "commercialRegisterType" : "HRA",
  "commercialRegisterNumber" : "1234567890",
  "parentCorporationId" : "parentCorporationId",
  "valueAddedTaxNumber" : "SomeValueAddedTaxNumber",
  "marketingEnabled" : true,
  "creditorId" : "DE98ZZZ09999999999",
  "checkoutCreationLocked" : false,
  "merchantStatus" : "NOT_ACTIVE",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/79d4355c-efd1-455d-bf08-445ce680b7b7"
    },
    "shops" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/79d4355c-efd1-455d-bf08-445ce680b7b7/shops"
    },
    "postalAddress" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/79d4355c-efd1-455d-bf08-445ce680b7b7/address"
    },
    "agreementSets" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/79d4355c-efd1-455d-bf08-445ce680b7b7/agreementsets"
    },
    "contacts" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/79d4355c-efd1-455d-bf08-445ce680b7b7/contacts"
    },
    "downstreamPsps" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/79d4355c-efd1-455d-bf08-445ce680b7b7/downstreampsps"
    },
    "authorizedPsps" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/79d4355c-efd1-455d-bf08-445ce680b7b7/authorizedpsps"
    }
  }
}

Read all merchants

GET /api/psp/merchant/v1/merchants

This endpoint provides a list of all merchant data stored in the system for this giropay PSP.
If the request is made by the owning giropay PSP (meaning the PSP that created the merchant via API), all owning merchants are returned. If the request is made by the giropay psp owning the agreement set which is currently assigned to a merchant (acquirer, see agreement set administration), all merchants are returned, which have an agreement set reference to the acquirer’s agreement set.

Each merchant record listed in the response also contains further administration links for this merchant resource.

This endpoint is thus an excellent entry point for the administration of merchant data, since its URL is static, and it only needs to be called with valid authentication. Most endpoints of the API can be reached via the links in this response.

Response

Field Type Characteristics Description

_embedded.merchants

Array

List of merchants managed by the PSP, including links to manage each merchant object separately.
Relation Description

self

Link to this resource.

Return codes

Status code Message code Description

200 (Ok)

The response provides a list of all existing merchant data.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

Example

GET /api/psp/merchant/v1/merchants 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

{
  "_embedded" : {
    "merchants" : [ {
      "merchantId" : "36fbc7c4-db75-43e9-b043-562f41b8d2e3",
      "name" : "ACME Spielwaren-Versand",
      "merchantType" : "GIROPAY_MERCHANT",
      "formOfOrganisation" : "AG",
      "commercialRegisterType" : "HRA",
      "commercialRegisterNumber" : "1234567890",
      "parentCorporationId" : "parentCorporationId",
      "valueAddedTaxNumber" : "SomeValueAddedTaxNumber",
      "marketingEnabled" : true,
      "checkoutCreationLocked" : false,
      "merchantStatus" : "NOT_ACTIVE",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36fbc7c4-db75-43e9-b043-562f41b8d2e3"
        },
        "shops" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36fbc7c4-db75-43e9-b043-562f41b8d2e3/shops"
        },
        "postalAddress" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36fbc7c4-db75-43e9-b043-562f41b8d2e3/address"
        },
        "agreementSets" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36fbc7c4-db75-43e9-b043-562f41b8d2e3/agreementsets"
        },
        "contacts" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36fbc7c4-db75-43e9-b043-562f41b8d2e3/contacts"
        },
        "downstreamPsps" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36fbc7c4-db75-43e9-b043-562f41b8d2e3/downstreampsps"
        },
        "authorizedPsps" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/36fbc7c4-db75-43e9-b043-562f41b8d2e3/authorizedpsps"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants"
    }
  }
}

Update a merchant

PATCH /api/psp/merchant/v1/merchants/{merchantId}

giropay merchants can be edited through this endpoint. This includes status updates, namely activation or deboarding of the merchant by setting the value of the status field accordingly. Please note that for activating a merchant certain conditions have to be fulfilled:

Request

Field Type Characteristics Description

merchantStatus

String

Optional. Either ACTIVE or DEBOARDED.

New status to which the merchant should be transitioned.
Caution: Once a merchant has been deboarded, it can not be activated again.

name

String

Optional. Maximum 100 characters.

Name of the merchant.

formOfOrganisation

String

Optional.

Legal form, e.g., GmbH, AG, …​

commercialRegisterType

String

Optional.

Type of the commercial register entry (HRA/HRB).

commercialRegisterNumber

String

Optional.

Commercial register number.

parentCorporationId

String

Optional. Maximum 100 characters.

ID of the parent corporation.

valueAddedTaxNumber

String

Optional. Maximum 100 characters.

Value added tax identification number.

marketingEnabled

Boolean

Optional.

Indicates whether the acquirer has granted paydirekt GmbH the right for merchant marketing (default: true).

creditorId

String

Mandatory if the merchant has at least one shop with collectingEnabled set to false.
Must be a valid creditorId (see Creditor Identifier).

Creditor identification number.

Response

In the response, the updated merchant base data is returned. The structure is nearly identical to the endpoint for GET calls, in particular the response contains the ID of the created merchant and all links relevant for the resource.

Field Type Characteristics Description

merchantId

String

Always present.

ID of the merchant.

name

String

Always present.

Name of the merchant.

formOfOrganisation

String

Always present.

Legal form, e.g., GmbH, AG, …​

commercialRegisterType

String

Optional.

Type of the commercial register entry (HRA/HRB).

commercialRegisterNumber

String

Optional.

Commercial register number.

parentCorporationId

String

Optional.

ID of the parent corporation.

valueAddedTaxNumber

String

Optional.

Value added tax identification number.

merchantType

String

Always present.

Merchant type. Here always GIROPAY_MERCHANT.

merchantStatus

String

Always present.

Status of the merchant.

checkoutCreationLocked

Boolean

Always present.

Indicates whether the creation of checkouts is locked for the shop.

marketingEnabled

Boolean

Always present.

Indicates whether the acquirer has granted paydirekt GmbH the right for merchant marketing (default: true).

creditorId

String

Optional.

Creditor identification number.
Relation Description

self

Link to this resource.

shops

Link to the shops, see also Shops.

agreementSets

Link to the agreement set reference, see also Agreement set references.

contacts

Link to the contacts, see also Contacts.

postalAddress

Link to the postal address, see also Postal address.

downstreamPsps

Link to list all downstream PSPs, useful for finding PSPs which can be authorized, see also Read all available downstream PSPs.

authorizedPsps

Link to list all currently authorized PSPs, see also Read all authorized PSPs.

Return codes

Status code Message code Description

200 (Ok)

The requested change of status of the merchant was successful.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

422 (Unprocessable Entity)

INVALID_STATE_TRANSITION

The requested state transition is not possible for the merchant’s current status.

422 (Unprocessable Entity)

NO_SHOP

Only when activating: The merchant does not have a shop.

422 (Unprocessable Entity)

EFFECTIVE_AGREEMENT_SET_REFERENCE_REQUIRED

Only when activating: The merchant does not have an effective agreement set reference (see agreement set references.

Example

PATCH /api/psp/merchant/v1/merchants/7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "merchantStatus" : "ACTIVE",
  "name" : "newName",
  "formOfOrganisation" : "newFormOfOrganisation",
  "commercialRegisterType" : "newCommercialRegisterType",
  "commercialRegisterNumber" : "newCommercialRegisterNumber",
  "parentCorporationId" : "newParentCorporationId",
  "valueAddedTaxNumber" : "newValueAddedTaxNumber",
  "marketingEnabled" : true,
  "creditorId" : "DE98ZZZ09999999999"
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "merchantId" : "7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00",
  "name" : "newName",
  "merchantType" : "GIROPAY_MERCHANT",
  "formOfOrganisation" : "newFormOfOrganisation",
  "commercialRegisterType" : "newCommercialRegisterType",
  "commercialRegisterNumber" : "newCommercialRegisterNumber",
  "parentCorporationId" : "newParentCorporationId",
  "valueAddedTaxNumber" : "newValueAddedTaxNumber",
  "marketingEnabled" : true,
  "creditorId" : "DE98ZZZ09999999999",
  "checkoutCreationLocked" : false,
  "merchantStatus" : "ACTIVE",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00"
    },
    "shops" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00/shops"
    },
    "postalAddress" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00/address"
    },
    "agreementSets" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00/agreementsets"
    },
    "contacts" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00/contacts"
    },
    "downstreamPsps" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00/downstreampsps"
    },
    "authorizedPsps" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/7b95c7f6-bb4a-4ed9-b4ee-68f7fb379e00/authorizedpsps"
    }
  }
}

Postal address

Endpoint for merchant address administration.

Create/Update a merchant’s address

This endpoint can be used to both create and update a merchant’s address.

PUT /api/psp/merchant/v1/merchants/{merchantId}/address

Request

Field Type Characteristics Description

company

String

Mandatory. Maximum 100 characters.

Company name.

street

String

Mandatory. Maximum 100 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&+'.

Street.

streetNr

String

Mandatory. Maximum 10 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&+.

Street number.

additionalAddressInformation

String

Optional. Maximum 100 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&!"?+'_:´`.

Additional address information.

zip

String

Optional. Maximum 10 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&.

Postal code.

city

String

Mandatory. Maximum 100 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&+'.

Town or city.

country

String

Optional.

Country code following the ISO 3166-1 alpha-2 format.

Response

The response contains the created or updated address. The structure is identical to the data returned in the GET call.

Return codes

Status code Message code Description

200 (OK)

The merchant address data has been updated.

201 (Created)

The merchant address data has been created.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

NOT_FOUND

The specified merchant does not exist.

Example

PUT /api/psp/merchant/v1/merchants/cb816ef7-52c9-47d2-9124-3ddabc9839b5/address HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "company" : "AnyCompany",
  "street" : "Beethovenstr.",
  "streetNr" : "1",
  "additionalAddressInformation" : "Some additional information",
  "zip" : "12345",
  "city" : "Berlin",
  "country" : "DE"
}
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=utf-8

{
  "company" : "AnyCompany",
  "street" : "Beethovenstr.",
  "streetNr" : "1",
  "additionalAddressInformation" : "Some additional information",
  "zip" : "12345",
  "city" : "Berlin",
  "country" : "DE",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/cb816ef7-52c9-47d2-9124-3ddabc9839b5/address"
    }
  }
}

Read a merchant’s postal address

GET /api/psp/merchant/v1/merchants/{merchantId}/address

Response

Field Type Characteristics Description

company

String

Always present.

Company name.

street

String

Always present.

Street.

streetNr

String

Always present.

Street number.

additionalAddressInformation

String

Optional.

Additional address information.

zip

String

Optional.

Postal code.

city

String

Always present.

Town or city.

country

String

Optional.

Country code following the ISO 3166-1 alpha-2 format.

Links

Relation Description

self

Link to this resource.

Return codes

Status code Message code Description

200 (Ok)

Address data found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

NOT_FOUND

The requested merchant does not exist.

Example

GET /api/psp/merchant/v1/merchants/4e87fb4b-8746-429c-9ee7-8477f92d1224/address 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

{
  "company" : "AnyCompany",
  "street" : "Beethovenstr.",
  "streetNr" : "1",
  "additionalAddressInformation" : "Some additional information",
  "zip" : "12345",
  "city" : "Berlin",
  "country" : "DE",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/4e87fb4b-8746-429c-9ee7-8477f92d1224/address"
    }
  }
}

Agreement set references

Each merchant can have multiple acquirer agreement set references, each provided with a different starting date. The effective agreement set reference is resolved according to this starting date. A merchant has to provide one effective acquirer agreement set reference to get activated (see Update Merchant). Please note, that once there is no effective agreement set reference provided, no checkouts can be performed for that merchant.

Read all available agreement sets

This endpoint can be used to query all agreement sets that are available to create an agreement set reference.

GET /api/psp/merchant/v1/psp/agreementsets

Response

Field Type Characteristics Description

_embedded.agreementSets

Array

Present if own or assigned agreement sets were found.

The agreement sets available for the giropay psp calling the endpoint.

Links

Relation Description

self

Link to this resource.

Return codes

Status code Message code Description

200 (Ok)

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

Example

GET /api/psp/merchant/v1/psp/agreementsets 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

{
  "_embedded" : {
    "agreementSets" : [ {
      "agreementSetId" : "79c2d527-0db4-499c-9e34-e3d3f5e65292",
      "agreementSetName" : "Name of the acquirer agreement set"
    }, {
      "agreementSetId" : "1942336f-f948-400e-a8ef-a1c500c3332a",
      "agreementSetName" : "Name of another acquirer agreement set"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/psp/agreementsets"
    }
  }
}

Create an agreement set reference

This endpoint can be used to assign an agreement set reference to the administrated merchant. All agreement sets available for this can be read via the get all available agreement sets endpoint as described in the section above.

At this point there are additional validations. The reason is to ensure that the payment will be processed accordingly to the planned setup, e.g. the collecting status. An explicit requirement is an already existing postal address.

POST /api/psp/merchant/v1/merchants/{merchantId}/agreementsets

Request

Field Type Characteristics Description

agreementSetId

String

Mandatory. Must be an agreement set id of merchant’s owning PSP.

ID of the agreement set.

startDate

String

Mandatory. Must be unique within all agreement set references of the merchant.

Start date of the agreement set reference.

Response

The response contains the created agreement set reference. The structure is identical to the data returned in the GET call.

Return codes

Status code Message code Description

200 (Ok)

The agreement set reference has been updated.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The specified merchant does not exist.

422 (Unprocessable Entity)

NOT_AUTHORIZED_FOR_AGREEMENT_SET

The agreement is not accessible for the current authorization.

422 (Unprocessable Entity)

ACQUIRER_AGREEMENT_SET_REFERENCE_WITH_SAME_START_DATE_ALREADY_EXISTS

There is already an agreement set reference with the same start date assigned to the merchant.

422 (Unprocessable Entity)

INVALID_COLLECTING_STATUS_SHOP

For a giropay admission agreement the requested collectingEnabled attribute of the shop does not match the collecting status of the psp master data in the giropay system, see Create a shop request. If the requested value is correct, please contact your giropay administrator.

422 (Unprocessable Entity)

BANK_NOT_FOUND

The BIC of one shop does not exist on an active bank in the giropay system. If the requested value is correct, please contact your giropay administrator.

422 (Unprocessable Entity)

MISSING_CREDITOR_ID

The required creditorId in the merchant base data is missing.

422 (Unprocessable Entity)

POSTAL_ADDRESS_NOT_EXISTING

The required postalAddress is missing.

Example

POST /api/psp/merchant/v1/merchants/db91da4b-4745-4c5e-a4bb-37b4e398b1f3/agreementsets HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "agreementSetId" : "cd7827c5-7d1f-45cc-89f8-cbab6c5d6677",
  "startDate" : "2021-01-01"
}
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=utf-8

{
  "referenceId" : "8ce4670c-ccc5-4c4c-b30d-63cc0b4c24ac",
  "agreementSetId" : "cd7827c5-7d1f-45cc-89f8-cbab6c5d6677",
  "startDate" : "2021-01-01",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/db91da4b-4745-4c5e-a4bb-37b4e398b1f3/agreementsets/8ce4670c-ccc5-4c4c-b30d-63cc0b4c24ac"
    }
  }
}

Read a merchant agreement set reference

In order to query a single agreement set reference, the IDs of the merchant and the agreement set reference are required.

GET /api/psp/merchant/v1/merchants/{merchantId}/agreementsets/{referenceId}

Response

Field Type Characteristics Description

referenceId

String

Always present.

ID of the agreement set reference.

agreementSetId

String

Always present.

ID of the agreement set.

startDate

String

Always present.

Start date of the agreement set reference.

Links

Relation Description

self

Link to this resource.

Return codes

Status code Message code Description

200 (Ok)

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

422 (Unprocessable Entity)

NOT_AUTHORIZED_FOR_AGREEMENT_SET

The agreement set reference is not accessible for the current authorization

404 (Not Found)

ACQUIRER_AGREEMENT_SET_REFERENCE_NOT_FOUND

The specified agreement set reference does not exist for this merchant.

Example

GET /api/psp/merchant/v1/merchants/046c5ec1-4eff-4d5b-94f3-23c721445b81/agreementsets/2aa1a8dd-bfbb-4c6d-9912-e315aa120f7f 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

{
  "referenceId" : "2aa1a8dd-bfbb-4c6d-9912-e315aa120f7f",
  "agreementSetId" : "82dbdad9-5d30-4121-bdd0-027d65e6c0d9",
  "startDate" : "2021-01-01",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/046c5ec1-4eff-4d5b-94f3-23c721445b81/agreementsets/2aa1a8dd-bfbb-4c6d-9912-e315aa120f7f"
    }
  }
}

Read all merchant agreement set references

Query all agreement set references belonging to a merchant.

GET /api/psp/merchant/v1/merchants/{merchantId}/agreementsets

Response

Field Type Characteristics Description

_embedded.agreementSets

Array

The list of agreement set references assigned to this merchant.

Links

Relation Description

self

Link to the agreement set references of the merchant, see also Agreement set references.

Return codes

Status code Message code Description

200 (Ok)

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

422 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

Example

GET /api/psp/merchant/v1/merchants/b8530122-0683-4c48-aaa5-c425530d23c2/agreementsets 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

{
  "_embedded" : {
    "agreementSets" : [ {
      "referenceId" : "6ab3c1b4-a4b4-4564-b41e-ee5b3e8c389a",
      "agreementSetId" : "7cc30a77-818e-47d1-8ae5-61b93a9aad9b",
      "startDate" : "2021-01-01",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/b8530122-0683-4c48-aaa5-c425530d23c2/agreementsets/6ab3c1b4-a4b4-4564-b41e-ee5b3e8c389a"
        }
      }
    }, {
      "referenceId" : "717e5460-5c3d-4023-b6b1-3c947efaa942",
      "agreementSetId" : "7cc30a77-818e-47d1-8ae5-61b93a9aad9b",
      "startDate" : "2024-07-25",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/b8530122-0683-4c48-aaa5-c425530d23c2/agreementsets/717e5460-5c3d-4023-b6b1-3c947efaa942"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/b8530122-0683-4c48-aaa5-c425530d23c2/agreementsets"
    }
  }
}

Update an agreement set reference

This endpoint can be used to update an agreement set reference. An agreement set reference can be patched only if its start date is in the future.

PATCH /api/psp/merchant/v1/merchants/{merchantId}/agreementsets/{referenceId}

Request

Field Type Characteristics Description

agreementSetId

String

Optional. Must be an agreement set id of merchant’s owning PSP.

ID of the agreement set.

startDate

String

Optional. Must be unique within all agreement set references of the merchant.

Start date of the agreement set reference.

Response

The response contains the modified agreement set reference. The structure is identical to the data returned in the GET call.

Return codes

Status code Message code Description

200 (Ok)

The agreement set reference has been updated.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The specified merchant does not exist.

404 (Not Found)

ACQUIRER_AGREEMENT_SET_REFERENCE_NOT_FOUND

The specified agreement set reference does not exist for this merchant.

422 (Unprocessable Entity)

ACQUIRER_AGREEMENT_SET_REFERENCE_WITH_SAME_START_DATE_ALREADY_EXISTS

There is already an agreement set reference with the same start date assigned to the merchant

422 (Unprocessable Entity)

INVALID_COLLECTING_STATUS_SHOP

The requested collectingEnabled attribute of the shop does not match the collecting status of the psp master data in the giropay system, see Create a shop request. If the requested value is correct, please contact your giropay administrator.

422 (Unprocessable Entity)

BANK_NOT_FOUND

The BIC of one shop does not exist on an active bank in the giropay system. If the requested value is correct, please contact your giropay administrator.

422 (Unprocessable Entity)

MISSING_CREDITOR_ID

The required creditorId in the merchant base data is missing.

422 (Unprocessable Entity)

POSTAL_ADDRESS_NOT_EXISTING

The required postalAddress is missing.

422 (Unprocessable Entity)

ONLY_FUTURE_ACQUIRER_AGREEMENT_SET_REFERENCE_CAN_BE_EDITED

The specified agreement set reference cannot be deleted since its start date is not in the future.

Example

PATCH /api/psp/merchant/v1/merchants/eb112a65-6b20-4d38-9662-2d0b41776eda/agreementsets/865f49fb-2142-4272-a46d-1825811118d8 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "agreementSetId" : "e6becf2a-0d62-4512-914d-e05c8ad698cf",
  "startDate" : "2023-07-26"
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "referenceId" : "865f49fb-2142-4272-a46d-1825811118d8",
  "agreementSetId" : "e6becf2a-0d62-4512-914d-e05c8ad698cf",
  "startDate" : "2023-07-26",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/eb112a65-6b20-4d38-9662-2d0b41776eda/agreementsets/865f49fb-2142-4272-a46d-1825811118d8"
    }
  }
}

Delete an agreement set reference

This endpoint can be used to delete an agreement set reference. An agreement set reference can be deleted only if its start date is in the future.

Request

DELETE /api/psp/merchant/v1/merchants/{merchantId}/agreementsets/{referenceId}

Response

The response does not contain a body.

Return codes

Status code Message code Description

204 (Ok)

The agreement set reference has been deleted.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The specified merchant does not exist.

404 (Not Found)

ACQUIRER_AGREEMENT_SET_REFERENCE_NOT_FOUND

The specified agreement set reference does not exist for this merchant.

422 (Unprocessable Entity)

ONLY_FUTURE_ACQUIRER_AGREEMENT_SET_REFERENCE_CAN_BE_EDITED

The specified agreement set reference cannot be deleted since its start date is not in the future.

Example

DELETE /api/psp/merchant/v1/merchants/d863656a-6a83-4025-ab01-6e61fc1cef92/agreementsets/11f46d78-817d-4be7-837d-894706d94b3f HTTP/1.1
Content-Type: text/plain;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 204 No Content

Authorized PSP

An owning giropay PSP (meaning the PSP that created the merchant) and the assigned acquirer can authorize one or multiple downstream PSPs to create checkouts in the name of a merchant. An authorized PSP then can also read merchant base data - however, he cannot edit it.

Downstream PSP refers to a service provider connected via already existing contractual relationship with an owning PSP.

Read all available downstream PSPs

This endpoint can be used to read all available downstream PSPs, which can be authorized to create checkouts for the merchant’s shops. There is no request body, the required information is part of the url and the bearer token.

GET /api/psp/merchant/v1/merchants/{merchantId}/downstreampsps

Response

Field Type Characteristics Description

_embedded.downstreamPsps

Array

Always present.

List of downstream PSPs, including links to manage the authorization of each downstream PSP separately.

_embedded.downstreamPsps[].pspId

String

Always present.

ID of the downstream PSP.

_embedded.downstreamPsps[].name

String

Always present.

Name of the downstream PSP.

_embedded.downstreamPsps[]._links.authorization

Object

Always present.

Link to manage the authorization of the downstream PSP, see also Authorize a PSP and Delete authorization of a PSP.

Links

Relation Description

self

Link to this resource.

Return codes

Status code Message code Description

200 (Ok)

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The specified merchant does not exist.

Example

GET /api/psp/merchant/v1/merchants/c52339ad-3c33-4fb7-80ba-eb79fff65ca1/downstreampsps 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

{
  "_embedded" : {
    "downstreamPsps" : [ {
      "pspId" : "d5612286-6edc-4b9c-912e-eb74c34bdb9b",
      "name" : "Downstream PSP 1",
      "_links" : {
        "authorization" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/c52339ad-3c33-4fb7-80ba-eb79fff65ca1/authorizedpsps/d5612286-6edc-4b9c-912e-eb74c34bdb9b"
        }
      }
    }, {
      "pspId" : "47f87e6d-c064-44a5-b136-62a2a5c445ee",
      "name" : "Downstream PSP 2",
      "_links" : {
        "authorization" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/c52339ad-3c33-4fb7-80ba-eb79fff65ca1/authorizedpsps/47f87e6d-c064-44a5-b136-62a2a5c445ee"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/c52339ad-3c33-4fb7-80ba-eb79fff65ca1/downstreampsps"
    }
  }
}

Authorize a PSP

This endpoint can be used to authorize a downstream PSP to create checkouts for the merchant’s shops. There is no request body, the required information is part of the url and the bearer token.

PUT /api/psp/merchant/v1/merchants/{merchantId}/authorizedpsps/{authorizedPspId}

Response

Field Type Characteristics Description

merchantId

String

Always present.

The ID of the merchant for which the PSP is authorized.

authorizedPspId

String

Always present.

The ID of the PSP, which is authorized.

name

String

Always present.

The name of the PSP, which is authorized.

Links

Relation Description

self

Link to this resource.

Return codes

Status code Message code Description

200 (Ok)

The PSP has been authorized for the merchant.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The specified merchant does not exist.

400 (Bad Request)

PSP_NOT_A_DOWNSTREAM_PSP

The PSP to be authorized is not a downstream PSP of the owning PSP.

Example

PUT /api/psp/merchant/v1/merchants/a23f73af-3860-4db4-b699-66e50d42ef26/authorizedpsps/bc1df3f1-689d-4cac-8f74-289dcdd4242f 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

{
  "merchantId" : "a23f73af-3860-4db4-b699-66e50d42ef26",
  "authorizedPspId" : "bc1df3f1-689d-4cac-8f74-289dcdd4242f",
  "name" : "Authorized PSP",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/a23f73af-3860-4db4-b699-66e50d42ef26/authorizedpsps/bc1df3f1-689d-4cac-8f74-289dcdd4242f"
    }
  }
}

Read all authorized PSPs

This endpoint can be used to query all PSPs that are given authorization to create checkouts for the merchant’s shops. There is no request body, the required information is part of the url and the bearer token.

GET /api/psp/merchant/v1/merchants/{merchantId}/authorizedpsps

Response

Field Type Characteristics Description

_embedded.authorizedPsps

Array

Always present.

List of authorized PSPs, including links to manage the authorization of each authorized PSP separately.

_embedded.authorizedPsps[].merchantId

String

Always present.

ID of the merchant of the authorized PSP.

_embedded.authorizedPsps[].authorizedPspId

String

Always present.

ID of the authorized PSP.

_embedded.authorizedPsps[].name

String

Always present.

Name of the authorized PSP.

_embedded.authorizedPsps[]._links.self

Object

Always present.

Link to manage the authorization of the authorized PSP, see also Authorize a PSP and Delete authorization of a PSP.

Links

Relation Description

self

Link to this resource.

Return codes

Status code Message code Description

200 (Ok)

The PSP has been authorized for the merchant.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The specified merchant does not exist.

Example

GET /api/psp/merchant/v1/merchants/a23f73af-3860-4db4-b699-66e50d42ef26/authorizedpsps 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

{
  "_embedded" : {
    "authorizedPsps" : [ {
      "merchantId" : "a23f73af-3860-4db4-b699-66e50d42ef26",
      "authorizedPspId" : "bc1df3f1-689d-4cac-8f74-289dcdd4242f",
      "name" : "Authorized PSP",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/a23f73af-3860-4db4-b699-66e50d42ef26/authorizedpsps/bc1df3f1-689d-4cac-8f74-289dcdd4242f"
        }
      }
    }, {
      "merchantId" : "a23f73af-3860-4db4-b699-66e50d42ef26",
      "authorizedPspId" : "12b4c130-811a-491d-865b-73b804c8ed07",
      "name" : "Authorized Payment Service Provider",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/a23f73af-3860-4db4-b699-66e50d42ef26/authorizedpsps/12b4c130-811a-491d-865b-73b804c8ed07"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/a23f73af-3860-4db4-b699-66e50d42ef26/authorizedpsps"
    }
  }
}

Delete authorization of a PSP

This endpoint can be used to unauthorize a downstream PSP to act in the name of the merchant.

Request

DELETE /api/psp/merchant/v1/merchants/{merchantId}/authorizedpsps/{authorizedPspId}

Response

The response does not contain a body.

Return codes

Status code Message code Description

204 (Ok)

The authorization has been deleted.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The specified merchant does not exist.

Example

DELETE /api/psp/merchant/v1/merchants/a23f73af-3860-4db4-b699-66e50d42ef26/authorizedpsps/bc1df3f1-689d-4cac-8f74-289dcdd4242f HTTP/1.1
Content-Type: text/plain;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 204 No Content

Shops

Each merchant can have multiple shops. A merchant must have at least one shop before it can be activated.

Create a shop

POST /api/psp/merchant/v1/merchants/{merchantId}/shops

Request

Field Type Characteristics Description

name

String

Mandatory. Maximum 100 characters.

Name of the shop.

type

String

Mandatory. One of WEB_SHOP, APP_SHOP, or POS_SHOP.

Shop type, either a web shop, app shop, or point of sale shop.

url

String

Mandatory if the shop is a web shop, otherwise the field must be empty. If present, must follow the https protocol. Letters in host name and domain name must be lowercase.

URL of the shop’s website.

merchantCategory

String

Mandatory.

Merchant category code (MCC) following the ISO 18245 format.

fraudEmail

String

Optional.

Email address of the fraud contact.
If not specified, the field will be set to the same value as disputeEmail.

disputeEmail

String

Optional.

An email address used for any kind of disputes (exception: fraud). If not specified, the associated acquirer’s dispute email address is contacted in case of issues.

bankAccountIban

String

Mandatory. Must follow the ISO 7064 format.

The IBAN of the shop’s bank account.

bankAccountBic

String

Mandatory.
Must be a valid BIC for an existing bank in the giropay system. Capital letters only.

The BIC of the shop’s account.

bankAccountOwnerName

String

Mandatory. Maximum 27 characters from the SEPA character set.

The name of the owner of the shop’s bank account.

refundBankAccountIban

String

Optional. Must follow the ISO 7064 format and must belong to the same bank as the shop’s bank account.

The IBAN of the shop’s refund bank account.

collectingEnabled

Boolean

Mandatory if the collecting status of the owning giropay PSP is set to MIXED.
Optional if the owning giropay PSP either never or exclusively collects for merchants. Then collectingEnabled has to match the collecting status of the PSP master data in the giropay system.

Indicates whether the created bank account IBAN of the shop is a bank account of the owning giropay PSP.

Response

In the response, the data of the created shop is returned. The structure is identical to the data returned from the GET call.

Field Type Characteristics Description

shopId

String

Always present.

ID of the shop.

name

String

Always present.

Name of the shop.

type

String

Always present.

Shop type, either a web shop, app shop, or point of sale shop.

url

String

Present if the shop is a web shop, otherwise empty.

URL of the shop’s website.

merchantCategory

String

Always present.

Merchant category code (MCC) following the ISO 18245 format.

fraudEmail

String

Optional.

Email address of the fraud contact.
If not specified, the field will be set to the same value as disputeEmail.

disputeEmail

String

Optional.

An email address used for any kind of disputes (exception: fraud). If not specified, the associated acquirer’s dispute email address is contacted in case of issues.

merchantAuthorizationReference

String

Always present.

Merchant authorization reference. The reference must be provided when creating a checkout for the merchant shop.

bankAccountIban

String

Always present.

The IBAN of the shop’s bank account.

bankAccountBic

String

Always present.

The BIC of the shop’s account.

bankAccountOwnerName

String

Always present.

The name of the owner of the shop’s bank account.

refundBankAccountIban

String

Present if the IBAN was set.

The IBAN of the shop’s refund bank account.

collectingEnabled

Boolean

Optional.

Indicates whether the created bank account IBAN of the shop is a bank account of the owning giropay PSP.

Return codes

Status code Message code Description

201 (Created)

The shop was created.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

422 (Unprocessable Entity)

INVALID_COLLECTING_STATUS_SHOP

The requested collectingEnabled attribute of the shop does not match the collecting status of the psp master data in the giropay system. If the requested value is correct, please contact your giropay administrator.

422 (Unprocessable Entity)

BANK_NOT_FOUND

1. The BIC of one shop does not exist on an active bank in the giropay system.

2. The requested refundBankAccountIban does not belong to any active bank in the giropay system.

If the requested values are correct, please contact your giropay administrator.

422 (Unprocessable Entity)

REFUND_IBAN_DOES_NOT_MATCH_TRANSFER_BANK

The requested refundBankAccountIban does not belong to the shop’s bank.

422 (Unprocessable Entity)

BANK_ACCOUNT_IBAN_AND_BIC_DO_NOT_MATCH

The IBAN and BIC do not belong to the same bank.

Example

POST /api/psp/merchant/v1/merchants/16af9088-a61d-4828-912e-744c02183ead/shops HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "name" : "Anyshop",
  "type" : "WEB_SHOP",
  "url" : "http://www.anyshop.example.com",
  "merchantCategory" : "1520",
  "bankAccountIban" : "DE37500105172313797565",
  "bankAccountBic" : "INGDDEFFXXX",
  "bankAccountOwnerName" : "Some BankAccountOwner",
  "fraudEmail" : "fraud@mail.de",
  "disputeEmail" : "dispute@paydirekt.de",
  "collectingEnabled" : true,
  "refundBankAccountIban" : "DE88500105176132978326"
}
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=utf-8

{
  "shopId" : "2877aace-fe26-4c5d-a978-d86235372043",
  "name" : "Anyshop",
  "type" : "WEB_SHOP",
  "url" : "http://www.anyshop.example.com",
  "merchantCategory" : "1520",
  "fraudEmail" : "fraud@mail.de",
  "disputeEmail" : "dispute@paydirekt.de",
  "merchantAuthorizationReference" : "rceEtiuwcSuqN1RUPv0-dtyTvni8kqOkYKLzo3jivMU=",
  "bankAccountIban" : "DE37500105172313797565",
  "bankAccountBic" : "INGDDEFFXXX",
  "bankAccountOwnerName" : "Some BankAccountOwner",
  "refundBankAccountIban" : "DE88500105176132978326",
  "collectingEnabled" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/16af9088-a61d-4828-912e-744c02183ead/shops/2877aace-fe26-4c5d-a978-d86235372043"
    },
    "logo" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/16af9088-a61d-4828-912e-744c02183ead/shops/2877aace-fe26-4c5d-a978-d86235372043/logo"
    }
  }
}

There is one endpoint for reading either all shops or a specific shop of a merchant.

Read a shop

The query of a specific shop is done by specifying the merchant ID as well as the ID of the shop.

Request

GET /api/psp/merchant/v1/merchants/{merchantId}/shops/{shopId}

Response

Field Type Characteristics Description

shopId

String

Always present.

ID of the shop.

name

String

Always present.

Name of the shop.

type

String

Always present.

Shop type, either a web shop, app shop, or point of sale shop.

url

String

Present if the shop is a web shop, otherwise empty.

URL of the shop’s website.

merchantCategory

String

Always present.

Merchant category code (MCC) following the ISO 18245 format.

fraudEmail

String

Optional.

Email address of the fraud contact.
If not specified, the field will be set to the same value as disputeEmail.

disputeEmail

String

Optional.

An email address used for any kind of disputes (exception: fraud). If not specified, the associated acquirer’s dispute email address is contacted in case of issues.

merchantAuthorizationReference

String

Always present.

Merchant authorization reference. The reference must be provided when creating a checkout for the merchant shop.

bankAccountIban

String

Always present.

The IBAN of the shop’s bank account.

bankAccountBic

String

Always present.

The BIC of the shop’s account.

bankAccountOwnerName

String

Always present.

The name of the owner of the shop’s bank account.

refundBankAccountIban

String

Present if the IBAN was set.

The IBAN of the shop’s refund bank account.

collectingEnabled

Boolean

Optional.

Indicates whether the created bank account IBAN of the shop is a bank account of the owning giropay PSP.

Links

Relation Description

self

Link to this resource.

logo

Link to logo resources of the shop.

Return codes

Status code Message code Description

200 (Ok)

Shop found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

404 (Not Found)

SHOP_NOT_FOUND

The requested shop does not exist.

Example

GET /api/psp/merchant/v1/merchants/d667a47f-be91-4331-aeb8-d04084ddf3f1/shops/c3147f9c-ca5c-47cf-9242-017fe2a5c4cb 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

{
  "shopId" : "c3147f9c-ca5c-47cf-9242-017fe2a5c4cb",
  "name" : "Anyshop",
  "type" : "WEB_SHOP",
  "url" : "http://www.anyshop.example.com",
  "merchantCategory" : "1520",
  "fraudEmail" : "fraud@mail.de",
  "disputeEmail" : "dispute@mail.de",
  "merchantAuthorizationReference" : "9KgNql8QAdji9PfTyPLZ9d49CAPM1TdQPMoKfgMu80Q=",
  "bankAccountIban" : "DE37500105172313797565",
  "bankAccountBic" : "INGDDEFFXXX",
  "bankAccountOwnerName" : "Some BankAccountOwner",
  "refundBankAccountIban" : "DE88500105176132978326",
  "collectingEnabled" : false,
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/d667a47f-be91-4331-aeb8-d04084ddf3f1/shops/c3147f9c-ca5c-47cf-9242-017fe2a5c4cb"
    },
    "logo" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/d667a47f-be91-4331-aeb8-d04084ddf3f1/shops/c3147f9c-ca5c-47cf-9242-017fe2a5c4cb/logo"
    }
  }
}

Read all shops

GET /api/psp/merchant/v1/merchants/{merchantId}/shops

Response

The response consists of a list of shops as listed in the response of a single call (including the respective links to the shop resource).

Return codes

Status code Message code Description

200 (Ok)

Shop found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

Example

GET /api/psp/merchant/v1/merchants/3b417ca9-93fb-4da4-a933-91e906c33737/shops 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

{
  "_embedded" : {
    "shops" : [ {
      "shopId" : "736b49b1-a169-404c-8792-92708bc0ea22",
      "name" : "Anyshop",
      "type" : "WEB_SHOP",
      "url" : "http://www.anyshop.example.com",
      "merchantCategory" : "1520",
      "fraudEmail" : "fraud@mail.de",
      "disputeEmail" : "dispute@mail.de",
      "merchantAuthorizationReference" : "tgm93V-1TgyzNdxjo-32Jq0oTKrzePi7nmLKKxDYeCI=",
      "bankAccountIban" : "DE37500105172313797565",
      "bankAccountBic" : "INGDDEFFXXX",
      "bankAccountOwnerName" : "Some BankAccountOwner",
      "refundBankAccountIban" : "DE88500105176132978326",
      "collectingEnabled" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/3b417ca9-93fb-4da4-a933-91e906c33737/shops/736b49b1-a169-404c-8792-92708bc0ea22"
        },
        "logo" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/3b417ca9-93fb-4da4-a933-91e906c33737/shops/736b49b1-a169-404c-8792-92708bc0ea22/logo"
        }
      }
    }, {
      "shopId" : "e05a2b5e-18a5-4acb-8b27-4b9fb0d3ddfc",
      "name" : "Anyshop",
      "type" : "WEB_SHOP",
      "url" : "http://www.anyshop.example.com",
      "merchantCategory" : "1520",
      "fraudEmail" : "fraud@mail.de",
      "disputeEmail" : "dispute@mail.de",
      "merchantAuthorizationReference" : "VcVN5ZkSUgMSJaJ7feUDkhxqOFytYo2qEksMLRqPltg=",
      "bankAccountIban" : "DE37500105172313797565",
      "bankAccountBic" : "INGDDEFFXXX",
      "bankAccountOwnerName" : "Some BankAccountOwner",
      "refundBankAccountIban" : "DE88500105176132978326",
      "collectingEnabled" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/3b417ca9-93fb-4da4-a933-91e906c33737/shops/e05a2b5e-18a5-4acb-8b27-4b9fb0d3ddfc"
        },
        "logo" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/3b417ca9-93fb-4da4-a933-91e906c33737/shops/e05a2b5e-18a5-4acb-8b27-4b9fb0d3ddfc/logo"
        }
      }
    } ]
  }
}

Patch a shop

The query for a specific shop has to include the merchant ID as well as the ID of the shop.

Request

PATCH /api/psp/merchant/v1/merchants/{merchantId}/shops/{shopId}

All properties are optional. Properties that should not be changed have to be absent in the request.

Field Type Characteristics Description

name

String

Maximum 100 characters.

Name of the shop.

url

String

Must be a valid Url.

URL of the shop’s website.

merchantCategory

String

Merchant category code (MCC) following the ISO 18245 format.

fraudEmail

String

Email address of the fraud contact.

disputeEmail

String

An email address used for any kind of disputes (exception: fraud). If not specified, the associated acquirer’s dispute email address is contacted in case of issues.

bankAccountIban

String

Optional. Must follow the ISO 7064 format.

The IBAN of the shop’s bank account.

bankAccountBic

String

Must be a valid BIC for an existing bank in the giropay system. Capital letters only.

The BIC of the shop’s account.

bankAccountOwnerName

String

The name of the owner of the shop’s bank account.

refundBankAccountIban

String

Optional. Must follow the ISO 7064 format and must belong to the same bank as the shop’s bank account.

The IBAN of the shop’s refund bank account.

collectingEnabled

Boolean

Mandatory if the collecting status of the owning giropay PSP is set to MIXED.
Optional if the owning giropay PSP either never or exclusively collects for merchants. Then collectingEnabled has to match the collecting status of the PSP master data in the giropay system.

Indicates whether the created bank account IBAN of the shop is a bank account of the owning giropay PSP.

Response

In the response, the data of the patched shop is returned. The structure is identical to the data returned from the GET call.

Field Type Characteristics Description

shopId

String

Always present.

ID of the shop.

name

String

Always present.

Name of the shop.

type

String

Always present.

Shop type, either a web shop, app shop, or point of sale shop.

url

String

Present if the shop is a web shop, otherwise empty.

URL of the shop’s website.

merchantCategory

String

Always present.

Merchant category code (MCC) following the ISO 18245 format.

fraudEmail

String

Optional.

Email address of the fraud contact.
If not specified, the field will be set to the same value as disputeEmail.

disputeEmail

String

Optional.

An email address used for any kind of disputes (exception: fraud). If not specified, the associated acquirer’s dispute email address is contacted in case of issues.

merchantAuthorizationReference

String

Always present.

Merchant authorization reference. The reference must be provided when creating a checkout for the merchant shop.

bankAccountIban

String

Always present.

The IBAN of the shop’s bank account.

bankAccountBic

String

Always present.

The BIC of the shop’s account.

bankAccountOwnerName

String

Always present.

The name of the owner of the shop’s bank account.

refundBankAccountIban

String

Present if the IBAN was set.

The IBAN of the shop’s refund bank account.

collectingEnabled

Boolean

Optional.

Indicates whether the created bank account IBAN of the shop is a bank account of the owning giropay PSP.

Return codes

Status code Message code Description

200 (Ok)

Shop found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

404 (Not Found)

SHOP_NOT_FOUND

The requested shop does not exist.

422 (Unprocessable Entity)

INVALID_COLLECTING_STATUS_SHOP

The requested collectingEnabled attribute of the shop does not match the collecting status of the psp master data in the giropay system. If the requested value is correct, please contact your giropay administrator.

422 (Unprocessable Entity)

BANK_NOT_FOUND

1. The BIC of one shop does not exist on an active bank in the giropay system.

2. The requested refundBankAccountIban does not belong to any active bank in the giropay system.

If the requested values are correct, please contact your giropay administrator.

422 (Unprocessable Entity)

REFUND_IBAN_DOES_NOT_MATCH_TRANSFER_BANK

The requested refundBankAccountIban does not belong to the shop’s bank.

422 (Unprocessable Entity)

BANK_ACCOUNT_IBAN_AND_BIC_DO_NOT_MATCH

The IBAN and BIC do not belong to the same bank.

Example

PATCH /api/psp/merchant/v1/merchants/cf9ad6c8-fbf4-485e-82c2-bfb3343f2236/shops/9ec86756-3404-430a-9f2e-e90b5f51bfa2 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "name" : "shopName",
  "url" : "https://giropay.de",
  "merchantCategory" : "3015",
  "fraudEmail" : "fraud@mail.com",
  "disputeEmail" : "dispute@mail.com",
  "bankAccountIban" : "DE54500105171238439739",
  "bankAccountBic" : "INGDDEFFXXX",
  "bankAccountOwnerName" : "Some BankAccountOwner",
  "collectingEnabled" : true,
  "refundBankAccountIban" : "DE39500105171438272716"
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "shopId" : "9ec86756-3404-430a-9f2e-e90b5f51bfa2",
  "name" : "shopName",
  "type" : "WEB_SHOP",
  "url" : "https://giropay.de",
  "merchantCategory" : "3015",
  "fraudEmail" : "fraud@mail.com",
  "disputeEmail" : "dispute@mail.com",
  "merchantAuthorizationReference" : "7zQlHV-lto6jvgAWMXcLuB5jRD9byAThNeT3SEuYJIQ=",
  "bankAccountIban" : "DE54500105171238439739",
  "bankAccountBic" : "INGDDEFFXXX",
  "bankAccountOwnerName" : "Some BankAccountOwner",
  "refundBankAccountIban" : "DE39500105171438272716",
  "collectingEnabled" : true,
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/cf9ad6c8-fbf4-485e-82c2-bfb3343f2236/shops/9ec86756-3404-430a-9f2e-e90b5f51bfa2"
    },
    "logo" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/cf9ad6c8-fbf4-485e-82c2-bfb3343f2236/shops/9ec86756-3404-430a-9f2e-e90b5f51bfa2/logo"
    }
  }
}

Delete a shop

Request

DELETE /api/psp/merchant/v1/merchants/{merchantId}/shops/{shopId}

Response

The response does not contain a body.

Return codes

Status code Message code Description

204 (No Content)

The shop data was deleted.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

404 (Not Found)

SHOP_NOT_FOUND

The requested shop does not exist.

422 (Unprocessable Entity)

ILLEGAL_MERCHANT_STATUS

The status of the merchant linked to the shop is required to be NOT_ACTIVE.

Example

DELETE /api/psp/merchant/v1/merchants/dc491030-a900-45e6-877d-6b51f1180865/shops/a7e1c0bd-a692-4172-8f9c-d83a7152e63c HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 204 No Content

The logo of a merchant’s shop can be administrated via the separate endpoint described in this section.

Create/Update a shop logo

A logo can be assigned to a merchant’s shop via this endpoint.

POST /api/psp/merchant/v1/merchants/{merchantId}/shops/{shopId}/logo

The logo image will be transmitted as multipart file in the request body. The name of the parameter for the file must be logo. The requirements for the image are as follows:

  • Image type must be either png or jpg

  • Resolution at a maximum of 1024 x 1024 (1 MP)

  • File size at a maximum of 512 kB

In the response only a status code will be transmitted.

Return Codes

Status Code Message Code Description

201 (Created)

The Logo has been created/updated.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See also Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

404 (Not Found)

SHOP_NOT_FOUND

The requested shop does not exist.

Example

POST /api/psp/merchant/v1/merchants/91173e1e-6e6c-4479-9c6a-9b03d2e9d54f/shops/e2a58c48-e5e4-4b0d-9198-666ab08de69d/logo HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Authorization: Bearer <access_token>

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=logo; filename=Retina-Logo.png
Content-Type: image/png
HTTP/1.1 201 Created

Read a shop logo

A logo of a shop can be retrieved via this endpoint, which can be accessed without authentication.

GET /api/psp/merchant/v1/merchants/{merchantId}/shops/{shopId}/logo

Response

As a response, the endpoint returns the logo of the merchant.

Return Codes

Status Code Message Code Description

200 (Ok)

The logo has been returned.

404 (Not Found)

The requested logo could not be found.

Example

GET /api/psp/merchant/v1/merchants/efbefe8d-26c6-4b23-9102-4347ebffd398/shops/4d6135b5-8e11-4e87-b971-efa1587db646/logo HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: image/png;charset=utf-8

Contacts

Each merchant can have multiple contacts with different roles.

Create contacts

Creates one or more contacts for an existing merchant. By providing an array of contact roles, multiple contacts can be created at once.

POST /api/psp/merchant/v1/merchants/{merchantId}/contacts

Request

Field Type Characteristics Description

familyName

String

Mandatory. Maximum 100 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&+'.

Last name.

givenName

String

Mandatory. Maximum 100 characters.

First name.

email

String

Mandatory.

Email address.

phone

String

Mandatory. Maximum 20 characters.

Phone number.

mobilePhone

String

Optional. Maximum 20 characters.

Mobile phone number.

responsibility

String

Optional. Maximum 1000 characters.

Description of the contact’s responsibility.

address

PostalAddress

Optional.

PostalAddress

roles

Array

Mandatory. An array which contains one or more of the following values: BUSINESS, TECHNICAL, DISPUTE, FRAUD, FEE_SETTLEMENT.

Roles.

Response

Returns a list of contacts. The response is the same as for querying all contacts via GET.

Return codes

Status code Message code Description

201 (Created)

One or more contacts have been created.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

400 (Bad Request)

VALIDATION_ERROR

The request is syntactically invalid.

400 (Bad Request)

CONTACT_ROLES_NOT_VALID

The given array of contact roles contains invalid values.

400 (Bad Request)

INVALID_PHONENUMBER

The given phone number is invalid.

Example

POST /api/psp/merchant/v1/merchants/68dfd1a7-5702-4742-b652-7847a276efdc/contacts HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "familyName" : "Schmitt",
  "givenName" : "Patrick",
  "email" : "patrick.schmitt@example.org",
  "phone" : "+49 30 1234567",
  "roles" : [ "DISPUTE", "BUSINESS" ],
  "mobilePhone" : "+49 170 1234567",
  "responsibility" : "some responsbility",
  "address" : {
    "company" : "AnyCompany",
    "street" : "Beethovenstr",
    "streetNr" : "1",
    "additionalAddressInformation" : "Some additional information",
    "zip" : "12345",
    "city" : "Berlin",
    "country" : "DE"
  }
}
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=utf-8

{
  "_embedded" : {
    "contacts" : [ {
      "contactId" : "1893c2a1-b01f-4194-a7be-0df408c4758c",
      "familyName" : "Schmitt",
      "givenName" : "Patrick",
      "email" : "patrick.schmitt@example.org",
      "phone" : "+49 30 1234567",
      "mobilePhone" : "+49 170 1234567",
      "responsibility" : "some responsbility",
      "role" : "DISPUTE",
      "address" : {
        "company" : "AnyCompany",
        "street" : "Beethovenstr",
        "streetNr" : "1",
        "additionalAddressInformation" : "Some additional information",
        "zip" : "12345",
        "city" : "Berlin",
        "country" : "DE"
      },
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/68dfd1a7-5702-4742-b652-7847a276efdc/contacts/1893c2a1-b01f-4194-a7be-0df408c4758c"
        }
      }
    }, {
      "contactId" : "7147b8d3-2f8b-46c7-b0d7-f19342064958",
      "familyName" : "Schmitt",
      "givenName" : "Patrick",
      "email" : "patrick.schmitt@example.org",
      "phone" : "+49 30 1234567",
      "mobilePhone" : "+49 170 1234567",
      "responsibility" : "some responsbility",
      "role" : "BUSINESS",
      "address" : {
        "company" : "AnyCompany",
        "street" : "Beethovenstr",
        "streetNr" : "1",
        "additionalAddressInformation" : "Some additional information",
        "zip" : "12345",
        "city" : "Berlin",
        "country" : "DE"
      },
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/68dfd1a7-5702-4742-b652-7847a276efdc/contacts/7147b8d3-2f8b-46c7-b0d7-f19342064958"
        }
      }
    } ]
  }
}

Read a contact

In order to query a single contact, the IDs of both the merchant and the contact are required.

GET /api/psp/merchant/v1/merchants/{merchantId}/contacts/{contactId}

Response

Field Type Characteristics Description

contactId

String

Always present.

ID of the contact.

familyName

String

Always present.

Last name.

givenName

String

Always present.

First name.

email

String

Always present.

Email address.

phone

String

Always present.

Phone number.

mobilePhone

String

Optional.

Mobile phone number.

responsibility

String

Optional.

Description of the contact’s responsibility.

address

PostalAddress

Optional.

PostalAddress

role

String

Always present.

Role.

Links

Relation Description

self

Link to this resource.

Return codes

Status code Message code Description

200 (Ok)

Contact found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

404 (Not Found)

CONTACT_NOT_FOUND

The requested contact does not exist.

Example

GET /api/psp/merchant/v1/merchants/9341df93-332f-48b2-b035-9e08e6ee7888/contacts/4934fcf7-1197-4daf-8809-fe6119203e6d 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

{
  "contactId" : "4934fcf7-1197-4daf-8809-fe6119203e6d",
  "familyName" : "Meyer",
  "givenName" : "Lisa",
  "email" : "lisa.meyer@example.org",
  "phone" : "+49 30 12345678",
  "mobilePhone" : "+49 170 12345678",
  "responsibility" : "Some comment regarding this dispute contact.",
  "role" : "DISPUTE",
  "address" : {
    "company" : "AnyCompany",
    "street" : "Beethovenstr.",
    "streetNr" : "1",
    "additionalAddressInformation" : "Some additional information",
    "zip" : "12345",
    "city" : "Berlin",
    "country" : "DE"
  },
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/9341df93-332f-48b2-b035-9e08e6ee7888/contacts/4934fcf7-1197-4daf-8809-fe6119203e6d"
    }
  }
}

Read all contacts

Query all contacts belonging to a merchant.

GET /api/psp/merchant/v1/merchants/{merchantId}/contacts

Response

A list of contacts. Each entry in the list is a separate contact object, as described in the response of a single contact. If no contacts are available, the resulting list will be empty.

Return codes

Status code Message code Description

200 (Ok)

Contact(s) found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

Example

GET /api/psp/merchant/v1/merchants/4ac427aa-705d-4925-b4a8-6d9b6b178fa5/contacts 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

{
  "_embedded" : {
    "contacts" : [ {
      "contactId" : "17d1bb6f-118a-41ca-bef8-8e7b6a56543a",
      "familyName" : "Schmitt",
      "givenName" : "Patrick",
      "email" : "patrick.schmitt@example.org",
      "phone" : "+49 30 1234567",
      "mobilePhone" : "+49 170 1234567",
      "role" : "BUSINESS",
      "address" : {
        "company" : "AnyCompany",
        "street" : "Beethovenstr.",
        "streetNr" : "1",
        "additionalAddressInformation" : "Some additional information",
        "zip" : "12345",
        "city" : "Berlin",
        "country" : "DE"
      },
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/4ac427aa-705d-4925-b4a8-6d9b6b178fa5/contacts/17d1bb6f-118a-41ca-bef8-8e7b6a56543a"
        }
      }
    }, {
      "contactId" : "37402654-dd8b-47e7-aa5c-7d5cea61d77d",
      "familyName" : "Meyer",
      "givenName" : "Lisa",
      "email" : "lisa.meyer@example.org",
      "phone" : "+49 30 12345678",
      "mobilePhone" : "+49 170 12345678",
      "responsibility" : "Some comment regarding this dispute contact.",
      "role" : "DISPUTE",
      "address" : {
        "company" : "AnyCompany",
        "street" : "Beethovenstr.",
        "streetNr" : "1",
        "additionalAddressInformation" : "Some additional information",
        "zip" : "12345",
        "city" : "Berlin",
        "country" : "DE"
      },
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/4ac427aa-705d-4925-b4a8-6d9b6b178fa5/contacts/37402654-dd8b-47e7-aa5c-7d5cea61d77d"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/4ac427aa-705d-4925-b4a8-6d9b6b178fa5/contacts"
    }
  }
}

Patch a contact

The query for a specific contact has to include the merchant ID as well as the ID of the contact.

Request

PATCH /api/psp/merchant/v1/merchants/{merchantId}/contacts/{contactId}

All properties are optional. Properties that should not be changed have to be absent in the request.

Please note that single properties of the address cannot be patched. The address can only be changed as a whole by providing a valid PostalAddress request with all its properties being present.

Field Type Characteristics Description

familyName

String

Maximum 100 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&+'.

Last name.

givenName

String

Maximum 100 characters.

First name.

email

String

Email address.

phone

String

Maximum 20 characters.

Phone number.

mobilePhone

String

Maximum 20 characters.

Mobile phone number.

responsibility

String

Maximum 1000 characters.

Description of the contact’s responsibility.

address

PostalAddress

PostalAddress

role

String

One of the following values: BUSINESS, TECHNICAL, DISPUTE, FRAUD, FEE_SETTLEMENT.

Role.

Response

In the response, the data of the patched contact is returned. The structure is identical to the data returned from the GET call.

Field Type Characteristics Description

contactId

String

Always present.

ID of the contact.

familyName

String

Always present.

Last name.

givenName

String

Always present.

First name.

email

String

Always present.

Email address.

phone

String

Always present.

Phone number.

mobilePhone

String

Optional.

Mobile phone number.

responsibility

String

Optional.

Description of the contact’s responsibility.

address

PostalAddress

Optional.

PostalAddress

role

String

Always present.

Role.

Return codes

Status code Message code Description

200 (Ok)

Contact found.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

404 (Not Found)

CONTACT_NOT_FOUND

The requested contact does not exist.

Example

PATCH /api/psp/merchant/v1/merchants/f4899d3a-2a0e-4fbf-b1dc-8aafd84703a2/contacts/4d5772e3-9838-4f7b-aeef-fbd8ba1d8eb7 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>

{
  "familyName" : "Fischer",
  "givenName" : "Emma",
  "email" : "emma.fischer@example.org",
  "phone" : "+49 30 1234567",
  "role" : "TECHNICAL",
  "mobilePhone" : "+49 178 1234567",
  "responsibility" : "Some comment",
  "address" : {
    "company" : "AnyBusiness",
    "street" : "Schillerstr",
    "streetNr" : "1",
    "additionalAddressInformation" : "Some additional information",
    "zip" : "56789",
    "city" : "Hamburg",
    "country" : "DE"
  }
}
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=utf-8

{
  "contactId" : "4d5772e3-9838-4f7b-aeef-fbd8ba1d8eb7",
  "familyName" : "Fischer",
  "givenName" : "Emma",
  "email" : "emma.fischer@example.org",
  "phone" : "+49 30 1234567",
  "mobilePhone" : "+49 178 1234567",
  "responsibility" : "Some comment",
  "role" : "TECHNICAL",
  "address" : {
    "company" : "AnyBusiness",
    "street" : "Schillerstr",
    "streetNr" : "1",
    "additionalAddressInformation" : "Some additional information",
    "zip" : "56789",
    "city" : "Hamburg",
    "country" : "DE"
  },
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/f4899d3a-2a0e-4fbf-b1dc-8aafd84703a2/contacts/4d5772e3-9838-4f7b-aeef-fbd8ba1d8eb7"
    }
  }
}

Delete a contact

Request

DELETE /api/psp/merchant/v1/merchants/{merchantId}/contacts/{contactId}

Response

The response does not contain a body.

Return codes

Status code Message code Description

204 (No Content)

The contact was deleted.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

404 (Not Found)

MERCHANT_NOT_FOUND

The requested merchant does not exist.

404 (Not Found)

CONTACT_NOT_FOUND

The requested contact does not exist.

Example

DELETE /api/psp/merchant/v1/merchants/47fd0604-71f0-4071-9e7d-026171ae4a7c/contacts/7dfd1278-d88e-422b-bf82-301e03302016 HTTP/1.1
Content-Type: application/json;charset=utf-8
Authorization: Bearer <access_token>
HTTP/1.1 204 No Content

Complete merchant

All resources described in the previous sections that make up a complete merchant can alternatively be created with just a single request. To this end, the sub resources for postal address, shops, agreement sets, and contacts can be embedded within the request for creating the merchant’s base data. Additionally, the merchant status can be set to ACTIVE with that same request. This results in a completely set-up and activated merchant. The whole request is processed atomically: Either the entire merchant resource with all its sub resources is written if it is valid and complete, or it is rejected in its entirety if a single necessary requirement is not met. This potentially simplifies the overall process for merchant creation.

Create a complete merchant

POST /api/psp/merchant/v1/merchants

A new complete merchant can be created via this endpoint. The necessary sub resources for postal address, agreement set, shops, and contacts can be embedded within this request.

Please note that for creating a complete merchant in status ACTIVE the same requirements apply as described in Update Merchant

Request

Field Type Characteristics Description

name

String

Mandatory. Maximum 100 characters.

Name of the merchant.

merchantStatus

String

Set this field to ACTIVE if you wish to create an active merchant. Please consider the requirements for merchant activation, see Update Merchant.

formOfOrganisation

String

Mandatory.

Legal form, e.g., GmbH, AG, …​

commercialRegisterType

String

Optional.

Type of the commercial register entry (HRA/HRB).

commercialRegisterNumber

String

Optional.

Commercial register number.

parentCorporationId

String

Optional. Maximum 100 characters.

ID of the parent corporation.

valueAddedTaxNumber

String

Optional. Maximum 100 characters.

Value added tax identification number.

merchantType

String

Mandatory. Use GIROPAY_MERCHANT as type identifier for giropay merchants.

Merchant type. Here always GIROPAY_MERCHANT.

marketingEnabled

Boolean

Optional.

Indicates whether the acquirer has granted paydirekt GmbH the right for merchant marketing (default: true).

creditorId

String

Mandatory if the merchant has at least one shop with collectingEnabled set to false.
Must be a valid creditorId (see Creditor Identifier).

Creditor identification number.

_embedded.postalAddress

Object

The postal address of this managed merchant.

_embedded.agreementSets

Array

The list of agreement set references assigned to this merchant.

_embedded.shops

Array

The list of shops owned by the managed merchant.

_embedded.contacts

Array

The list of contacts owned by the managed merchant.

Response

In the response, the created merchant base data is returned. The structure is identical to the endpoint for GET calls, in particular the response contains the ID of the created merchant and all links relevant for the resource.

Return codes

Status code Message code Description

201 (Created)

The merchant was created.

401 (Unauthorized)

ACCESS_TOKEN_EXPIRED

See Resource access.

422 (Unprocessable Entity)

NO_SHOP

Only when activating: The merchant does not have a shop.

422 (Unprocessable Entity)

EFFECTIVE_AGREEMENT_SET_REFERENCE_REQUIRED

Only when activating: The merchant does not have an effective agreement set reference (see agreement set references).

422 (Unprocessable Entity)

INVALID_COLLECTING_STATUS_SHOP

The requested collectingEnabled attribute of one of the merchant’s shops does not match the collecting status of the psp master data in the giropay system (see shops). If the requested value is correct, please contact your giropay administrator.

422 (Unprocessable Entity)

BANK_NOT_FOUND

1. The BIC of one shop does not exist on an active bank in the giropay system.

2. The requested refundBankAccountIban does not belong to any active bank in the giropay system.

If the requested values are correct, please contact your giropay administrator.

422 (Unprocessable Entity)

REFUND_IBAN_DOES_NOT_MATCH_TRANSFER_BANK

One of the requested refundBankAccountIban does not belong to the corresponding shop’s bank.

422 (Unprocessable Entity)

MISSING_CREDITOR_ID

The required creditorId in the merchant base data is missing.

422 (Unprocessable Entity)

POSTAL_ADDRESS_NOT_EXISTING

The required postalAddress is missing.

422 (Unprocessable Entity)

BANK_ACCOUNT_IBAN_AND_BIC_DO_NOT_MATCH

One of the IBANs and BICs do not belong to the same bank.

Example

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

{
  "name" : "someName",
  "merchantStatus" : "ACTIVE",
  "formOfOrganisation" : "someForm",
  "commercialRegisterType" : "someCommType",
  "commercialRegisterNumber" : "someCommNumber",
  "parentCorporationId" : "someParentCorp",
  "valueAddedTaxNumber" : "someTaxNumber",
  "merchantType" : "GIROPAY_MERCHANT",
  "marketingEnabled" : true,
  "creditorId" : "DE98ZZZ09999999999",
  "_embedded" : {
    "postalAddress" : {
      "company" : "Some Company",
      "street" : "Some Street",
      "streetNr" : "42a",
      "additionalAddressInformation" : "Some Additional Information",
      "zip" : "12345",
      "city" : "Some City",
      "country" : "DE"
    },
    "agreementSets" : [ {
      "agreementSetId" : "21b77fa0-bbe2-419e-b0d9-77311dba1ca9",
      "startDate" : "2021-01-01"
    } ],
    "shops" : [ {
      "name" : "Some Shop Name",
      "type" : "WEB_SHOP",
      "url" : "https://www.someshop.invalid/",
      "merchantCategory" : "7911",
      "bankAccountIban" : "DE37500105172313797565",
      "bankAccountBic" : "INGDDEFFXXX",
      "bankAccountOwnerName" : "Some Bank Account Owner",
      "fraudEmail" : "fraud@someshop.invalid",
      "disputeEmail" : "dispute@someshop.invalid",
      "collectingEnabled" : false,
      "refundBankAccountIban" : "DE88500105176132978326"
    } ],
    "contacts" : [ {
      "familyName" : "Some Family Name",
      "givenName" : "Some Given Name",
      "email" : "someuser@someshop.invalid",
      "phone" : "+49 1234 56789",
      "roles" : [ "BUSINESS", "TECHNICAL" ],
      "mobilePhone" : "+49 1234 56789",
      "responsibility" : "Some Responsibility",
      "address" : {
        "company" : "Some Company",
        "street" : "Some Street",
        "streetNr" : "42a",
        "additionalAddressInformation" : "Some Additional Information",
        "zip" : "12345",
        "city" : "Some City",
        "country" : "DE"
      }
    } ]
  }
}
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=utf-8

{
  "merchantId" : "18928e9a-a029-4f2c-9c5c-bba484395a74",
  "name" : "someName",
  "merchantType" : "GIROPAY_MERCHANT",
  "formOfOrganisation" : "someForm",
  "commercialRegisterType" : "someCommType",
  "commercialRegisterNumber" : "someCommNumber",
  "parentCorporationId" : "someParentCorp",
  "valueAddedTaxNumber" : "someTaxNumber",
  "marketingEnabled" : true,
  "creditorId" : "DE98ZZZ09999999999",
  "checkoutCreationLocked" : false,
  "merchantStatus" : "ACTIVE",
  "_links" : {
    "self" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74"
    },
    "shops" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/shops"
    },
    "postalAddress" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/address"
    },
    "agreementSets" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/agreementsets"
    },
    "contacts" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/contacts"
    },
    "downstreamPsps" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/downstreampsps"
    },
    "authorizedPsps" : {
      "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/authorizedpsps"
    }
  },
  "_embedded" : {
    "postalAddress" : {
      "company" : "Some Company",
      "street" : "Some Street",
      "streetNr" : "42a",
      "additionalAddressInformation" : "Some Additional Information",
      "zip" : "12345",
      "city" : "Some City",
      "country" : "DE",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/address"
        }
      }
    },
    "shops" : [ {
      "shopId" : "5e66da03-af95-4fd7-ba97-b5cb45ae31d7",
      "name" : "Some Shop Name",
      "type" : "WEB_SHOP",
      "url" : "https://www.someshop.invalid/",
      "merchantCategory" : "7911",
      "fraudEmail" : "fraud@someshop.invalid",
      "disputeEmail" : "dispute@someshop.invalid",
      "merchantAuthorizationReference" : "Be4ycrsuqsPdZB7-oVFM0LR3ffVAaPN0zng2r7FB-mM=",
      "bankAccountIban" : "DE37500105172313797565",
      "bankAccountBic" : "INGDDEFFXXX",
      "bankAccountOwnerName" : "Some Bank Account Owner",
      "refundBankAccountIban" : "DE88500105176132978326",
      "collectingEnabled" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/shops/5e66da03-af95-4fd7-ba97-b5cb45ae31d7"
        },
        "logo" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/shops/5e66da03-af95-4fd7-ba97-b5cb45ae31d7/logo"
        }
      }
    } ],
    "contacts" : [ {
      "contactId" : "0096e37f-5ae8-43b3-a188-f4558ba47c2b",
      "familyName" : "Some Family Name",
      "givenName" : "Some Given Name",
      "email" : "someuser@someshop.invalid",
      "phone" : "+49 123456789",
      "mobilePhone" : "+49 123456789",
      "responsibility" : "Some Responsibility",
      "role" : "TECHNICAL",
      "address" : {
        "company" : "Some Company",
        "street" : "Some Street",
        "streetNr" : "42a",
        "additionalAddressInformation" : "Some Additional Information",
        "zip" : "12345",
        "city" : "Some City",
        "country" : "DE"
      },
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/contacts/0096e37f-5ae8-43b3-a188-f4558ba47c2b"
        }
      }
    }, {
      "contactId" : "1e9c2ebb-fb37-4d2d-b4a7-2f53c8470185",
      "familyName" : "Some Family Name",
      "givenName" : "Some Given Name",
      "email" : "someuser@someshop.invalid",
      "phone" : "+49 123456789",
      "mobilePhone" : "+49 123456789",
      "responsibility" : "Some Responsibility",
      "role" : "BUSINESS",
      "address" : {
        "company" : "Some Company",
        "street" : "Some Street",
        "streetNr" : "42a",
        "additionalAddressInformation" : "Some Additional Information",
        "zip" : "12345",
        "city" : "Some City",
        "country" : "DE"
      },
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/contacts/1e9c2ebb-fb37-4d2d-b4a7-2f53c8470185"
        }
      }
    } ],
    "agreementSets" : [ {
      "referenceId" : "f16dfdbe-ac80-48f0-a4e5-0fbb052eae14",
      "agreementSetId" : "21b77fa0-bbe2-419e-b0d9-77311dba1ca9",
      "startDate" : "2021-01-01",
      "_links" : {
        "self" : {
          "href" : "https://api.paydirekt.de/api/psp/merchant/v1/merchants/18928e9a-a029-4f2c-9c5c-bba484395a74/agreementsets/f16dfdbe-ac80-48f0-a4e5-0fbb052eae14"
        }
      }
    } ]
  }
}

Common data types

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

PostalAddress

Data type for postal addresses.

Field Type Characteristics Description

company

String

Mandatory. Maximum 100 characters.

Company name.

street

String

Mandatory. Maximum 100 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&+'.

Street.

streetNr

String

Mandatory. Maximum 10 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&+.

Street number.

additionalAddressInformation

String

Optional. Maximum 100 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&!"?+'_:´`.

Additional address information.

zip

String

Optional. Maximum 10 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&.

Postal code.

city

String

Mandatory. Maximum 100 characters. Allowed: Letters, numbers, whitespaces and the special characters -./,()&+'.

Town or city.

country

String

Optional.

Country code following the ISO 3166-1 alpha-2 format.

 
{
  "company" : "AnyCompany",
  "street" : "Beethovenstr.",
  "streetNr" : "1",
  "additionalAddressInformation" : "Some additional information",
  "zip" : "12345",
  "city" : "Berlin",
  "country" : "DE"
}

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"
}

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

04.07.2023

CHANGE

Edit BANK_NOT_FOUND exception. Indicating that bank might be an inactive bank in the giropay system.

Several sections of the document

30.03.2023

FIX

Added usage of correct possessive apostrophe.

Several sections of the document

10.03.2023

CHANGE

Acquirer agreement set references can only be edited or deleted if they have a future start date.

Update an agreement set reference, Delete an agreement set reference

03.03.2023

NEW_INFO

Added additional information about initial merchantStatus after create.

Create merchant

14.02.2023

CHANGE

Added additional information regarding allowed characters for PostalAddress and Contacts.

Postal Address, Create contacts, Patch a contact

08.02.2023

CHANGE

Edit response presence of valueAddedTaxNumber, now Optional.

Read a merchant, Patch a merchant

07.02.2023

FEATURE

1. Added two new endpoints in order to enable administration of authorized PSPs.
2. Added name attribute to response.
3. Added HAL links referring the new endpoints in several responses.

1. Read all available downstream PSPs, Read all authorized PSPs;
2. Authorize a PSP;
3. Create a merchant, Update a merchant, Read a merchant

07.02.2023

CHANGE

Changed return status code of merchant address update from 204 to 200.

Create/Update a merchant’s address

01.02.2023

CHANGE

Changed request field constraint of valueAddedTaxNumber from Mandatory to Optional.

Create a complete merchant, Create a merchant

27.01.2023

CHANGE

Added validation to ensure IBAN and BIC of bankAccount belong to the same bank.

Create a shop, Patch a shop, Create a complete merchant