Guides

Consents

The Consent Service is used to create and manage consents for accessing account data in the Account Information Service (AIS). A consent is an object that holds information about what permissions a PSU has given you to fetch its account information from a particular bank. This guide shows the steps for creating a consent and authorizing it through the various SCA flows.

For requests to the Consent Service API, you need an access token with scope accountinformation corporate.

Endpoint

POST /psd2/consent/v1/consents

http

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`TPP-Redirect-Preferred`	boolean	Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

Request Body

Name	Type	Description
`access`	object	Requested access services for a consent.
`combinedServiceIndicator`	boolean	Indicates that the Payment Initiation Service (PIS) will be addressed in the same session.
`frequencyPerDay`	integer	The number of times per day the TPP may access the account data without PSU interaction. For one-off access, this attribute is set to “1”. If not otherwise agreed bilaterally between TPP and bank, the frequency is less equal to 4.
`recurringIndicator`	boolean	Indicates that access to the data should be recurring when set to `true`.
`validUntil`	string(date)	The end date of the consent in ISO 8601 format, e.g. 2025-10-31.

curl -X POST "https://api.openbankingplatform.com/psd2/consent/v1/consents" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 8ef6348b-3f9f-4e1c-a768-fc586af7badf" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "TPP-Redirect-Preferred: false" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -d '{
    "access": {},
    "combinedServiceIndicator": false,
    "frequencyPerDay": 4,
    "recurringIndicator": true,
    "validUntil": "2099-12-31"
  }'

bash

Response

{
    "consentStatus": "received",
    "consentId": "70c6d203-e1d1-43ff-9e42-07e5dda640ba",
    "scaMethods": [
        {
            "authenticationType": "PUSH_OTP",
            "authenticationMethodId": "mbid",
            "name": "Mobilt BankID"
        },
        {
            "authenticationType": "CHIP_OTP",
            "authenticationMethodId": "mbid_same_device",
            "name": "Mobile BankID on this device"
        },
        {
            "authenticationType": "PHOTO_OTP",
            "authenticationMethodId": "mbid_animated_qr_image",
            "name": "Mobile BankID on another device"
        }
    ],
    "_links": {
        "self": {
            "href": "/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba"
        },
        "status": {
            "href": "/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/status"
        },
        "startAuthorisation": {
            "href": "/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/authorisations"
        }
    }
}

json

The next step is to create an authorisation process for this consent. The response will provide a list of available SCA methods for the specified bank.

Endpoint

POST /psd2/consent/v1/consents/{consentId}/authorisations

http

Path Parameters

Name	Type	Description
`consentId`	string	The ID of the consent that was created.

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`TPP-Redirect-Preferred`	boolean	Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

curl -X POST "https://api.openbankingplatform.com/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/authorisations" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 10d168c9-4813-4f6c-8aea-e6250133cf37" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "TPP-Redirect-Preferred: false" \
  -H "PSU-IP-Address: 152.120.171.187"

bash

Response

{
    "authorisationId": "8615ab1a-aab3-4619-ba4a-e627968fc634",
    "scaMethods": [
        {
            "authenticationType": "PUSH_OTP",
            "authenticationMethodId": "mbid",
            "name": "Mobilt BankID"
        },
        {
            "authenticationType": "CHIP_OTP",
            "authenticationMethodId": "mbid_same_device",
            "name": "Mobile BankID on this device"
        },
        {
            "authenticationType": "PHOTO_OTP",
            "authenticationMethodId": "mbid_animated_qr_image",
            "name": "Mobile BankID on another device"
        }
    ],
    "scaStatus": "received"
}

json

This request triggers the authentication flow. Here, you select the most appropriate SCA method for the PSU's context and initiate the authentication process. This is done by taking the authenticationMethodId of an SCA method listed in the previous step and including it in the request body. For example, if the bank supports Animated QR, the response from the previous step will include an element with authenticationMethodId mbid_animated_qr_image or mbid_animated_qr_token. This authenticationMethodId should be used if the authentication is to be performed on another device, while mbid_same_device (or mbid if not available) should be used if the authentication is to be performed on the same device.

Endpoint

PUT /psd2/consent/v1/consents/{consentId}/authorisations/{authorisationId}

http

Path Parameters

Name	Type	Description
`consentId`	string	The ID of the consent that was created.
`authorisationId`	string	The ID of the authorisation process that was created.

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`TPP-Redirect-Preferred`	boolean	Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

Request Body

Name	Type	Description
`authenticationMethodId`	string	The ID of the authentication method provided by the bank.

curl -X PUT "https://api.openbankingplatform.com/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/authorisations/8615ab1a-aab3-4619-ba4a-e627968fc634" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 07a57f41-3d89-45cc-b251-e04be8445660" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "TPP-Redirect-Preferred: false" \
  -H "PSU-IP-Address: 152.120.171.187" \
  -d '{
    "authenticationMethodId": "mbid_animated_qr_token"
    }'

bash

The first thing we need to check in the response is the SCA flow used by the bank (Decoupled or Redirect), which will be extracted from the response header aspsp-sca-approach. The response values we are interested in depend on whether we get a Decoupled or Redirect flow.

3.1. Decoupled Flow

Response Headers

aspsp-sca-approach: "DECOUPLED"

json

If the aspsp-sca-approach is DECOUPLED, the PSU will authenticate via a separate channel. As the TPP, you need to present the correct interface to the PSU.

If authenticationMethodId is mbid or mbid_same_device:

These methods launch the BankID app on the same device, meaning that you need to generate the bankIdLink. To do this, you first need to get the autoStartToken:

Response

{
    "chosenScaMethod": {
        "authenticationType": "PUSH_OTP",
        "authenticationMethodId": "mbid",
        "name": "Mobilt BankID"
    },
    "_links": {
        "scaStatus": {
            "href": "/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/authorisations/8615ab1a-aab3-4619-ba4a-e627968fc634"
        }
    },
    "scaStatus": "started",
    "challengeData": {
        "data": [
            "0a5f9137-7cb2-4d2f-b762-bfab4ad9d35f"
        ]
    }
}

json

Once you have the autoStartToken, you can construct the the full QR code like this:

bankIdLink: https://app.bankid.com/?autostarttoken={autoStartToken}&redirect={redirectUriAfterDecoupledAuthentication}

text

If your PSUs only use desktop, set {redirectUriAfterDecoupledAuthentication} to null:

bankIdLink: https://app.bankid.com/?autostarttoken=0a5f9137-7cb2-4d2f-b762-bfab4ad9d35f&redirect=null

text

If your PSUs are on mobile or mixed device types, set {redirectUriAfterDecoupledAuthentication} to the URI that the PSU should be redirected to after authenticating:

bankIdLink: https://app.bankid.com/?autostarttoken=0a5f9137-7cb2-4d2f-b762-bfab4ad9d35f&redirect=https://exampleapplication.com/callback

text

If authenticationMethodId is mbid_animated_qr_image:

With this method, you need to dispay the Base64encoded PNG animatedQRImage and instruct the PSU to scan it in the Mobile BankID app. The image is only valid for 1 second, and must be refreshed by calling Get Consent Authorisation SCA Status repeatedly at least every second but no more than every 500ms.

Response

{
    "chosenScaMethod": {
        "authenticationType": "PHOTO_OTP",
        "authenticationMethodId": "mbid_animated_qr_image",
        "name": "Mobile BankID on another device"
    },
    "_links": {
        "scaStatus": {
            "href": "/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/authorisations/8615ab1a-aab3-4619-ba4a-e627968fc634"
        }
    },
    "psuMessage": "Please confirm with your bank app.",
    "scaStatus": "started",
    "challengeData": {
        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
    }
}

json

If authenticationMethodId is mbid_animated_qr_token:

With this method, you need to generate your own QR image from the token animatedQRToken and instruct the PSU to scan it in the Mobile BankID app. The token is only valid for 1 second, and must be refreshed by calling Get Consent Authorisation SCA Status repeatedly at least every second but no more than every 500ms.

Response

{
    "chosenScaMethod": {
        "authenticationType": "PHOTO_OTP",
        "authenticationMethodId": "mbid_animated_qr_token",
        "name": "Mobile BankID on another device"
    },
    "_links": {
        "scaStatus": {
            "href": "/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/authorisations/8615ab1a-aab3-4619-ba4a-e627968fc634"
        }
    },
    "scaStatus": "started",
    "challengeData": {
        "data": [
            "bankid.dXRvS2VuU3RyaW5nMTIz"
        ]
    }
}

json

3.2. Redirect Flow

Response Headers

aspsp-sca-approach: "REDIRECT"

json

If the aspsp-sca-approach is REDIRECT, the PSU will authenticate via the bank’s external authentication page. As the TPP, you need to extract the redirect link from our OAuth server and replace the placeholders with the relevant values.

Response

{
    "chosenScaMethod": {
        "authenticationType": "PUSH_OTP",
        "authenticationMethodId": "mbid",
        "name": "Mobilt BankID"
    },
    "_links": {
        "scaStatus": {
            "href": "/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/authorisations/8615ab1a-aab3-4619-ba4a-e627968fc634"
        },
        "scaOAuth": {
            "href": "https://auth.openbankingplatform.com/connect/authorize?client_id=[CLIENT_ID]&scope=accountinformation%20corporate&response_type=code&redirect_uri=[TPP_REDIRECT_URI]&state=[TPP_STATE]&acr_values=idp:ESSESESS%20consentId:70c6d203-e1d1-43ff-9e42-07e5dda640ba%20consentAuthorisationId:8615ab1a-aab3-4619-ba4a-e627968fc634"
        }
    },
    "psuMessage": "Please confirm with your bank app.",
    "scaStatus": "started"
}

json

Replace the following placeholders in redirectLinkToBank in the following way:

[CLIENT_ID] should be replaced by your client_id.

[TPP_REDIRECT_URI] is the URI you want us to redirect to after we get confirmation from the bank that the PSU has authenticated. This URI has to be whitelisted for your application in the Developer Portal.

[TPP_STATE] is a convenience field for you to put in a value of your choice that identifies this session. It's important that you can identify the correct session after the PSU is redirected back again.

We now have what we need to let the PSU authenticate. Redirect the PSU to redirectLinkToBank. When the PSU has authenticated, the bank will route the PSU back to your [TPP_REDIRECT_URI]. Once there, you extract the URL parameters codeand scope.

redirectLinkToBank: https://www.openpayments.io/?code=SplxlOBeZQQYbYS6WxSbIA&scope=accountinformation%20corporate&state=sessionxyz

text

To finalise the consent, you make the following request.

Endpoint

POST /connect/token

http

Request Headers

Name	Type	Description
`Accept`	string	Specifies the desired response format.
`Content-Type`	string	Specifies the request format.
`X-ConsentAuthorisationId`	string	The ID of the authorisation process that was created.
`X-ConsentId`	string	The ID of the consent that was created.

Request Body

Name	Type	Description
`client_id`	string	The Client ID of the application you created in the Developer Portal.
`client_secret`	string	The secret key that was generated when the application was created.
`code`	string	The authorisation code received from the authorisation server after the PSU has authenticated at the bank. This code is exchanged for an access token.
`redirect_uri`	string(uri)	The URI to which the PSU was redirected after authorisation. It must exactly match the redirect URI used in the initial authorisation request.
`scope`	string	Specifies the level of access requested. It is a space-separated string combining API scopes (e.g. `accountinformation`) and PSU context scopes (e.g. `corporate`).
`grant_type`	string(enum)	Specifies the OAuth 2.0 grant flow to use. For redirect-based access tokens, this should be `authorization_code`.

curl -X POST "https://auth.openbankingplatform.com/connect/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-ConsentAuthorisationId: 8615ab1a-aab3-4619-ba4a-e627968fc634" \
  -H "X-ConsentId: 70c6d203-e1d1-43ff-9e42-07e5dda640ba" \
  -d "client_id=555510ad-da62-4e6d-80b8-e18967eabf0b" \
  -d "client_secret=joiaHR0cHM6Ly9hdXRoLm9wZW5iYW5raW5ncGxhdGZvcm0uY29tIiwiYXVkIjpb" \
  -d "code=SplxlOBeZQQYbYS6WxSbIA" \
  -d "redirect_uri=https://exampleapplication.com/callback" \
  -d "scope=accountinformation corporate" \
  -d "grant_type=authorization_code"

bash

Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
    "expires_in": 3600,
    "token_type": "Bearer", 
    "scope": "accountinformation corporate"
}

json

If you receive an access token it means that the request was successful. Note: This access token does not need to be stored or used in any subsequent calls.

Regardless of the method, you can use the scaStatus link from the response to poll the Get Consent Authorisation SCA Status call until scaStatus becomes finalised or failed.

Endpoint

GET /psd2/consent/v1/consents/{consentId}/authorisations/{authorisationId}

http

Path Parameters

Name	Type	Description
`consentId`	string	The ID of the consent that was created.
`authorisationId`	string	The ID of the authorisation process that was created.

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`TPP-Redirect-Preferred`	boolean	Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

curl -X GET "https://api.openbankingplatform.com/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/authorisations/8615ab1a-aab3-4619-ba4a-e627968fc634" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 7be49d26-51c8-4946-b263-741a4d05cd6a" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "TPP-Redirect-Preferred: false" \
  -H "PSU-IP-Address: 152.120.171.187"

bash

Response

{
    "scaStatus": "finalised"
}

json

Lastly, we check the status of the consent by polling the Get Consent Status endpoint.

Endpoint

GET /psd2/consent/v1/consents/{consentId}/status

http

Path Parameters

Name	Type	Description
`consentId`	string(uuid)	The ID of the consent that was created.

Request Headers

Name	Type	Description
`X-Request-ID`	string(uuid)	The ID of the request, unique to the call, as determined by the initiating party.
`X-BicFi`	string	The BIC of the bank to which the request is addressed.
`PSU-ID`	string	The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
`PSU-Corporate-ID`	string	The Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
`TPP-Redirect-Preferred`	boolean	Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types.
`PSU-IP-Address`	string(ipv4)	The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.

curl -X GET "https://api.openbankingplatform.com/psd2/consent/v1/consents/70c6d203-e1d1-43ff-9e42-07e5dda640ba/status" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 5a441866-935b-41e9-ba3a-2952a351b706" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "TPP-Redirect-Preferred: false" \
  -H "PSU-IP-Address: 152.120.171.187"

bash

Response

{
    "consentStatus": "valid"
}

json

Note: Payments can have a number of different statuses. Here, we want to check if the consent was rejected, in which case consentStatus would have the value rejected. If not, then we are done.

Banks Account Information

​1. Create Consent

​Endpoint

​Request Headers

​Request Body

​Response

​2. Start Consent Authorisation Process

​Endpoint

​Path Parameters

​Request Headers

​Response

​3. Start Consent Authorisation

​Endpoint

​Path Parameters

​Request Headers

​Request Body

​3.1. Decoupled Flow

​Response Headers

​Response

​Response

​Response

​3.2. Redirect Flow

​Response Headers

​Response

​3.2.1 Activate OAuth Consent Authorisation

​Endpoint

​Request Headers

​Request Body

​Response

​4. Get Consent Authorisation SCA Status

​Endpoint

​Path Parameters

​Request Headers

​Response

​5. Get Consent Status

​Endpoint

​Path Parameters

​Request Headers

​Response

1. Create Consent

Endpoint

Request Headers

Request Body

Response

2. Start Consent Authorisation Process

Endpoint

Path Parameters

Request Headers

Response

3. Start Consent Authorisation

Endpoint

Path Parameters

Request Headers

Request Body

3.1. Decoupled Flow

Response Headers

Response

Response

Response

3.2. Redirect Flow

Response Headers

Response

3.2.1 Activate OAuth Consent Authorisation

Endpoint

Request Headers

Request Body

Response

4. Get Consent Authorisation SCA Status

Endpoint

Path Parameters

Request Headers

Response

5. Get Consent Status

Endpoint

Path Parameters

Request Headers

Response