IPS/X

Consent Management
REST API Specification
V3.0

Instant Payment System

CMA Small Systems AB

Document information

Project name: Instant Payment System

Document name: Consent Management REST API v1.0 specification

Version history (in reversed order)

Version Date Authors Comments

CMA Small Systems
001 19.08.2022 Draft version
AB
CMA Small Systems A series of pieces are added according to
002 19.09.22
AB SBP suggestions
CMA Small Systems
003 07.11.22 Tuning of headers
AB

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 2 OF 32

Document audience

IPS participants: Commercial banks

PISPs

 Copyright CMA Small Systems AB – 2022

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 3 OF 32

Table of contents
1. Definitions and abbreviations ................................................................................... 5
2. Overview .................................................................................................................... 5
3. Requesting Consent .................................................................................................. 7
3.1. Web Channel is Selected for Authentication............................................................. 7
3.1.1. Flow ..................................................................................................................... 7
3.1.2. Request for New Consent .................................................................................... 8
3.1.3. Asynchronous Response - Positive .................................................................... 10
3.1.4. Asynchronous Response - Negative .................................................................. 11
3.2. OTP is Selected for Authentication ......................................................................... 12
3.2.1. Flow ................................................................................................................... 12
3.2.2. Request for New Consent .................................................................................. 13
3.2.3. Asynchronous Response - Positive .................................................................... 13
3.2.4. Asynchronous Response - Negative .................................................................. 14
4. Authenticating Payer Person .................................................................................. 15
4.1. Authentication over Web Channel .......................................................................... 15
4.1.1. Flow ................................................................................................................... 15
4.1.2. Delivery of Authentication Secret and Person Public Key ................................ 16
4.2. Authentication with OTP ......................................................................................... 18
4.2.1. Flow ................................................................................................................... 18
4.2.2. Delivery of Authentication Secret and Person Public Key ................................ 19
5. Granting Consent .................................................................................................... 19
5.1. Flow ....................................................................................................................... 19
5.2. Delivery of Data on New Consent........................................................................... 19
5.3. Reporting Authentication Error ............................................................................... 20
6. Finalizing Consent ................................................................................................... 22
6.1. Flow ....................................................................................................................... 22
6.2. Request for Consent Finalization ........................................................................... 22
6.3. Asynchronous Response - Positive ........................................................................ 24
6.4. Asynchronous Response - Negative ...................................................................... 25
7. Revoking Consent ................................................................................................... 26
7.1. Revocation from PISP Side .................................................................................... 26
7.1.1. Flow ................................................................................................................... 26
7.1.2. Request for Consent Revocation ........................................................................ 26
7.1.3. Asynchronous Response - Positive .................................................................... 27
7.1.4. Asynchronous Response - Negative .................................................................. 28
7.2. Revocation from Payer Person FI Side .................................................................. 29
7.2.1. Flow ................................................................................................................... 29
7.2.2. Delivery of Revocation Information .................................................................. 30
8. Payment Initiation Request ..................................................................................... 30
9. Composing a Challenge .......................................................................................... 30

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 4 OF 32

 9.1. Challenge for Credentials Generation .................................................................... 30
9.2. Challenge for Consent Finalization ......................................................................... 31
9.3. Challenge for PIR Cryptogram ............................................................................... 31
10. Error codes .............................................................................................................. 31

1. Definitions and abbreviations

PISP Payment Initiation Service Provider
Payer Person FI Financial Institution holding Payer Person source account

2. Overview
Transacting via PISP requires an explicit consent of account holder, which is kept with Payer Person
FI. Before executing any instruction Payer Person submits over PISP Payer Person FI must check if
sufficient consent is both in place and valid.
Consent management operations include: consent issuance (3 through 6) and revocation (7). In its
turn, consent issuance is a multistep procedure, which is made of: requesting (3), authenticating (4),
granting (5) and finalizing (6). Note, that certain steps can be executed in slightly different ways
depending on what channel is used for consent Payer Person authentication, that is, Web or OTP.
Note that whenever FIDO (Fast IDentity Online) is referred to in this document FIDO 2 is assumed.

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 5 OF 32

 Figure 1. Steps for Consent Issuance

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 6 OF 32

3. Requesting Consent
3.1. Web Channel is Selected for Authentication

3.1.1. Flow

Figure 2. Requesting Consent: Web Channel Selected for Authentication

Note: At step 5, on receiving the Consent Request, the Payer Person FI needs to

1. Validate customer exist with this Mobile Number

2. Store Consent Request against customer

3. Determine an Authentication method (Web or OTP)

4. If Authentication Method is determined as Web, then generate an Authentication URL which is

unique to that consent request and is available for authentication for a limited time period (5
minutes). The authentication URL should be responsive and designed to be opened on Web or
Mobile browsers. It should be only usable one-time for each consentRequest.

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 7 OF 32

 5. When PISP will redirect customer to Authentication URL, the Payer Person FI will authenticate
customer as per its own customer authentication and security policy and redirect to the callback
URL received in Consent Request API.

6. In case Authentication is successful the redirect URL will contain following parameters

a. authenticationResponse=1

b. authenticationToken = Secret

7. In case Authentication is unsuccessful the redirect URL will indicate failure using following
parameters

a. authenticationResponse=0

8. PISP will only proceed to Steps described in 4.1 in case authenticationResponse = 1

3.1.2. Request for New Consent

Description PISP requests from Payer Person FI a new consent

Method POST

URL /consentRequests

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of PISP
Participant-
Code

Receiver- String(11) true [pseudo] BIC of Payer Person FI

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 8 OF 32

 Sender-User- String(12) false Code of sending user
Code

Body {
"consentRequestID": "11111111-0000-0000-0000-000000000000",
"uid":
{
"type": "mobile",
"value": "+12345678901"
},
"authChannels": ["Web", "OTP"],
"callBackURI”: "pisp-
app://callback?authenticationResponse=1&authenticationToken=xxxxxxx”
}

Body Field Type Required Description

description
consentReques String true Common unique ID between
tID the PISP and the Payer Person
FI for the consent request
object. The ID should be reused
for resends of the same
consent request. A new ID
should be generated for each
new consent request

Uid true User identification data for

Payer Person FI

authChannels ConsentRequ true A collection of the types of

estChannelTy authentication that the Payer
pe Person FI may use to verify that
its customer has in fact
requested access for the PISP
to the accounts requested

callBackURI Uri true The callback URI that the user

will be redirected to after
completing verification via the
WEB authentication channel.
This field is mandatory as the
PISP does not know ahead of
time which AuthChannel the
Payer Person FI will use to
authenticate their customer

202 Accepted Request has been accepted for processing

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 9 OF 32

 Response 503 Service unavailable Selected Payer Person FI does not support
type the service (is missing in the routing table)

3.1.3. Asynchronous Response - Positive

Description Person FI responds positively to a PISP request for a new consent

Method PUT

URL /consentRequests/<consentRequestID>

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) True [pseudo] BIC of Payer Person FI
Participant-
Code

Receiver- String(11) True [pseudo] BIC of PISP

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

Body {
"authChannels": ["Web"],
"authURI”: "fi.com/authorize?consentRequestID=11111111-0000-
0000-0000-000000000000"
}

Body Field Type Required Description

description
authChannels ConsentRequ true A collection of the types of
estChannelTy authentication that the Payer
pe Person FI may use to verify that
its customer has in fact
requested access for the PISP
CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 10 OF 32
 to the accounts requested

authURI Uri true The URI where PISP should

redirect the user for
authentication over Web
channel

Response 200 OK Success

type
404 Not found Given consentRequestID does not exist

3.1.4. Asynchronous Response - Negative

Description Person FI responds with error to a PISP request for a new consent

Method PUT

URL /consentRequests/<consentRequestID>/error

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) True [pseudo] BIC of Payer Person FI
Participant-
Code

Receiver- String(11) True [pseudo] BIC of PISP

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

Body {
errorInformation : {
errorCode: "1",
errorDescription: "Consent request error. Customer
not found or has invalid status"
}

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 11 OF 32

 }

Body Field Type Required Description

description
errorCode String true Error code as per paragraph 10

errorDescriptio String true Error description as per

n paragraph 10

Response 200 OK Success

type
404 Not found Given consentRequestID does not exist

3.2. OTP is Selected for Authentication

3.2.1. Flow

Figure 3. Requesting Consent: OTP Selected for Authentication

Note: for OTP Generation, Payer Person FI must follow these guidelines.
1. OTP Length is 6 digits

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 12 OF 32

 2. OTP expiry time is 2 minutes
3. OTP should be unique per consent request and once used should not be re-used. It means that
if in subsequent PATCH request (Section 4.2) OTP validation fails then invalidate the entire
Consent Request.

3.2.2. Request for New Consent

Identical to the one described in 3.1.2.

3.2.3. Asynchronous Response - Positive

Description Person FI responds to a PISP request for a new consent

Method PUT

URL /consentRequests/<consentRequestID>

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of Payer Person FI
Participant-
Code

Receiver- String(11) true [pseudo] BIC of PISP

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

Body {
"authChannels":["OTP"]
}

Field Type Required Description

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 13 OF 32

 Body authChannels ConsentRequ true A collection of the types of
description estChannelTy authentication that the Payer
pe Person FI may use to verify that
its customer has in fact
requested access for the PISP
to the accounts requested

Response 200 OK Success

type
404 Not found Given consentRequestID does not exist

3.2.4. Asynchronous Response - Negative

Description Person FI responds with error to a PISP request for a new consent

Method PUT

URL /consentRequests/<consentRequestID>/error

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of Payer Person FI
Participant-
Code

Receiver- String(11) true [pseudo] BIC of PISP

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

Body {
errorInformation : {
errorCode: "1",
errorDescription: "Consent request error. Customer
not found or has invalid status"
}

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 14 OF 32

 }

Body Field Type Required Description

description
errorCode String true Error code as per paragraph 10

errorDescriptio String true Error description as per

n paragraph 10

Response 200 OK Success

type
404 Not found Given consentRequestID does not exist

4. Authenticating Payer Person

4.1. Authentication over Web Channel

4.1.1. Flow

Figure 4. Payer Person Authentication over Web

Note for PISP:

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 15 OF 32

 1. Secret value provided by Payer Person FI should not be stored in clear by PISP. It should be only
captured and used to create Challenge.

2. PISP will design its user interface such that in case Challenge is validated and it receives Grant
Consent within 1 minute it will prompt customer for next step, otherwise the process will
terminate.

Note for Payer Person FI:

1. In case FI identifies that the Consent Request has already been fulfilled then it will immediately
decline.

4.1.2. Delivery of Authentication Secret and Person Public Key

Description PISP delivers to Payer Person FI the secret resulted from Payer Person
authentication along with Payer Person public key

Method PATCH

URL /consentRequests/<consentRequestID>

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of PISP
Participant-
Code

Receiver- String(11) true [pseudo] BIC of Payer Person FI

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 16 OF 32

 Body {
"fidoPublicKeyCredentialAttestation":
{
"id": "5C1VIOMZf_20lXL3VLrHZoIxDsQsErKdr9Mi6v-…",
"response":
{
"attestationObject": "SZYN5YgOjGh0NBcPZHZgW4_kr…",
"clientDataJSON": "MEQCIAEoNafIT4gUb9Xx…"
}
}
}

Body Field Type Required Description

description
fidoPublicKeyCr PublicKeyCre true PublicKeyCredential data
edentialAttesta dential resulting from procedure
tion explained un
https://webauthn.guide/#regis
tration.
Note, that both PISP (when
initiating keys generation) and
FI (when verifying keys) must
compose the challenge as
explained in 9.1.

Response 202 Accepted Request has been accepted for processing

type
404 Not found Resource with the given consentRequestID
does not exist

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 17 OF 32

4.2. Authentication with OTP

4.2.1. Flow

Figure 5. Payer Person Authentication with OTP

Note for PISP:

3. OTP value provided by customer should not be stored in clear by PISP. It should be only captured
and used to create Challenge.

4. PISP will design its user interface such that in case Challenge is validated and it receives Grant
Consent within 1 minute it will prompt customer for next step, otherwise the process will
terminate.

Note for Payer Person FI:

2. In case FI identifies that the Consent Request has already been fulfilled then it will immediately
decline.

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 18 OF 32

 3. In case challenge produced by known OTP does not match the challenge received from PISP,
then PISP will not proceed with Granting Consent

4.2.2. Delivery of Authentication Secret and Person Public Key

Identical to the one described in 4.1.2.

5. Granting Consent
5.1. Flow

Figure 6. Payer Person Authentication with OTP

5.2. Delivery of Data on New Consent

Description Payer Person FI grants a new consent

Method POST

URL /consents

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of Payer Person FI
Participant-
Code

Receiver- String(11) true [pseudo] BIC of PISP

Participant-
Code
CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 19 OF 32
 X-Request-ID UUID as true UUID defined by agent sending
String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

Body {
"consentRequestID": "1111111-0000-0000-0000-000000000000",
"consentID": "22222222-0000-0000-0000-000000000000",
"scopes":
[{
"accountNo": "PK26AIIN9234567890000003",
"actions": ["ACCOUNTS_TRANSFER"]
}]
}

Body Field Type Required Description

description
consentReques String true ID of request upon which the
tID given consent got issued

consentID String true ID of the issued consent

scopes Scope true A collection of accounts and

access rights for user to choose
from

Response 202 Accepted Request has been accepted for processing

type
404 Not found Given consentRequestID does not exist

5.3. Reporting Authentication Error

Description Person FI responds with error to a PISP request for a new consent

Method PUT

URL /consentRequests/<consentRequestID>/error

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Field Type Required Description

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 20 OF 32

 Header Sender- String(11) true [pseudo] BIC of Payer Person FI
parameters Participant-
Code

Receiver- String(11) true [pseudo] BIC of PISP

Participant-
Code

X-Request-ID UUID as true Request ID defined by sender

String(36) party

Sender-User- String(12) true Code of sending user

Code

Body {
errorInformation : {
errorCode: "3",
errorDescription: " Authentication error. Customer
public key not recognized"
}
}

Body Field Type Required Description

description
errorCode String true Error code as per paragraph 10

errorDescriptio String true Error description as per

n paragraph 10

Response 200 OK Success

type
404 Not found Given consentRequestID does not exist

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 21 OF 32

6. Finalizing Consent
6.1. Flow

Figure 7. Finalization of Consent

6.2. Request for Consent Finalization

Description PISP requests finalization of a newly issued consent

Method PUT

URL /consents/<consentID>

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 22 OF 32

 Header Field Type Required Description
parameters
Sender- String(11) true [pseudo] BIC of PISP
Participant-
Code

Receiver- String(11) true [pseudo] BIC of Payer Person FI

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

Body {
"scopes":
[{
"accountNo": "PK26AIIN9234567890000003",
"actions": ["ACCOUNTS_TRANSFER"]
}],
"fidoPublicKeyCredentialAssertion":
{
"id": "5C1VIOMZf_20lXL3VLrHZoIxDsQsErKdr9Mi6v-…",
"response":
{
"authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4_kr…",
"clientDataJSON": "MEQCIAEoNafIT4gUb9Xx…",
"signature": "IAEoNMEQCafIT4gUb9Xx…",
"userHandle": "BUKjEd1Ff0dx_S8NYTlSjcMh7G9…"
}
}
}

Body Field Type Required Description

description
fidoPublicKeyCr PublicKeyCre true PublicKeyCredential data
edentialAsserti dential resulting from procedure
on explained un
https://webauthn.guide/#auth
entication.
Note, that both PISP (when
initiating signature) and FI

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 23 OF 32

 (when verifying signature)
must compose the challenge as
explained in 9.2.

Response 202 Accepted Request has been accepted for processing

type
404 Not found Resource with the given consentID does not
exist

6.3. Asynchronous Response - Positive

Description Person FI responds to a PISP request for a new consent

Method PATCH

URL /consents/<consentID>

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of Payer Person FI
Participant-
Code

Receiver- String(11) true [pseudo] BIC of PISP

Participant-
Code

X-Request-ID UUID as true Request ID defined by sender

String(36) party

Sender-User- String(12) true Code of sending user

Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

Body {

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 24 OF 32

 "status":"ISSUED"
}

Body Field Type Required Description

description
status String true Status of the updated consent.
“ISSUED” should be expected
at this step.

Response 200 OK Success

type
404 Not found Given consentRequestID does not exist

6.4. Asynchronous Response - Negative

Description Person FI responds with error to a PISP request for a new consent

Method PATCH

URL /consents/<consentID>/error

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of Payer Person FI
Participant-
Code

Receiver- String(11) true [pseudo] BIC of PISP

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent request
(3.1.2/3.2.2) and then used
throughout the whole chain of
responses and requests from
3.1.3/3.2.3 to 6.3/6.4

Sender-User- String(12) true Code of sending user

Code

Body {
errorInformation : {

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 25 OF 32

 errorCode: "8",
errorDescription: " Consent finalization error. Can
not verify customer signature "
}
}

Body Field Type Required Description

description
errorCode String true Error code as per paragraph 10

errorDescriptio String true Error description as per

n paragraph 10

Response 200 OK Success

type
404 Not found Given consent does not exist

7. Revoking Consent
7.1. Revocation from PISP Side

7.1.1. Flow

Figure 8. Consent Revocation from PISP Side

7.1.2. Request for Consent Revocation

Description PISP requests a consent to be revoked

Method DELETE

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 26 OF 32

 URL /consents/<consentID>

Request Content-type application/json

headers
Charset UTF-8

Authorization Bearer, JWT access token

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of PISP
Participant-
Code

Receiver- String(11) true [pseudo] BIC of Payer Person FI

Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent revocation request
(7.1.2) and then used in
responses (7.1.3/7.1.4)

Sender-User- String(12) true Code of sending user

Code

Response 202 Accepted Request has been accepted for processing

type
404 Not found Resource with the given consentID does not
exist

7.1.3. Asynchronous Response - Positive

Description Person FI responds to a PISP request for a new consent

Method PATCH

URL /consents/<consentID>

Request Content-type application/json

headers
Charset UTF-8

Authorization Basic

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of Payer Person FI
Participant-
Code

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 27 OF 32

 Receiver- String(11) true [pseudo] BIC of PISP
Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent revocation request
(7.1.2) and then used in
responses (7.1.3/7.1.4)

Sender-User- String(12) true Code of sending user

Code

Body {
"status":"REVOKED",
"revokedAt":"2022-06-20T13:00:00.000"
}

Body Field Type Required Description

description
status String true Status of the updated consent.
“REVOKED” should be
expected in the given context.

revokedAt DateTime true Revocation date and time.

Response 200 OK Success

type
404 Not found Given consentRequestID does not exist

7.1.4. Asynchronous Response - Negative

Description Person FI responds with error to a PISP request for a new consent

Method PATCH

URL /consents/<consentID>/error

Request Content-type application/json

headers
Charset UTF-8

Authorization Basic

Header Field Type Required Description

parameters
Sender- String(11) true [pseudo] BIC of Payer Person FI
Participant-
Code

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 28 OF 32

 Receiver- String(11) true [pseudo] BIC of PISP
Participant-
Code

X-Request-ID UUID as true UUID defined by agent sending

String(36) the consent revocation request
(7.1.2) and then used in
responses (7.1.3/7.1.4)

Sender-User- String(12) true Code of sending user

Code

Body {
errorInformation : {
errorCode: "10",
errorDescription: " Consent revocation error.
Consent does not exist or has invalid status"
}
}

Body Field Type Required Description

description
errorCode String true Error code as per paragraph 10

errorDescriptio String true Error description as per

n paragraph 10

Response 200 OK Success

type
404 Not found Given consentRequestID does not exist

7.2. Revocation from Payer Person FI Side

7.2.1. Flow

Figure 9. Consent Revocation from FI Side

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 29 OF 32

7.2.2. Delivery of Revocation Information
Equivalent to the ones described in 7.1.3 and 7.1.4.

8. Payment Initiation Request

As Payment Initiation Request is processed over message exchange core, it is included here as
auxiliary information. The aim is to illustrate how PIR cryptogram is to be composed and verified.

Figure 10. Payment Initiation Request

9. Composing a Challenge
9.1. Challenge for Credentials Generation

a) Build the srsJson JSON object:

{
“authToken”: “<Secret yielded from authentication over Web or
OTP>”
}
b) Convert srsJson to a string representation using an RFC-8785 Canonical JSON format. (Refer to
https://tools.ietf.org/html/rfc8785 Appendix G for sample)

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 30 OF 32

c) Calculate a SHA-256 hash of the canonicalized JSON, i.e. SHA256(CJSON(srsJson)).

9.2. Challenge for Consent Finalization

a) Build the srsJson JSON object:

{
“scopes”: “<SCOPES>”
}

b) Convert srsJson to a string representation using a RFC-8785 Canonical JSON format.

c) Calculate a SHA-256 hash of the canonicalized JSON, i.e. SHA256(CJSON(srsJson)).

9.3. Challenge for PIR Cryptogram

d) Build the JSON object srsJson:

{
“sourceAccount”: “<debtor account number from PIR>”,
“destinationAccount”: “<creditor account number from
PIR>”,
“destinationFI”: “<creditor agent BIC from IR>”,
“amount”: “<PIR amount>”,
“currency”: “<PIR currency>”
}

e) Convert srsJson to a string representation using a RFC-8785 Canonical JSON format.

f) Calculate a SHA-256 hash of the canonicalized JSON, i.e. SHA256(CJSON(srsJson)).

10. Error codes

Error Description
code
1 Consent request error. Customer not found or has invalid status
Consent request error. Authentication system is temporarily unavailable. Try
2
again later
3 Authentication error. Customer public key not recognized
4 Authentication error. Invalid customer signature or secret value
5 FI internal error. Cannot store customer public key
6 Consent granting error. Customer has no suitable accounts
Valid consent already exists for the given PISP. Revoke current consent before
7
requesting a new one

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 31 OF 32

 8 Consent finalization error. Can not verify customer signature
9 Consent finalization error. Consent does not exist or can not be finalized
10 Consent revocation error. Consent does not exist or has invalid status

11. Authentication

Authentication is carried out using an access token in JWT format. To obtain an access token, participant
needs to request it specifying Client token.
In response, Access server performs password-based authentication and issues an access token with short
lifetime and refresh token with long lifetime.
Refresh token is used to obtain additional access tokens on demand without sending user’s password.
Participant can send request to Access server for a new access token based on a previously issued and valid
refresh token without specifying user's password.

Refer to “IPS Messaging REST API specification”, chapter 4 ‘Authentication’ for detailed description of
methods to retrieve token.

CONSENT MANAGEMENT REST API SPECIFICATION V1.0 PAGE 32 OF 32