Guides

​Authorisations

This guide shows how to perform PSU authorisation when interacting with our APIs. It covers the different authorisation flows supported by the API and provides a step-by-step overview of how to complete them successfully.

Our API supports two main authorisation flows:

  • Redirect - where the PSU is redirected to their bank to complete the authorisation.
  • Decoupled - where the PSU completes the authorisation embedded in your own interface.

The overall authorisation process is the same regardless of the type of resource being authorised — whether it's a consent, a single payment, or a signing basket. This guide therefore uses variables instead of resource-specific fields.

​Resource Variables

VariableConsentPaymentSigning Basket
resourceBasePath/psd2/consent/v1/consents/{consentId}/psd2/paymentinitiation/v1/{payment-service}/{payment-product}/{paymentId}/psd2/paymentinitiation/v1/signing-baskets/{basketId}
resourceIdconsentIdpaymentIdbasketId
resourceAuthorisationIdConsentAuthorisationIdPaymentAuthorisationIdBasketAuthorisationId
resourceScopeaccountinformation corporate/privatepaymentinitiation corporate/privatepaymentinitiation corporate/private

In this guide, the flows for decoupled and redirect authorisation are outlined separately to highlight any flow-specific steps.

Decoupled

​Decoupled Flow

​1. Create Authorisation

The first step after creating a resource is to create an authorisation process for that resource. The response will provide a list of available SCA methods for the specified bank.

​Endpoint

POST {resourceBasePath}/authorisations
http

​Request Headers

NameTypeDescription
X-Request-IDstring(uuid)The ID of the request, unique to the call, as determined by the initiating party.
X-BicFistringThe BIC of the bank to which the request is addressed.
PSU-IDstringThe ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
PSU-Corporate-IDstringThe Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
TPP-Redirect-PreferredbooleanIndicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types.
PSU-IP-Addressstring(ipv4)The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.
PSU-User-AgentstringThe forwarded Agent header field of the HTTP request between PSU and TPP, if available.
curl -X POST "{resourceBasePath}/authorisations" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 6c2fd2da-d90e-4cc9-944b-0e470594540d" \
  -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": "10f647b2-2ec3-48a5-845b-c3851cde1acb",
    "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_token",
            "name": "Mobile BankID on another device"
        }
    ],
    "scaStatus": "received"
}
json

​2. Start Authorisation

This request triggers the authentication flow. Here, you select the 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.

If the bank supports animated QR, the response from the previous step will include an element with mbid_animated_qr_image or mbid_animated_qr_token as the authenticationMethodId, which should be used if the authentication is to be performed on another device. If the authentication is to be performed on the same device, mbid_same_device (or mbid if not available) should be used.

​Endpoint

PUT {resourceBasePath}/authorisations/{authorisationId}
http

​Path Parameters

NameTypeDescription
authorisationIdstringThe ID of the authorisation process that was created.

​Request Headers

NameTypeDescription
X-Request-IDstring(uuid)The ID of the request, unique to the call, as determined by the initiating party.
X-BicFistringThe BIC of the bank to which the request is addressed.
PSU-IDstringThe ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
PSU-Corporate-IDstringThe Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
TPP-Redirect-PreferredbooleanIndicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types.
PSU-IP-Addressstring(ipv4)The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.
PSU-User-AgentstringThe forwarded Agent header field of the HTTP request between PSU and TPP, if available.

​Request Body

NameTypeDescription
authenticationMethodIdstringThe ID of the authentication method provided by the bank.
curl -X PUT "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 57d92dd1-077a-4425-bd9e-e69e1079d107" \
  -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 to check in the response is the SCA flow used by the bank, which will be extracted from the response header aspsp-sca-approach. For a decoupled flow, aspsp-sca-approach should be DECOUPLED, in which case you will need to present the correct interface to the PSU.

​Response Headers

aspsp-sca-approach: "DECOUPLED"
json

A. If authenticationMethodId is mbid_same_device or mbid:

These methods launch the BankID app on the same device, meaning that you need to generate the BankID link. To do this, you first need to get the data from the response, which you will set the {autoStartToken} to in the BankID link.

​Response

{
    "chosenScaMethod": {
        "authenticationType": "CHIP_OTP",
        "authenticationMethodId": "mbid_same_device",
        "name": "Mobile BankID on this device"
    },
    "_links": {
        "scaStatus": {
            "href": "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb"
        }
    },
    "scaStatus": "started",
    "challengeData": {
        "data": [
            "0a5f9137-7cb2-4d2f-b762-bfab4ad9d35f"
        ]
    }
}
json

Once you have the {autoStartToken}, the BankID link should be constructed as below:

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

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

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:

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

B. If authenticationMethodId is mbid_animated_qr_token:

With this method, you need to generate your own QR code from the token animatedQRToken and instruct the PSU to scan it in the Mobile BankID app.

The QR code is only valid for 1 second and must be refreshed by polling Get Authorisation SCA Status every 500-1000ms to give the PSU enough time to scan it. Only send a new request when you've received a response for the previous one.

​Response

{
    "chosenScaMethod": {
        "authenticationType": "PHOTO_OTP",
        "authenticationMethodId": "mbid_animated_qr_token",
        "name": "Mobile BankID on another device"
    },
    "_links": {
        "scaStatus": {
            "href": "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb"
        }
    },
    "scaStatus": "started",
    "challengeData": {
        "data": [
            "bankid.dXRvS2VuU3RyaW5nMTIz"
        ]
    }
}
json

C. If authenticationMethodId is mbid_animated_qr_image:

With this method, you need to dispay the Base64-encoded PNG animatedQRImage and instruct the PSU to scan it in the Mobile BankID app.

​Response

{
    "chosenScaMethod": {
        "authenticationType": "PHOTO_OTP",
        "authenticationMethodId": "mbid_animated_qr_image",
        "name": "Mobile BankID on another device"
    },
    "_links": {
        "scaStatus": {
            "href": "{resourceBasePath}/10f647b2-2ec3-48a5-845b-c3851cde1acb"
        }
    },
    "psuMessage": "Please confirm with your bank app.",
    "scaStatus": "started",
    "challengeData": {
        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
    }
}
json

​3. Get Authorisation SCA Status

Finally, use the scaStatus link from the response to poll the Get Authorisation SCA Status call until scaStatus becomes finalised or failed.

Authentication may take time. Keep polling Get Authorisation SCA Status until a final status is returned.

​Endpoint

GET {resourceBasePath}/authorisations/{authorisationId}
http

​Path Parameters

NameTypeDescription
{authorisationId}stringThe ID of the authorisation process that was created.

​Request Headers

NameTypeDescription
X-Request-IDstring(uuid)The ID of the request, unique to the call, as determined by the initiating party.
X-BicFistringThe BIC of the bank to which the request is addressed.
PSU-IDstringThe ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
PSU-Corporate-IDstringThe Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
TPP-Redirect-PreferredbooleanIndicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types.
PSU-IP-Addressstring(ipv4)The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.
PSU-User-AgentstringThe forwarded Agent header field of the HTTP request between PSU and TPP, if available.
curl -X GET "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 9d443655-c1e9-4434-9013-56a859bb8b67" \
  -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
Redirect

​Redirect Flow

​1. Create Authorisation

The first step after creating a resource is to create an authorisation process for that resource. The response will provide a list of available SCA methods for the specified bank.

​Endpoint

POST {resourceBasePath}/authorisations
http

​Request Headers

NameTypeDescription
X-Request-IDstring(uuid)The ID of the request, unique to the call, as determined by the initiating party.
X-BicFistringThe BIC of the bank to which the request is addressed.
PSU-IDstringThe ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
PSU-Corporate-IDstringThe Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
TPP-Redirect-PreferredbooleanIndicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types.
PSU-IP-Addressstring(ipv4)The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.
PSU-User-AgentstringThe forwarded Agent header field of the HTTP request between PSU and TPP, if available.
curl -X POST "{resourceBasePath}/authorisations" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 6c2fd2da-d90e-4cc9-944b-0e470594540d" \
  -H "X-BicFi: ESSESESS" \
  -H "PSU-ID: 123456789001" \
  -H "PSU-Corporate-ID: 1234567890" \
  -H "TPP-Redirect-Preferred: true" \
  -H "PSU-IP-Address: 152.120.171.187"
bash

​Response

{
    "authorisationId": "10f647b2-2ec3-48a5-845b-c3851cde1acb",
    "scaStatus": "received",
    "scaMethods": [
        {
            "authenticationType": "PUSH_OTP",
            "authenticationMethodId": "mbid",
            "name": "Mobilt BankID"
        }
    ],
    "_links": {
        "authoriseTransaction": {
            "href": "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb"
        },
        "scaStatus": {
            "href": "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb"
        }
    }
}
json

​2. Start Authorisation

This request triggers the authentication flow. Here, you select the 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 a redirect flow, authenticationMethodId is always mbid.

​Endpoint

PUT {resourceBasePath}/authorisations/{authorisationId}
http

​Path Parameters

NameTypeDescription
authorisationIdstringThe ID of the authorisation process that was created.

​Request Headers

NameTypeDescription
X-Request-IDstring(uuid)The ID of the request, unique to the call, as determined by the initiating party.
X-BicFistringThe BIC of the bank to which the request is addressed.
PSU-IDstringThe ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
PSU-Corporate-IDstringThe Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
TPP-Redirect-PreferredbooleanIndicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types.
PSU-IP-Addressstring(ipv4)The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.
PSU-User-AgentstringThe forwarded Agent header field of the HTTP request between PSU and TPP, if available.

​Request Body

NameTypeDescription
authenticationMethodIdstringThe ID of the authentication method provided by the bank.
curl -X PUT "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 57d92dd1-077a-4425-bd9e-e69e1079d107" \
  -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"
    }'
bash

​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 the scaOAuth parameter and replace the placeholders with the relevant values.

​Response

{
    "chosenScaMethod": {
        "authenticationType": "PUSH_OTP",
        "authenticationMethodId": "mbid",
        "name": "Mobilt BankID"
    },
    "_links": {
        "scaStatus": {
            "href": "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb"
        },
        "scaOAuth": {
            "href": "https://auth.openbankingplatform.com/connect/authorize?client_id=[CLIENT_ID]&scope={resourceScope}&response_type=code&redirect_uri=[TPP_REDIRECT_URI]&state=[TPP_STATE]&acr_values=idp:ESSESESS%20{resourceId}:70c6d203-e1d1-43ff-9e42-07e5dda640ba%20{resourceAuthorisationId}:10f647b2-2ec3-48a5-845b-c3851cde1acb"
        }
    },
    "scaStatus": "started"
}
json

Replace the following placeholders in the redirect link as below:

[CLIENT_ID] should be replaced by the client_id of your application in the Developer Portal.

[TPP_REDIRECT_URI] is the URI you want us to redirect to after you 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.

Now that you have what you need to let the PSU authenticate, redirect the PSU to this URI. When the PSU has authenticated, the bank will route the PSU back to your [TPP_REDIRECT_URI]. Once the PSU has been redirected, a code will be added to the URI, which you will need to extract in the following step, along with the scope.

https://www.openpayments.io/?code=AMpzr91kT-QwL8dXyNf3VbGt6hEsJoRc2mKuHqPaSj&scope={resourceScope}&state=myState
text

​2.1 Activate OAuth Authorisation

To finalise the authorisation, you make the following request to our auth server.

​Endpoint

POST /connect/token
http

​Request Headers

NameTypeDescription
AcceptstringSpecifies the desired response format.
Content-TypestringSpecifies the request format.
X-{resourceAuthorisationId}stringThe ID of the authorisation process that was created.
X-{resourceId}stringThe ID of the resource that was created.

​Request Body

NameTypeDescription
client_idstringThe Client ID of the application you created in the Developer Portal.
client_secretstringThe secret key that was generated when the application was created.
codestringThe authorisation code received from the authorisation server after the PSU has authenticated at the bank. This code is exchanged for an access token.
redirect_uristring(uri)The URI to which the PSU was redirected after authorisation. It must exactly match the redirect URI used in the initial authorisation request.
scopestringSpecifies 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_typestring(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-`{resourceAuthorisationId}`: 10f647b2-2ec3-48a5-845b-c3851cde1acb" \
  -H "X-`{resourceId}`: 70c6d203-e1d1-43ff-9e42-07e5dda640ba" \
  -d "client_id=555510ad-da62-4e6d-80b8-e18967eabf0b" \
  -d "client_secret=joiaHR0cHM6Ly9hdXRoLm9wZW5iYW5raW5ncGxhdGZvcm0uY29tIiwiYXVkIjpb" \
  -d "code=AMpzr91kT-QwL8dXyNf3VbGt6hEsJoRc2mKuHqPaSj" \
  -d "redirect_uri=https://exampleapplication.com/callback" \
  -d "scope={resourceScope}" \
  -d "grant_type=authorization_code"
bash

​Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
    "expires_in": 3600,
    "token_type": "Bearer", 
    "scope": "{resourceScope}"
}
json

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

​3. Get Authorisation SCA Status

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

Authentication may take time. Keep polling Get Authorisation SCA Status until a final status is returned.

​Endpoint

GET {resourceBasePath}/authorisations/{authorisationId}
http

​Path Parameters

NameTypeDescription
{authorisationId}stringThe ID of the authorisation process that was created.

​Request Headers

NameTypeDescription
X-Request-IDstring(uuid)The ID of the request, unique to the call, as determined by the initiating party.
X-BicFistringThe BIC of the bank to which the request is addressed.
PSU-IDstringThe ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID.
PSU-Corporate-IDstringThe Corporate ID of the PSU when acting on behalf of an organization, e.g. Org. nummer for SE, KVK for NL.
TPP-Redirect-PreferredbooleanIndicates a preference for redirect-based SCA over decoupled when set to true. The bank may not support both types.
PSU-IP-Addressstring(ipv4)The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU.
PSU-User-AgentstringThe forwarded Agent header field of the HTTP request between PSU and TPP, if available.
curl -X GET "{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0..." \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 9d443655-c1e9-4434-9013-56a859bb8b67" \
  -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
KYCISO Payments