Berlin Group

Yapily's knowledge article about Berlin Group Payments

While PSD2 (Payment Services Directive 2) has mandated that banks must open their systems to third-parties, and provide interfaces for them to initiate payments and retrieve account information, in the UK it is the Open Banking Implementation Entity (OBIE) that defines how banks are to provide this information securely through APIs and data structures. In order to bring some synergy across the European banks, the Berlin Group which is a pan-European initiative has implemented a common API standard called NextGenPSD2. While these efforts have greatly improved how Open Banking can be consumed in member countries, there are some differences in how you communicate to these banks.


  • In order to initiate a payment from an account from an Institution that belongs to the Berlin Group, the Payer object and all its mandatory properties are required. This currently holds true for every Institution provided by Yapily that is in Europe (not including UKI)

Note: When making a payment from an account held within the UK to an account held in Europe, the Payer object is not required since the payment is executed by an Institution that is a member of the Open Banking UK specification.

  • The payment reference unlike an Institution in order the Open Banking UK specification can be more than 18 characters.

Response Codes


Code Status Description Yapily Response
200 OK PUT, GET Response Codes. OK 200
201 CREATED POST response code where Payment Initiation or Consent Request was correctly performed. 201
202 ACCEPTED DELETE response code, where a payment resource can be cancelled in general, but where a cancellation authorisation is needed in addition. 200
204 NO_CONTENT DELETE response code where a consent resource was successfully deleted. The code indicates that the request was performed, but no content was returned 200
400 FORMAT_ERROR Format of certain request fields are not matching the XS2A requirements.
400 PARAMETER_NOT_CONSISTENT Parameters submitted by TPP are not consistent. This applies only for query parameters.
400 PARAMETER_NOT_SUPPORTED The parameter is not supported by the API provider. This code should only be used for parameters that are described as "optional if supported by API provider.
400 PERIOD_INVALID Requested time period out of bound.
400 RESOURCE_BLOCKED The addressed resource is not addressable by this request, since it is blocked e.g. by a grouping in a signing basket.
400 SCA_INVALID Method Application on authorisation resource (e.g. Confirmation Request) blocked since SCA status of the resource equals "failed".
400 SCA_METHOD_UNKNOWN Addressed SCA method in the Authentication Method Select Request is unknown or cannot be matched by the ASPSP with the PSU.
400 SERVICE_INVALID The addressed service is not valid for the addressed resources or the submitted data.
400 TIMESTAMP_INVALID Timestamp not in accepted time period.
401 CERTIFICATE_BLOCKED Signature/corporate seal certificate has been blocked by the ASPSP or the related NCA. 401
401 CERTIFICATE_EXPIRED Signature/corporate seal certificate is expired. 401
401 CERTIFICATE_INVALID The contents of the signature/corporate seal certificate are not matching PSD2 general PSD2 or attribute requirements. 401
401 CERTIFICATE_MISSING Signature/corporate seal certificate was not available in the request but is mandated for the corresponding. 401
401 CERTIFICATE_REVOKED Signature/corporate seal certificate has been revoked by QSTP. 401
401 CONSENT_INVALID The consent was created by this TPP but is not valid for the addressed service/resource. 401
401 CONSENT_EXPIRED The consent was created by this TPP but has expired and needs to be renewed. 401
401 CORPORATE_ID_INVALID The PSU-Corporate-ID cannot be matched by the addressed ASPSP. 401
401 PSU_CREDENTIALS_INVALID The PSU-ID cannot be matched by the addressed ASPSP or is blocked, or a password resp. OTP was not correct. Additional information might be added. 401
401 ROLE_INVALID The TPP does not have the correct PSD2 role to access this service. 401
401 SIGNATURE_INVALID Application layer eIDAS Signature for TPP authentication is not correct. 401
401 SIGNATURE_MISSING Application layer eIDAS Signature for TPP authentication is mandated by the ASPSP but is missing. 401
401 TOKEN_UNKNOWN The OAuth2 token cannot be matched by the ASPSP relative to the TPP. 401
401 TOKEN_INVALID The OAuth2 token is associated to the TPP but is not valid for the addressed service/resource. 401
401 TOKEN_EXPIRED The OAuth2 token is associated to the TPP but has expired and needs to be renewed. 401
403 CONSENT_UNKNOWN The Consent-ID cannot be matched by the ASPSP relative to the TPP. 403
403 RESOURCE_EXPIRED The addressed resource is associated with the TPP but has expired, not addressable anymore. 403
403 SERVICE_BLOCKED This service is not reachable for the addressed PSU due to a channel independent blocking by the ASPSP 403
404 RESOURCE_UNKNOWN The addressed resource is unknown relative to the TPP.
409 STATUS_INVALID The addressed resource does not allow additional authorisation.
500 INTERNAL SERVER ERROR Internal server error occurred. 424
501 SERVICE UNAVAILABLE The ASPSP server is currently unavailable. Generally, this is a temporary state. 424


Code Status Description
400 EXECUTION_DATE_INVALID The requested execution date is not a valid execution date for the ASPSP.
400 PAYMENT_FAILED The payment initiation POST request failed during the initial process. Additional information may be provided by the ASPSP.
401 REQUIRED_KID_MISSING The payment initiation has failed due to a missing KID.
403 PRODUCT_INVALID The addressed payment product is not available for the PSU .
404 PRODUCT_UNKNOWN The addressed payment product is not supported by the ASPSP.
405 CANCELLATION_INVALID The addressed payment is not cancellable e.g. due to cut off time passed or legal constraints.


Code Status Description
400 SESSIONS_NOT_SUPPORTED The combined service flag may not be used with this ASPSP.
401 CONSENT_INVALID The consent definition is not complete or invalid. In case of being not complete, the bank is not supporting a completion of the consent towards the PSU.
406 REQUESTED_FORMATS _INVALID The requested formats in the Accept header entry are not matching the formats offered by the ASPSP.
429 ACCESS_EXCEEDED The access on the account has been exceeding the consented multiplicity without PSU involvement per day.