Description

The sandbox is an environment which allows you to test your application. This environment simulates API responses of the requests described in API page of this developer portal.

To get a response the request has to match certain headers, path and query parameters with specific values described below. Any deviation in these parameters may return in an error code.

The endpoints used in the sandbox environment are identical as those used in production.

Before starting

Like in the environment production, you will need to have a valid QWAC certificate in order to perform the requests. This certificate is mandatory; otherwise you will get an error.

All the specified values to use for the requests will be described in the next paragraphs.

AIS Consent creation
Initiate a consent (Single SCA)
POST /berlingroup/v1/consents

To initiate a consent with an implicit authorization on this consent, the header “TPP-Explicit-Authorisation-Preferred” of this request has to be set to “false”.

Authorize the AIS consent

The authorisation workflow implements the BerlinGroup redirect scenario using OAuth2 SCA Protocol.

The sandbox offers the possibility to simulate the different authentications scenarios (see the table below) using the following page:

https://xs2a-sandbox.comdirect.de/public/berlingroup/authorize?scope=AIS:VALID_CONSENT_ID&client_id=VALID_CLIENT_ID&state=test&redirect_uri=http://localhost&code_challenge=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&response_type=code&code_challenge_method=S256

 

 Authorize case

 Description

 LOGIN_CANCEL

 If the login phase was cancelled by the PSU

 LOGIN_TIMEOUT

 If the login phase encountered a timeout

 LOGIN_OTHER_ERROR

 If another error occurred during the login phase

 LOGIN_REQUEST_REJECTED

 If the login phase was rejected

 BAD_PASSWORD_LOGIN

 If an error occurred during the login phase with a bad password

 UNKNOWN_LOGIN

 If an error occurred during the login phase with an unknown login

 SCA_OK

 To get a successful authorization

 SCA_EXEMPTED

 If the SCA phase was exempted

 SCA_CANCEL

 If the SCA phase was cancelled by the PSU

 SCA_TIMEOUT

 If the SCA phase encountered a timeout

 SCA_OTHER_ERROR

 If another error occurred during the SCA phase

 SCA_NOK

 If the SCA phase did not succeed

 SCA_REQUEST_REJECTED

 If the SCA phase was rejected

 SCA_INTERNAL_ERROR

 If an internal error occurred

 

Get an AIS access Token
GET /berlingroup/v1/token

In order to access the PSD2 request you need to get an access token for your application.

Here are the different “authorization_code” that you can use in the “code” header of the request.

 Code

 Description

 AIS_VALID_CODE

 Valid code to get an access token for the consent “VALID_CONSENT_ID”

 AIS_VALID_CODE_REVOKED_BY_PSU

 Valid code to get an access token for the consent “CONSENT_ID_REVOKED_BY_PSU”

 AIS_VALID_CODE_TERMINATED_BY_TPP

 Valid code to get an access token for the consent “CONSENT_ID_REVOKED_BY_PSU”

 AIS_VALID_CODE_TRANSACTION_90D_KO

 Valid code to get an access token for the consent “CONSENT_ID_TRANSACTION_90D_KO”

 AIS_VALID_CODE_EXPIRED

 Valid code to get an access token for the consent “CONSENT_ID_EXPIRED”

 EXPIRED_CODE

 To test an expired code

 AIS_VALID_CODE_MULTICURRENCY

 Valid code to get an access token for the consent “CONSENT_ID_MULTICURRENCY”

Also, use "VALID_CLIENT_ID" as value for the "client_id" parameter of the request.

 

The response to this API comes in the form of a JSON object with the following structure:

{

    "access_token": "4db39597dc674268a7fa253d255c47cec7618d14ebdd433a984a7680ce0b77ad0bd76a3a55e8455b980bf41c833a03ce",

    "token_type": "Bearer",

    "expires_in": 3600,

    "refresh_token": "e3da5c9922a34d6e8fa0fa4b780acc2c1ad3a05d485f43f08580250d26a1782b0544973a64204185a9257ca07143c0bb",

    "scope": "AIS:VALID_CONSENT_ID"

}

This will be the access that has a limited time validity that you have to use for the future request.

According to Oauth2 specification, you can exchange this access token for a refresh token still using the /Token API but with a “refresh_token” as grant type in the header of the request:

 

 Key

 Value

 grant_type

 refresh_token

 refresh_token

 4db39597dc674268a7fa253d255c47cec7618d14ebdd433a984a7680ce0b77ad0bd76a3a55e8455b980bf41c833a03ce

 

The refresh token will have a validity of 90 days, the duration of an AIS consent.

Access the consent
GET/berlingroup/v1/consents/{consentId}
GET/berlingroup/v1/consents/{consentId}/status

Here are the different consent ids that you can use to test these APIs.

 

 Consent Id

 Description

 VALID_CONSENT_ID

To retrieve a consent with the status “Valid” and a preselected scope

 CONSENT_ID_REVOKED_BY_PSU

To retrieve a consent with the status “revokedByPsu”

 CONSENT_ID_EXPIRED

To retrieve a consent with the status “expired”

 CONSENT_ID_REJECTED

To retrieve a consent with the status “rejected”

 CONSENT_ID_TERMINATED_BY_TPP

To retrieve a consent with the status “terminatedByTpp”

 CONSENT_ID_RECEIVED

To retrieve a consent with the status “received”

 CONSENT_ID_ALL_PSD2

To retrieve a consent with the status “Valid” and a “allPsd2” scope

 CONSENT_ID_AVAILABLE_ACCOUNTS

To retrieve a consent with the status “Valid” and a “availableAccounts” scope

 CONSENT_ID_AVAILABLE_ACCOUNTS_WITH_BALANCES

To retrieve a consent with the status “Valid” and a “availableAccountsWithBalances” scope

 

Delete a consent

Here are the different consent ids that you can use to test this API.

 Consent Id

 VALID_CONSENT_ID

 CONSENT_ID_REVOKED_BY_PSU

 CONSENT_ID_EXPIRED

 CONSENT_ID_REJECTED

 CONSENT_ID_TERMINATED_BY_TPP

 CONSENT_ID_RECEIVED

 
Get the consent authorizations and status
GET /berlingroup/v1/consents/{consentId}/authorisations

This request retrieves the list of the authorizations of the consent.

You can use the value “VALID_CONSENT_ID” in the request to test this API. If you use another value, the consent will be considered as not found.

GET /berlingroup/v1/consents/{consentId}/authorisations/{consentAuthorizationId}

You can use the value “VALID_CONSENT_ID” and a value for the “consentAuthorizationId” in the request path to test this API. If you use another value, the consent will be considered as not found.

 

consentAuthorizationId

description

AUTHORIZATION_ID_FINALISED

To retrieve a authorization with the status “finalised”

AUTHORIZATION_ID_RECEIVED

To retrieve a authorization with the status “received”

AUTHORIZATION_ID_PSU_IDENTIFIED

To retrieve a authorization with the status “psuIdentified”

AUTHORIZATION_ID_PSU_AUTHENTICATED

To retrieve a authorization with the status “psuAuthenticated”

AUTHORIZATION_ID_SCA_METHOD_SELECTED

To retrieve a authorization with the status “scaMethodSelected”

AUTHORIZATION_ID_STARTED

To retrieve a consent with the status “started”

AUTHORIZATION_ID_FAILED

To retrieve a authorization with the status “failed”

AUTHORIZATION_ID_EXEMPTED

To retrieve a authorization with the status “exempted”

 

Access the AIS accounts
Retrieve all accounts
GET /berlingroup/v1/accounts

Here are the different consent ids that you can use to in the “Consent-Id” header to test this API.

You also have to use the access token for the corresponding status.

Consent Id

Description

VALID_CONSENT_ID

Valid consent

CONSENT_ID_REVOKED_BY_PSU

Consent revoked by the psu

CONSENT_ID_EXPIRED

Consent expired

CONSENT_ID_TERMINATED_BY_TPP

Consent terminated by the TPP

CONSENT_ID_MULTICURRENCY

Consent with multi-currency account

You have a limited access of 4 times per day to a consent. You will have to get a new access token if you want to overpass the limit.

**Note that the "withBalance" parameter in the request URL is not implemented yet in the sandbox.

Retrieve the detail of an account
GET /berlingroup/v1/accounts/{accountId}

Here are the different consent ids that you can use to in the “Consent-Id” header to test this API.

You also have to use the access token for the corresponding status.

 

Consent-Id (header)

Account Id (request parameter)

Description

VALID_CONSENT_ID

ACCOUNT_ID

Account of a valid consent

VALID_CONSENT_ID

*Another value*

No permission on this account

CONSENT_ID_REVOKED_BY_PSU

ACCOUNT_ID

Account of a consent revoked by the psu

CONSENT_ID_EXPIRED

ACCOUNT_ID

Account of an expired consent

CONSENT_ID_TERMINATED_BY_TPP

ACCOUNT_ID

Account of a consent terminated by the TPP

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_XXX

Parent account of a consent with multi-currency account

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_CHILD1

Child account 1 of a consent with multi-currency account

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_CHILD2

Child account 2 of a consent with multi-currency account

 

You have a limited access of 4 times per day to a consent. You will have to get a new access token if you want to overpass the limit.

**Note that the "withBalance" parameter in the request URL is not implemented yet in the sandbox.

Retrieve the balances of an account
GET /berlingroup/v1/accounts/{accountId}/balances

Here are the different consent ids that you can use to in the “Consent-Id” header to test this API.

You also have to use the access token for the corresponding status.

Consent-Id (header)

Account Id (request parameter)

Description

VALID_CONSENT_ID

ACCOUNT_ID

Account of a valid consent

VALID_CONSENT_ID

*Another value*

No permission on this account

CONSENT_ID_REVOKED_BY_PSU

ACCOUNT_ID

Account of a consent revoked by the psu

CONSENT_ID_EXPIRED

ACCOUNT_ID

Account of an expired consent

CONSENT_ID_TERMINATED_BY_TPP

ACCOUNT_ID

Account of a consent terminated by the TPP

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_XXX

Parent account of a consent with multi-currency account

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_CHILD1

Child account 1 of a consent with multi-currency account

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_CHILD2

Child account 2 of a consent with multi-currency account

You have a limited access of 4 times per day to a consent. You will have to get a new access token if you want to overpass the limit.

Retrieve the transactions of an account
GET /berlingroup/v1/accounts/{accountId}/transactions?dateFrom=2019-02-01&bookingStatus=booked

Here are the different consent ids that you can use to in the “Consent-Id” header to test this API.

You also have to use the access token for the corresponding status.

Consent-Id (header)

Account Id (request parameter)

Description

VALID_CONSENT_ID

ACCOUNT_ID

Account of a valid consent

VALID_CONSENT_ID

*Another value*

No permission on this account

CONSENT_ID_REVOKED_BY_PSU

ACCOUNT_ID

Account of a consent revoked by the psu

CONSENT_ID_EXPIRED

ACCOUNT_ID

Account of an expired consent

CONSENT_ID_TERMINATED_BY_TPP

ACCOUNT_ID

Account of a consent terminated by the TPP

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_XXX

Parent account of a consent with multi-currency account

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_CHILD1

Child account 1 of a consent with multi-currency account

CONSENT_ID_MULTICURRENCY

ACCOUNT_ID_MULTI_CURRENCY_CHILD2

Child account 2 of a consent with multi-currency account

CONSENT_ID_TRANSACTION_90D_KO

ACCOUNT_ID

Account where the transactions are over 90 days

You have a limited access of 4 times per day to a consent. You will have to get a new access token if you want to overpass the limit.

**Note that the "withBalance" parameter in the request URL is not implemented yet in the sandbox.

PIS payment initiation
Initiate a payment (Single SCA)
POST /berlingroup/v1/{payment-service}/{payment-product}

Here are the different combinations that you can use in the URL of this request:

Payment service

Payment product

payments

sepa-credit-transfers

cross-border-credit-transfers

instant-sepa-credit-transfers

periodic-payments

sepa-credit-transfers

cross-border-credit-transfers

instant-sepa-credit-transfers

To initiate a payment with an implicit authorization on this payment, the header “TPP-Explicit-Authorisation-Preferred” of this request has to be set to “false”.

Authorize the payment

The authorisation workflow implements the BerlinGroup redirect scenario using OAuth2 SCA Protocol.

The sandbox offers the possibility to simulate the different authentications scenarios (see the table below) using the following page:

https://xs2a-sandbox.comdirect.de/public/berlingroup/authorize?scope=PIS:PAYMENT_ID_RCVD_SCT&client_id=VALID_CLIENT_ID&state=test&redirect_uri=http://localhost&code_challenge=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&response_type=code&code_challenge_method=S256

 Authorize case

 Description

 LOGIN_CANCEL

 If the login phase was cancelled by the PSU

 LOGIN_TIMEOUT

 If the login phase encountered a timeout

 LOGIN_OTHER_ERROR

 If another error occurred during the login phase

 LOGIN_REQUEST_REJECTED

 If the login phase was rejected

 BAD_PASSWORD_LOGIN

 If an error occurred during the login phase with a bad password

 UNKNOWN_LOGIN

 If an error occurred during the login phase with an unknown login

 SCA_OK

 To get a successful authorization

 SCA_EXEMPTED

 If the SCA phase was exempted

 SCA_CANCEL

 If the SCA phase was cancelled by the PSU

 SCA_TIMEOUT

 If the SCA phase encountered a timeout

 SCA_OTHER_ERROR

 If another error occurred during the SCA phase

 SCA_NOK

 If the SCA phase did not succeed

 SCA_REQUEST_REJECTED

 If the SCA phase was rejected

 SCA_INTERNAL_ERROR

 If an internal error occurred

Get a PIS access Token
GET /berlingroup/v1/token

In order to access the PSD2 request for the payment you need to get an access token for your application.

Here is the structure of an “authorization_code” that you can use in the “code” header:

PIS_VALID_CODE_<payment service>_<payment status>_<payment product>

Payment service

Payment status

Payment product

  (payment)

ACCP (AcceptedCustomerProfile)

SCT (sepa credit transfert)

PERIODIC (periodic payment)

ACSC (AcceptedSettlementCompleted)

ISCT (instant sepa credit transfert)

 

ACSP (AcceptedSettlementInProcess)

CBP (cross border payment)

 

ACTC (AcceptedTechnicalValidation)

 

 

ACWC (AcceptedWithChange)

 

 

ACWP (AcceptedWithoutPosting)

 

 

RCVD (Received)

 

 

PDNG (Pending)

 

 

RJCT (Rejected)

 

 

CANC (Cancelled)

 

 

PATC (PartiallyAcceptedTechnicalCorrect)

 

Use the code « EXPIRED_CODE » to test an expired code.

Also, use "VALID_CLIENT_ID" as value for the "client_id" parameter of the request.

Examples:

  • PIS_VALID_CODE_RCVD_CBP (valid code for token « payment – status received - cross border payment)
  • PIS_VALID_CODE_PERIODIC_PDNG_SCT (valid code for token « periodic payment – status pending  - sepa credit transfert)

The response to this API comes in the form of a JSON object with the following structure:

{

    "access_token": "4db39597dc674268a7fa253d255c47cec7618d14ebdd433a984a7680ce0b77ad0bd76a3a55e8455b980bf41c833a03ce",

    "token_type": "Bearer",

    "expires_in": 3600,

    "refresh_token": "e3da5c9922a34d6e8fa0fa4b780acc2c1ad3a05d485f43f08580250d26a1782b0544973a64204185a9257ca07143c0bb",

    "scope": "PIS:PAYMENT_ID_RJCT_SCT"

}

This will be the access token that has a limited time validity that you have to use for the future payment requests.

Access a payment
GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}
GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/status

The different payment ids to use in the URL and in the “Consent-Id” header of these requests have this structure:

PAYMENT_ID_<payment service>_<payment status>_<payment product>

Payment service

Payment status

Payment product

  (payment)

ACCP (AcceptedCustomerProfile)

SCT (sepa credit transfert)

PERIODIC (periodic payment)

ACSC (AcceptedSettlementCompleted)

ISCT (instant sepa credit transfert)

 

ACSP (AcceptedSettlementInProcess)

CBP (cross border payment)

 

ACTC (AcceptedTechnicalValidation)

 

 

ACWC (AcceptedWithChange)

 

 

ACWP (AcceptedWithoutPosting)

 

 

RCVD (Received)

 

 

PDNG (Pending)

 

 

RJCT (Rejected)

 

 

CANC (Cancelled)

 

 

PATC (PartiallyAcceptedTechnicalCorrect)

 

Examples:

  • PAYMENT_ID_RCVD_CBP (« payment – status received - cross border payment)
  • PAYMENT_ID_PERIODIC_PDNG_SCT (« periodic payment – status pending  - sepa credit transfert)

Knowing that an access token is needed in the header of the requests, you can also find the payment Id to use in the response of the /token request.

Example:

    "scope": "PIS:PAYMENT_ID_RJCT_SCT"

Get the payment authorisations and status
GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/authorisations

This request retrieves the list of the authorizations of the payment. 

You can use the values below to test this API:

Payment service

Payment product

Payment Id

payments

sepa-credit-transfers

PAYMENT_ID_PATC_SCT

cross-border-credit-transfers

PAYMENT_ID_PATC_CBP

instant-sepa-credit-transfers

PAYMENT_ID_PATC_ISCT

periodic-payments

sepa-credit-transfers

PAYMENT_ID_PERIODIC_PATC_SCT

cross-border-credit-transfers

PAYMENT_ID_PERIODIC_PATC_CBP

instant-sepa-credit-transfers

PAYMENT_ID_PERIODIC_PATC_ISCT

 

GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{paymentAuthorisationId}

 

consentAuthorizationId

description

AUTHORIZATION_ID_FINALISED

To retrieve a authorization with the status “finalised”

AUTHORIZATION_ID_RECEIVED

To retrieve a authorization with the status “received”

AUTHORIZATION_ID_PSU_IDENTIFIED

To retrieve a authorization with the status “psuIdentified”

AUTHORIZATION_ID_PSU_AUTHENTICATED

To retrieve a authorization with the status “psuAuthenticated”

AUTHORIZATION_ID_SCA_METHOD_SELECTED

To retrieve a authorization with the status “scaMethodSelected”

AUTHORIZATION_ID_STARTED

To retrieve a consent with the status “started”

AUTHORIZATION_ID_FAILED

To retrieve a authorization with the status “failed”

AUTHORIZATION_ID_EXEMPTED

To retrieve a authorization with the status “exempted”

 

Cancel a payment
Cancel a payment (No SCA or Single SCA)
DELETE /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}

To cancel a payment with an implicit authorization, the header “TPP-Explicit-Authorisation-Preferred” of this request has to be set to “false”.

Here are the different combinations that you can use in the URL of this request:

Payment service

Payment product

payments

sepa-credit-transfers

periodic-payments

sepa-credit-transfers

 

For the payment Id parameter, here is its structure: 

PAYMENT_ID_<payment service>_<payment status>_<payment product>

Payment service

Payment status

Payment product

  (payment)

ACCP (AcceptedCustomerProfile)

SCT (sepa credit transfert)

PERIODIC (periodic payment)

ACSC (AcceptedSettlementCompleted)

 

 

ACSP (AcceptedSettlementInProcess)

 

 

ACTC (AcceptedTechnicalValidation)

 

 

ACWC (AcceptedWithChange)

 

 

ACWP (AcceptedWithoutPosting)

 

 

RCVD (Received)

 

 

PDNG (Pending)

 

 

RJCT (Rejected)

 

 

CANC (Cancelled)

 

 

PATC (PartiallyAcceptedTechnicalCorrect)

 

Examples:

  • PAYMENT_ID_RCVD_CBP (« payment – status received - cross border payment)
  • PAYMENT_ID_PERIODIC_PDNG_SCT (« periodic payment – status pending  - sepa credit transfert)
 
Authorize the cancellation of a payment

The authorisation workflow implements the BerlinGroup redirect scenario using OAuth2 SCA Protocol.

The sandbox offers the possibility to simulate the different authentications scenarios (see the table below) using the following page:

https://xs2a-sandbox.comdirect.de/public/berlingroup/cancel/authorize?scope=PIS:PAYMENT_ID_RCVD_SCT&client_id=VALID_CLIENT_ID&state=test&redirect_uri=http://localhost&code_challenge=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk&response_type=code&code_challenge_method=S256

 Authorize case

 Description

 LOGIN_CANCEL

 If the login phase was cancelled by the PSU

 LOGIN_TIMEOUT

 If the login phase encountered a timeout

 LOGIN_OTHER_ERROR

 If another error occurred during the login phase

 LOGIN_REQUEST_REJECTED

 If the login phase was rejected

 BAD_PASSWORD_LOGIN

 If an error occurred during the login phase with a bad password

 UNKNOWN_LOGIN

 If an error occurred during the login phase with an unknown login

 SCA_OK

 To get a successful authorization

 SCA_EXEMPTED

 If the SCA phase was exempted

 SCA_CANCEL

 If the SCA phase was cancelled by the PSU

 SCA_TIMEOUT

 If the SCA phase encountered a timeout

 SCA_OTHER_ERROR

 If another error occurred during the SCA phase

 SCA_NOK

 If the SCA phase did not succeed

 SCA_REQUEST_REJECTED

 If the SCA phase was rejected

 SCA_INTERNAL_ERROR

 If an internal error occurred

 
Get the payment cancellation authorisations and status
GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations

This request retrieves the list of the authorizations of the cancellation of a payment. 

You can use the values below to test this API:

Payment service

Payment product

Payment Id

payments

sepa-credit-transfers

PAYMENT_ID_PATC_SCT

periodic-payments

sepa-credit-transfers

PAYMENT_ID_PERIODIC_PATC_SCT

 

GET /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations/{paymentAuthorisationId}

 

consentAuthorizationId

description

AUTHORIZATION_ID_FINALISED

To retrieve a authorization with the status “finalised”

AUTHORIZATION_ID_RECEIVED

To retrieve a authorization with the status “received”

AUTHORIZATION_ID_PSU_IDENTIFIED

To retrieve a authorization with the status “psuIdentified”

AUTHORIZATION_ID_PSU_AUTHENTICATED

To retrieve a authorization with the status “psuAuthenticated”

AUTHORIZATION_ID_SCA_METHOD_SELECTED

To retrieve a authorization with the status “scaMethodSelected”

AUTHORIZATION_ID_STARTED

To retrieve a consent with the status “started”

AUTHORIZATION_ID_FAILED

To retrieve a authorization with the status “failed”

AUTHORIZATION_ID_EXEMPTED

To retrieve a authorization with the status “exempted”

 
 
Funds confirmation
POST /berlingroup/v1/funds-confirmations

This request checks if funds are available for an account and an amount.

The values below allow you performing the different scenario cases:

IBAN

Amount on the account

Overdraft of the account

Currency

PIIS Consent existence

FR8230066631856742938741993

150,02

100

EUR

yes

FR7630001007941234567890185

50

100

EUR

no

FR8991440686040634995710135

150,02

100

XXX (multicurrency account)

yes

Note that for the multicurrency account, its currency is optional in the body of the request.