--- swagger: "2.0" info: title: PSD2 BG Consent Information Service API (CIS) description: |- Consents and consent management are core concepts of the PSD2 solution, and are defined with dedicated API endpoints in the Berlin Group specification. The general mechanism for validating and authorizing consents is through a Redirect SCA Approach - utilising implicit start of the authentication process. This is described in [NextGenPSD2 XS2A Framework - Implementation Guide, Section 6.1.1.1, Page 101](https://docs.wixstatic.com/ugd/c2914b_bec5f9d0d3c94cfca2ad1b9da36dc752.pdf). Access to the Consent Information Service API is controlled through the general onboarding/enrollment flow. I.e. the API is only accessible to valid TPPs, who have completed the enrollment in order to upload and verify their qualified certificates. By accessing the API, you confirm that you already have status as an authorized TPP - or (for sandbox access only) that your application has been submitted to a local NCA and is pending approval. Only TPPs who can document their authorization status are elegible for support. The CIS API is part of the general PSD2 XS2A implementation and works in the same security context. In addition to the information contained below, all communication, headers and additional steps adhere to the general [security model and flows](https://apiportal.prod.bec.dk/openbanking/sandbox/security-model-and-flows). Refer to this link for up to date information on required security headers. At present, consent API only applies to Account Information APIs (AIS) and only supports global consent to all PSD2 accounts. The API is implemented against [Berlin Group XS2A version 1.3](https://www.berlin-group.org/psd2-access-to-bank-accounts). **Note about this version** This version of the AIS API now also supports testing of security, consent and SCA flows in sandbox with full security context. * The sandbox API works on (stateless) mocked account data, while SCA, security and consent flows are identical to production. * The security model for TPP enrollment and PSU authentication/authorization is implemented and enforced for **both** production and sandbox API **Access to API Endpoints** **Production and sandbox access:** Prior to calling the API the TPP must complete the (one-time) process for [Onboarding](https://apiportal.prod.bec.dk/openbanking/sandbox/start) on a per-bank basis. Separate API URL/host endpoints are required for each bank under the BEC Umbrella. Consult the [Environments section](https://apiportal.prod.bec.dk/openbanking/sandbox/environments) for information on URL schemas in production and sandbox environments. See list of included ASPSPs and their corresponding urls by following [this link](https://apiportal.prod.bec.dk/openbanking/sandbox/included-aspsps). The X-IBM-Client-Id attribute is not required in this version. version: 1.0.3 contact: name: BEC PSD2 Support url: https://apiportal.prod.bec.dk/openbanking/sandbox/ email: psd2.support@bec.dk license: name: The API is made available to TPPs who have been authorized for the relevant roles by a NCA - or to TPPs applying to be authorized at a NCA with approval pending. x-ibm-name: psd2-bg-consent-api host: api.sandbox.openbanking.bec.dk basePath: /bg/openbanking/v1 schemes: - https tags: - name: Berlin Group Account Information Consent API (CIS) description: |- The Consents API contains the following services: * Request consent creation * Get status of consent * Fetch an already issued consent * Delete a consent paths: /consents: post: tags: - Berlin Group Account Information Consent API (CIS) summary: Create consent description: Called by TPP to request a consent from PSU to access account information services at the ASPSP on behalf of the PSU. The implementation is based on Berlin Group NextGenPSD2 XS2A Framework. Currently only global consent to all accounts is supported. operationId: createUsingPOST produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - name: TPP-Redirect-URI in: header type: string format: uri required: true description: | URI to which the PSU is redirected after SCA. - name: TPP-Nok-Redirect-URI in: header type: string format: uri description: | URI to which the PSU is redirected in case of a negative result of the SCA. required: false - name: TPP-ID in: header type: string description: | Client ID of the TPP in the ASPSP client interface (elaborated under the description of general security model). required: false - in: body name: consent description: Payload for consent creation required: true schema: $ref: '#/definitions/ConsentRequest' responses: 201: description: Created schema: $ref: '#/definitions/ConsentResponse' 400: description: | Bad request. For example: Timestamp not in accepted time period. schema: $ref: '#/definitions/TppMessages' 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' 404: description: | Not found. For example: The addressed resource is unknown relative to the TPP. schema: $ref: '#/definitions/TppMessages' /consents/{consentId}/status: get: tags: - Berlin Group Account Information Consent API (CIS) summary: Can check the status of an account information consent resource. operationId: getStatusUsingGET produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - in: path name: consentId type: string required: true description: | The ID of the content resource (as returned by a previous Post operation) responses: 200: description: OK schema: $ref: '#/definitions/ConsentResponse' 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' 404: description: | Not found. For example: The addressed resource is unknown relative to the TPP. schema: $ref: '#/definitions/TppMessages' /consents/{consentId}: get: tags: - Berlin Group Account Information Consent API (CIS) summary: Returns the content of an account information consent object. This is returning the data for the TPP especially in cases, where the consent was directly managed between ASPSP and PSU e.g. in a re-direct SCA Approach. description: Query status of an already created consent. operationId: readUsingGET produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - in: path name: consentId type: string required: true description: | The ID of the content resource (as returned by a previous Post operation) responses: 200: description: OK schema: $ref: '#/definitions/Consent' 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' 404: description: | Not found. For example: The addressed resource is unknown relative to the TPP. schema: $ref: '#/definitions/TppMessages' delete: tags: - Berlin Group Account Information Consent API (CIS) summary: The TPP can delete an account information consent object if needed. operationId: deleteUsingDELETE produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - in: path name: consentId type: string required: true description: | The ID of the content resource (as returned by a previous Post operation) responses: 200: description: OK 204: description: No Content 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' /consents/{consentId}/authorisations/{authorisationId}: get: tags: - Berlin Group Account Information Consent API (CIS) summary: The TPP get the information of authorisation related to the consent operationId: getAuthorisationUsingGET produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - in: path name: consentId type: string required: true description: | The ID of the content resource (as returned by a previous Post operation) - name: authorisationId in: path description: Authorisation identifier returned upon the consent creation. required: true type: string responses: 200: description: OK schema: $ref: '#/definitions/Authorisation' 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' 404: description: | Not found. For example: The addressed resource is unknown relative to the TPP. schema: $ref: '#/definitions/TppMessages' /consents/confirmation-of-funds: post: tags: - Berlin Group Account Information Consent API (CIS) summary: Creates confirmation of funds consent resource at the ASPSP regarding access to accounts specified in this request. operationId: createUsingPOST_1 consumes: - application/json produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - name: TPP-Redirect-URI in: header type: string format: uri required: true description: | URI to which the PSU is redirected after SCA. - name: TPP-Nok-Redirect-URI in: header type: string format: uri description: | URI to which the PSU is redirected in case of a negative result of the SCA. required: false - in: body name: consent description: Payload for confirmation of funds consent creation required: true schema: $ref: '#/definitions/FcsConsent' responses: 201: description: Created schema: $ref: '#/definitions/ConsentResponse' 400: description: | Bad request. For example: Timestamp not in accepted time period. schema: $ref: '#/definitions/TppMessages' 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' 404: description: | Not found. For example: The addressed resource is unknown relative to the TPP. schema: $ref: '#/definitions/TppMessages' /consents/confirmation-of-funds/{consentId}: get: tags: - Berlin Group Consent Information summary: Returns a confirmation of funds consent object. This is returning the data for the TPP. description: Query status of an already created consent. operationId: readUsingGET_1 produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - in: path name: consentId type: string required: true description: | The ID of the confirmation of funds consent resource (as returned by a previous Post operation) responses: 200: description: OK schema: $ref: '#/definitions/FcsConsent' 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' 404: description: | Not found. For example: The addressed resource is unknown relative to the TPP. schema: $ref: '#/definitions/TppMessages' /consents/confirmation-of-funds/{consentId}/authorisations/{authorisationId}: get: tags: - Berlin Group Consent Information summary: The TPP get the information of authorisation related to the confirmation of funds consent operationId: getAuthorisationUsingGET_1 produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - in: path name: consentId type: string required: true description: | The ID of the content resource (as returned by a previous Post operation) - name: authorisationId in: path description: Authorisation identifier returned upon the consent creation. required: true type: string responses: 200: description: OK schema: $ref: '#/definitions/Authorisation' 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' 404: description: | Not found. For example: The addressed resource is unknown relative to the TPP. schema: $ref: '#/definitions/TppMessages' /consents/confirmation-of-funds/{consentId}/status: get: tags: - Berlin Group Consent Information summary: Can check the status of a confirmation of funds consent resource. operationId: getStatusUsingGET_1 produces: - application/json parameters: - name: X-Request-ID in: header type: string format: uuid required: true description: | ID of the request (in UUID format), unique to the call (generated by the initiating party, who must ensure uniqueness). - in: path name: consentId type: string required: true description: | The ID of the content resource (as returned by a previous Post operation) responses: 200: description: OK schema: $ref: '#/definitions/ConsentResponse' 401: description: | Unauthorized. For example: The consent was created by this TPP but has expired and needs to be renewed. schema: $ref: '#/definitions/TppMessages' 403: description: | Forbidden. For example: The addressed resource is associated with the TPP but has expired, not addressable anymore. schema: $ref: '#/definitions/TppMessages' 404: description: | Not found. For example: The addressed resource is unknown relative to the TPP. schema: $ref: '#/definitions/TppMessages' definitions: Account: type: object properties: bban: type: string example: 01234567890123 description: |- BBAN (Basic Bank Account Number) up to 14 digits forming the account number used to identify an account intranationally\nPattern: [0-9]{1,14} maxLength: 14 iban: type: string example: DK9520000123456789 description: |- IBAN (International Bank Account Number) up to 34 alphanumeric characters consisting of a two letter country code, a two digit checksum, and a BBAN\nPattern: [A-Z]{2}[0-9]{2}[A-Z0-9]{1-30} maxLength: 34 title: Account description: Account representation. Either iban or bban MUST be filled out AccountLinks: type: object properties: accounts: $ref: '#/definitions/Link' title: AccountLinks description: This is a collection of links to other endpoints where the consent can be used. Authorisation: type: object properties: scaStatus: type: string enum: - CREATED - PENDING - APPROVED - REJECTED title: Authorisation ConsentRequest: type: object properties: access: $ref: '#/definitions/ScimAccountAccess' frequencyPerDay: type: integer format: int32 description: The maximum number of request, this consent can be used for per day, this is default 4. recurringIndicator: type: boolean description: true if the consent should be authorised for multiple requests, false of the consent should be authorised for only one request validUntil: type: string example: "2019-10-30T00:00:00.000Z" description: | The date of when the consent should expire in ISODate Format. If a maximal available date is requested, a date in far future is to be used: '9999-12-31'. title: ConsentRequest description: ConsentRequest Consent: type: object properties: _links: $ref: '#/definitions/AccountLinks' access: $ref: '#/definitions/ScimAccountAccess' consentId: type: string description: Identification of the consent resource as it is used in the API structure consentStatus: type: string description: Authentication status of the consent frequencyPerDay: type: integer format: int32 description: The maximum number of request, this consent can be used for per day, this is default 4. lastActionDate: type: string description: This date is containing the date of the last action on the consent object either through the XS2A interface or the PSU/ASPSP interface having an impact on the status. recurringIndicator: type: boolean description: true if the consent should be authorised for multiple requests, false of the consent should be authorised for only one request validUntil: type: string example: "2019-10-30T00:00:00.000Z" description: | The date of when the consent should expire in ISODate Format. If a maximal available date is requested, a date in far future is to be used: '9999-12-31'. title: Consent description: Consent ConsentLinks: type: object properties: scaRedirect: description: The link to retrieve the transaction status of the consent request $ref: '#/definitions/Link' scaStatus: description: The link to retrieve the scaStatus of the corresponding authorisation subresource. $ref: '#/definitions/Link' self: description: The link to the Consent resource created by this request. This link can be used to retrieve the resource data. $ref: '#/definitions/Link' status: description: The URL which the PSu must be redirected to in order to perform the SCA $ref: '#/definitions/Link' title: ConsentLinks description: A collection of links ConsentResponse: type: object properties: _links: $ref: '#/definitions/ConsentLinks' consentId: type: string consentStatus: type: string title: ConsentResponse description: Create and status consent response FcsConsent: type: object properties: account: $ref: '#/definitions/Account' consentStatus: type: string description: Authentication status of the consent enum: - RECEIVED - VALID - REJECTED - TERMTPP - REVOKPSU registrationInformation: type: string description: Additional description title: FcsConsent Link: type: object properties: href: type: string example: /v1/link/to/some/resource description: URL pointing to a resource title: Link description: Link to a resource ScimAccountAccess: type: object properties: allPsd2: type: string example: allAccounts enum: - allAccounts - allAccountsWithOwnerName title: ScimAccountAccess description: Requested access services TppMessage: type: object properties: category: type: string example: ERROR description: Error category enum: - ERROR - WARNING code: type: string example: CONSENT_UNKNOWN description: Message code to explain the nature of the underlying error. enum: - FORMAT_ERROR - SERVICE_INVALID - SERVICE_BLOCKED - CONSENT_UNKNOWN - CONSENT_INVALID - CONSENT_EXPIRED - '...' text: type: string example: Product invalid description: Detailed message description title: TppMessage description: TPP Message Information TppMessages: type: object properties: tppMessages: type: array items: $ref: '#/definitions/TppMessage' title: TppMessages description: Messages to the TPP on operational issues. x-ibm-configuration: testable: false enforced: true phase: realized x-ibm-endpoints: - endpointUrl: https://api.sandbox.openbanking.bec.dk type: - development ...