🇪🇺 Berlin Group v1.3 - Create consent

POST https://open-banking-api.paysera.com/xs2a/berlin/1.3/v1/consents

This method create a consent resource, defining access rights to dedicated accounts of a given PSU-ID. These accounts are addressed explicitly in the method as parameters as a core function.

Side Effects When this consent request is a request where the "recurringIndicator" equals "true", and if it exists already a former consent for recurring access on account information for the addressed PSU, then the former consent automatically expires as soon as the new consent request is authorised by the PSU.

Optional Extension: As an option, an ASPSP might optionally accept a specific access right on the access on all PSD2 related services for all available accounts.

As another option an ASPSP might optionally also accept a command, where only access rights are inserted without mentioning the addressed account. The relation to accounts is then handled afterwards between PSU and ASPSP. This option is not supported for the Embedded SCA Approach. As a last option, an ASPSP might in addition accept a command with access rights

to see the list of available payment accounts or
to see the list of available payment accounts with balances.

Authorization

This endpoint requires mTLS (Mutual TLS) authentication using a valid QWAC certificate. Consent and payment endpoints authenticate on the certificate alone: no access token or Consent-ID header is needed.

Requirements:

Valid QWAC certificate issued by a qualified trust service provider (QTSP)
Certificate must be registered with Paysera
Certificate organization identifier must match your TPP registration in the EBA register
X-Request-ID header with a UUID on every request

Request signing: not used. This API does not read the Digest, x-jws-signature or TPP-Signature-Certificate headers — see Security.

Example (cURL):

curl -X POST https://open-banking-api.paysera.com/xs2a/berlin/1.3/v1/consents \
  --cert qwac-cert.pem \
  --key qwac-key.pem \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @request.json

For detailed authentication guide, see Authentication.

Parameters

Request Body

Request body for a consents request.

Field	Type	Required	Description
`access`	object	✓	Requested access services for a consent.
`recurringIndicator`	boolean	✓	"true", if the consent is for recurring access to the account data. "false", if the consent is for one access to the account data.
`validUntil`	string	✓	This parameter is defining a valid until date (including the mentioned date) for the requested consent. The content is the local ASPSP date in ISO-Date format, e.g. 2017-10-30. Future dates might get adjusted by ASPSP. If a maximal available date is requested, a date in far future is to be used: "9999-12-31". In both cases the consent object to be retrieved by the get consent request will contain the adjusted date.
`frequencyPerDay`	integer	✓	This field indicates the requested maximum frequency for an access without PSU involvement per day. For a one-off access, this attribute is set to "1". The frequency needs to be greater equal to one. By default the maximum is 4. For a higher limit, please contact Paysera Technical Support at tech_support@paysera.com. Account accesses beyond the consent's agreed frequency are rejected with HTTP 429 (`ACCESS_EXCEEDED`).
`combinedServiceIndicator`	boolean	✓	If "true" indicates that a payment initiation service will be addressed in the same "session".

Errors

This endpoint may return the following errors. The list is shared by every endpoint of this API, so not every code applies to every endpoint.

Every error listed below is returned with a tppMessages array. Each message has a category and a code, and may add a path (the header or field at fault) and a text.

400 - Bad Request

The request could not be understood by the server due to malformed syntax or invalid parameters.

Common error codes:

CONSENT_UNKNOWN - The consent in the Consent-ID header is unknown or cannot be used by this TPP
FORMAT_ERROR - Invalid request format or syntax, for example a malformed body field or an X-Request-ID that is not a UUID
FORMAT_INVALID - The mandatory Consent-ID header is missing
PARAMETER_NOT_SUPPORTED - Request contains unsupported parameters
PERIOD_INVALID - The requested consent validity period is outside the allowed range
SERVICE_INVALID - The addressed service is not valid for the addressed resources
SESSIONS_NOT_SUPPORTED - Combined AIS and PIS sessions (combinedServiceIndicator) are not supported

Example response:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "FORMAT_ERROR",
      "path": "X-Request-ID",
      "text": "Request ID must be a valid UUID string."
    }
  ]
}

401 - Unauthorized

The certificate, the access token or the consent could not be used to authenticate the request.

Common error codes:

CERTIFICATE_INVALID - The TPP certificate is not valid or is not registered with Paysera
CERTIFICATE_MISSING - The TPP certificate is missing in the request
CONSENT_EXPIRED - The consent has expired and can no longer be used
CONSENT_INVALID - The consent is invalid for this operation
ROLE_INVALID - The TPP certificate does not have the role this endpoint requires (AIS or PIS)
TOKEN_INVALID - The access token does not carry the scope this endpoint requires
TOKEN_EXPIRED - The access token has expired, has been revoked or could not be verified
TOKEN_UNKNOWN - The access token is unknown or invalid

Example response:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "CERTIFICATE_INVALID"
    }
  ]
}

403 - Forbidden

The TPP does not have the necessary permissions or the resource access is forbidden.

Common error codes:

CONSENT_UNKNOWN - The addressed consent is unknown to this TPP, or the TPP may not perform this consent operation
RESOURCE_UNKNOWN - The addressed resource is unknown to this TPP

Example response:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "CONSENT_UNKNOWN"
    }
  ]
}

404 - Not Found

The requested resource could not be found.

Common error codes:

RESOURCE_UNKNOWN - The addressed resource is not found or does not exist
SERVICE_INVALID - The request path does not match any endpoint of this API

Example response:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "RESOURCE_UNKNOWN"
    }
  ]
}

405 - Method Not Allowed

The HTTP method used is not allowed for this endpoint.

Common error codes:

SERVICE_INVALID - The HTTP method is not supported for this service

Example response:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "SERVICE_INVALID"
    }
  ]
}

429 - Too Many Requests

The TPP has used up the account data accesses its consent allows.

Each consent allows its agreed frequencyPerDay accesses (4 by default, or a higher value agreed with Paysera) to each account data resource per 24 hours. Requests sent with the PSU-IP-Address header under a recurring consent do not count towards the limit.

Common error codes:

ACCESS_EXCEEDED - The consent's frequencyPerDay limit for this resource has been reached

Example response:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "ACCESS_EXCEEDED"
    }
  ]
}

500 - Internal Server Error

An unexpected error occurred on the server side. This indicates a problem with the ASPSP's system. Please try again later or contact Paysera support if the issue persists.

Common error codes:

INTERNAL_SERVER_ERROR - The request could not be completed; try again later
INVALID_TPP_CONFIGURATION - The TPP's configuration at Paysera is invalid; contact Paysera support

Example response:

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "INTERNAL_SERVER_ERROR"
    }
  ]
}

Example

Request

POST https://open-banking-api.paysera.com/xs2a/berlin/1.3/v1/consents
X-Request-ID: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
Content-Type: application/json
# plus the QWAC certificate presented during the TLS handshake

Response

{
  "consentStatus": "received",
  "consentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "_links": {
    "self": {
      "href": "/xs2a/berlin/1.3/v1/consents/3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "status": {
      "href": "/xs2a/berlin/1.3/v1/consents/3fa85f64-5717-4562-b3fc-2c963f66afa6/status"
    },
    "scaStatus": {
      "href": "/xs2a/berlin/1.3/v1/consents/3fa85f64-5717-4562-b3fc-2c963f66afa6/authorisations/123auth567"
    },
    "scaOAuth": {
      "href": "/.well-known/oauth-authorization-server"
    }
  }
}

The scaOAuth link points at the OAuth 2.0 authorisation server metadata document. Read it, then send the PSU through its authorization_endpoint. Paysera does not return a scaRedirect link.

AUTHORIZATION: HTTP

REQUEST

Base URL

https://open-banking-api.paysera.com

Body REQUIRED

{
  "access": {
    "balances": [
      {
        "iban": "DE40100100103307118608"
      },
      {
        "iban": "DE02100100109307118603",
        "currency": "USD"
      },
      {
        "iban": "DE67100100101306118605"
      }
    ],
    "transactions": [
      {
        "iban": "DE40100100103307118608"
      },
      {
        "maskedPan": "123456xxxxxx1234"
      }
    ]
  },
  "recurringIndicator": "true",
  "validUntil": "2017-11-01",
  "frequencyPerDay": 4
}

RESPONSE

Created

{
  "consentStatus": "received",
  "consentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "_links": {
    "self": {
      "href": "/xs2a/berlin/1.3/v1/consents/3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "status": {
      "href": "/xs2a/berlin/1.3/v1/consents/3fa85f64-5717-4562-b3fc-2c963f66afa6/status"
    },
    "scaStatus": {
      "href": "/xs2a/berlin/1.3/v1/consents/3fa85f64-5717-4562-b3fc-2c963f66afa6/authorisations/123auth567"
    },
    "scaOAuth": {
      "href": "/.well-known/oauth-authorization-server"
    }
  }
}

Authorization​

Parameters​

Request Body​

Errors​

400 - Bad Request​

401 - Unauthorized​

403 - Forbidden​

404 - Not Found​

405 - Method Not Allowed​

429 - Too Many Requests​

500 - Internal Server Error​

Example​

Request​

Response​

AUTHORIZATION: HTTP

REQUEST

RESPONSE

Authorization

Parameters

Request Body

Errors

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

405 - Method Not Allowed

429 - Too Many Requests

500 - Internal Server Error

Example

Request

Response