Open Payments Documentation

This API is used to retrieve and manage consent for accessing account information on behalf of a banks customer. If you are new to Open Payments API it is probably best to read a bit about how the APIs work in the ASPSP tutorial.

Hosts

Available AUTH_HOST values

Environment	URL
Sandbox	https://auth.sandbox.openbankingplatform.com
Production	https://auth.openbankingplatform.com

Available API_HOST values

Environment	URL
Sandbox	https://api.sandbox.openbankingplatform.com
Production	https://api.openbankingplatform.com

PlantUML model

Acquire an access token for Account Information

curl -X POST
    [AUTH_HOST]/connect/token
    -H 'Content-Type: application/x-www-form-urlencoded'
    -d 'client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&scope=accountinformation private&grant_type=client_credentials'

javascript

If you have looked at the ASPSP tutorial you will notice that this is similar. The only difference is the scope that you get the token for. Here it should be set to accountinformation private for access to private account information and accountinformation corporate if you want to access account information using corporate accounts.

This post will return a JSON object that looks like this:

{
    "access_token": "[ACCESS_TOKEN]",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "accountinformation private"
}

json

This endpoint is used to initiate the consent process with a request for consent.

curl -X POST
    [API_HOST]/psd2/consent/v1/consents
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'Content-Type: application/json'
    -H 'PSU-IP-Address: [PSU_IP_Address]'
    -H 'X-BicFi: [BICFI]'
    -H 'X-Request-ID: [GUID]'
    -d '{
        "access": {
            "accounts": [
                {
                    "iban": "[CONSENT_IBAN]",
                    "currency": "[CONSENT_CURRENCY]"
                },
                {
                    "iban": "[OTHER_CONSENT_IBAN]",
                    "currency": "[CONSENT_CURRENCY]"
                }
            ],
            "balances": [
                {
                    "iban": "[CONSENT_IBAN]",
                    "currency": "[CONSENT_CURRENCY]"
                }
            ],
            "transactions": [
                {
                    "iban": "[CONSENT_IBAN]",
                    "currency": "[CONSENT_CURRENCY]"
                }
            ]
        },
        "recurringIndicator": [CONSENT_RECURRING_INDICATOR],
        "validUntil": "[yyyy-MM-dd]",
        "frequencyPerDay": [CONSENT_FREQUENCY_PER_DAY],
        "combinedServiceIndicator": [CONSENT_COMBINED_SERVICE_INDICATOR]
    }'

javascript

Headers

PSU-IP-Address is the IP address of the end user.
X-BicFi the BICFI for the user's ASPSP. Find it in the ASPSP API.
X-Request-ID used to verify that the response matches the request.

Body description

access is a list of data items that consent need to be acquired for. There are three possible things to get consent from:

accounts this is a consent to get access to an account list with some account details needed.
balances this is a consent to get access to balances for accounts.
transactions this is a consent to see all the transactions for accounts.

Each consent request contains iban and currency (optional). Each consent request can be a list of account ids (ibans). The balances and transactions consent request must contain a subset of the accounts listed in accounts.

recurringIndicator is a boolean that indicates if the consent can be used multiple times or not. validUntil is a date in yyyy-MM-dd format. frequencyPerDay is a number indicating the number of usages per day for this consent. combinedServiceIndicator if true this indicates that the session will be used to initiate a payment also. It has no practical meaning at this time, but should be set to false as its default value.

Response

{
    "consentStatus": "received",
    "consentId": "[CONSENT_ID]",
    "scaMethods": [
        {
            "authenticationType": "PUSH_OTP",
            "authenticationMethodId": "[AUTHENTICATION_METHOD_ID]"
        }
    ],
    "_links": {
        "self": {
            "href": "/psd2/consent/v1/consents/[CONSENT_ID]"
        },
        "status": {
            "href": "/psd2/consent/v1/consents/[CONSENT_ID]/status"
        },
        "startAuthorisation": {
            "href": "/psd2/consent/v1/consents/[CONSENT_ID]/authorisations"
        }
    }
}

json

At this point the returned status should always be received. All possible values are listed below.

The list at scaMethods typically contains one entry. But in the future it is possible that banks - or our platform here - will support multiple methods.

Authentication type will always be PUSH_OTP since that is what the banks we integrate with support. In the future it may change. See below for a list of possible types.

The list of links can be used for further actions on the consent. The self one is obviously to retrieve the created consent request. The status is for accessing the status of the request. And startAuthorisationis the next step in the sequence of calls that is needed to get a consent.

Response headers

ASPSP-SCA-Approach see below for different values.
X-Request-ID

Once you have a consent you can use the id for that consent to get information about the consent.

curl -X GET
    [API_HOST]/psd2/consent/v1/consents/[CONSENT_ID]
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'PSU-IP-Address: [PSU_IP_Address]'
    -H 'X-BicFi: [BICFI]'
    -H 'X-Request-ID: [GUID]'

javascript

Headers

See Create consent.

Path parameter

CONSENT_ID - the id that was returned when the consent was created.

Response

{
    "consentId": "[CONSENT_ID]",
    "access": {
        "accounts": [
            {
                "iban": "[CONSENT_IBAN]",
                "currency": "[CONSENT_CURRENCY]"
            }
        ],
        "balances": [
            {
                "iban": "[CONSENT_IBAN]",
                "currency": "[CONSENT_CURRENCY]"
            }
        ],
        "transactions": [
            {
                "iban": "[CONSENT_IBAN]",
                "currency": "[CONSENT_CURRENCY]"
            }
        ]
    },
    "recurringIndicator": false,
    "validUntil": "2019-10-01",
    "frequencyPerDay": 100,
    "lastActionDate": "2019-05-16",
    "consentStatus": "received"
}

json

This is the exact same body as the one sent in to the create consent request endpoint except that the current status is added.

Response headers

X-Request-ID

A consent request can be deleted with a DELETE call.

curl -X DELETE
    [API_HOST]/psd2/consent/v1/consents/[CONSENT_ID]
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'PSU-IP-Address: [PSU_IP_Address]'
    -H 'X-BicFi: [BICFI]'
    -H 'X-Request-ID: [GUID]'

javascript

Status code

204 No content

Response headers

X-Request-ID

The consent request status is returned as part of the "get consent request" endpoint but it is also possible to use this endpoint to get only the status and nothing else. It is basically the same call with status added at the end to the path.

curl -X GET
    [API_HOST]/psd2/consent/v1/consents/[CONSENT_ID]/status
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'PSU-IP-Address: [PSU_IP_Address]'
    -H 'X-BicFi: [BICFI]'
    -H 'X-Request-ID: [GUID]'

javascript

Headers

See Create consent.

Path parameter

CONSENT_ID

Response

{
    "consentStatus": "received"
}

json

See possible values for status further down.

Response headers

X-Request-ID

curl -X POST
    [API_HOST]/psd2/consent/v1/consents/[CONSENT_ID]/authorisations
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'Content-Type: application/json'
    -H 'PSU-IP-Address: [PSU_IP_Address]'
    -H 'X-BicFi: [BICFI]'
    -H 'X-Request-ID: [GUID]'
    -d ''

javascript

Note that this call does not need a body despite being a POST.

Headers

See Create consent.

Path parameter

CONSENT_ID

Response

{
    "authorisationId": "[CONSENT_AUTH_ID]",
    "scaMethods": [
        {
            "authenticationType": "PUSH_OTP",
            "authenticationMethodId": "[AUTHENTICATION_METHOD_ID]"
        }
    ],
    "_links": {
        "scaStatus": {
            "href": "/psd2/consent/v1/consents/[CONSENT_ID]/authorisations/[CONSENT_AUTH_ID]"
        },
        "selectAuthenticationMethod": {
            "href": "/psd2/consent/v1/consents/[CONSENT_ID]/authorisations/[CONSENT_AUTH_ID]"
        }
    },
    "scaStatus": "started"
}

json

Response headers

ASPSP-SCA-Approach - see below for different values.
X-Request-ID

curl -X GET
    [API_HOST]/psd2/consent/v1/consents/[CONSENT_ID]/authorisations
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'PSU-IP-Address: [PSU_IP_Address]'
    -H 'X-BicFi: [BICFI]'
    -H 'X-Request-ID: [GUID]'

javascript

Headers

See Create consent.

Path parameter

CONSENT_ID

Response

{
    "authorisationIds": [
        "[CONSENT_AUTH_ID]"
    ]
}

json

Response headers

X-Request-ID

curl -X GET
    [API_HOST]/psd2/consent/v1/consents/[CONSENT_ID]/authorisations/[CONSENT_AUTH_ID]
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'PSU-IP-Address: [PSU_IP_Address]'
    -H 'X-BicFi: [BICFI]'
    -H 'X-Request-ID: [GUID]'

javascript

Headers

See Create consent.

Path parameter

CONSENT_ID
CONSENT_AUTH_ID

Response

{
    "scaStatus": "received"
}

json

Response headers

X-Request-ID

curl -X PUT
    [API_HOST]/psd2/consent/v1/consents/[CONSENT_ID]/authorisations/[CONSENT_AUTH_ID]
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
    -H 'Content-Type: application/json'
    -H 'PSU-IP-Address: [PSU_IP_Address]'
    -H 'X-BicFi: [BICFI]'
    -H 'X-Request-ID: [GUID]'
    -d '{
        "authenticationMethodId": "[AUTHENTICATION_METHOD_ID]"
    }'

javascript

Headers

See Create consent.

Path parameter

CONSENT_ID
CONSENT_AUTH_ID

Response headers

ASPSP-SCA-Approach see below for different values.
X-Request-ID

Response

{
    "chosenScaMethod": {
        "authenticationType": "PUSH_OTP",
        "authenticationMethodId": "[AUTHENTICATION_METHOD_ID]"
    },
    "_links": {
        "scaStatus": {
            "href": "/psd2/consent/v1/consents/[CONSENT_ID]/authorisations/[CONSENT_AUTH_ID]"
        },
        "scaOAuth": {
            "href": "[AUTH_HOST]/connect/authorize?client_id=[CLIENT_ID]&scope=accountinformation%20private&response_type=code&redirect_uri=[TPP_REDIRECT_URI]&state=[TPP_STATE]&acr_values=idp:[BICFI]%20consentId:[CONSENT_ID]%20consentAuthorisationId:[CONSENT_AUTH_ID]"
        }
    },
    "psuMessage": "Please confirm with your bank app",
    "scaStatus": "scaMethodSelected"
}

json

Test procedure

If the ASPSP uses OAuth:

The above endpoint returns an OAuth authorize URL in the scaOAuth field.
Replace all the bracketed fields with real values. In your code you will have to replace only the two TPP values.
- TPP_REDIRECT_URI should be the URL to redirect to after auth is completed.
- TPP_STATE can be anything the TPP wants.
- BICIFI
Run it in a browser. Test data may differ for different banks, please see individual docs at supported banks.
When you submit the data you will be redirected to the [TPP_REDIRECT_URI]
On this URI a code param will be added.
Use this code in the subsequent call when getting the account information token.

Call the OAuth token endpoint to finalize consent flow.

curl -X POST [AUTH_HOST]/connect/token -H 'Content-Type: application/x-www-form-urlencoded' -H 'X-ConsentAuthorisationId: [CONSENT_AUTH_ID]' -H 'X-ConsentId: [CONSENT_ID]' -d 'client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&code=[CODE]&redirect_uri=[TPP_REDIRECT_URI]&scope=accountinformation&grant_type=authorization_code'

At this point you are ready to call the account service. Read more in the account service tutorial.

Schemas

consentStatus for a consent can be one of the following values:

received
rejected
valid
revokedByPsu
expired
terminatedByTpp

scaStatus for a consent authorisation can be one of the following values:

received
psuIdentified
psuAuthenticated
scaMethodSelected
started
finalised
failed
exempted

ASPSP-SCA-Approach

This is a response header that describes how to proceed with authentication. Can be one of the following values. See the NextGen specs for more details.

EMBEDDED
DECOUPLED
REDIRECT

Authentication type

authenticationType for a consent authorisation can be one of the following values:

SMS_OTP
CHIP_OTP
PHOTO_OTP
PUSH_OTP

At this point the only type supported by banks are PUSH_OTP and how that works is covered by this tutorial. As we move into more markets and cover more different banks this will change and the documentation will be updated.

​Hosts

​Consent Flow

​Acquire an access token for Account Information

​Create Consent

​Headers

​Body description

​Response

​Response headers

​Get Consent

​Headers

​Path parameter

​Response

​Response headers

​Delete Consent

​Status code

​Response headers

​Get Consent Status

​Headers

​Path parameter

​Response

​Response headers

​Start Consent Authorisation Process

​Headers

​Path parameter

​Response

​Response headers

​Get Consent Authorisation Sub-Resources

​Headers

​Path parameter

​Response

​Response headers

​Get Consent Authorisation SCA Status

​Headers

​Path parameter

​Response

​Response headers

​Update PSU Data for Consent

​Headers

​Path parameter

​Response headers

​Response

​Test procedure

​Schemas

​Consent status

​Consent authorisation status

​ASPSP-SCA-Approach

​Authentication type

Hosts

Consent Flow

Acquire an access token for Account Information

Create Consent

Headers

Body description

Response

Response headers

Get Consent

Headers

Path parameter

Response

Response headers

Delete Consent

Status code

Response headers

Get Consent Status

Headers

Path parameter

Response

Response headers

Start Consent Authorisation Process

Headers

Path parameter

Response

Response headers

Get Consent Authorisation Sub-Resources

Headers

Path parameter

Response

Response headers

Get Consent Authorisation SCA Status

Headers

Path parameter

Response

Response headers

Update PSU Data for Consent

Headers

Path parameter

Response headers

Response

Test procedure

Schemas

Consent status

Consent authorisation status

ASPSP-SCA-Approach

Authentication type