The process described on this page is outdated. API clients do not need to implement it anymore.
An important part of our commitment to consumer’s privacy and security is the process we use to collect explicit consent from them, before we make data available to our API subscribers.
This tutorial explains how you can collect user's consents and share it with us.
Before we start, here is the good news: the whole process is implemented in just two API calls.
Let’s consider, as an example, the case when you want to access a consumer banking data via our Transactionz product. Everything said here also applies to the other use cases we support (Auth, PayMeBack, etc.).
When the consumer is using your app or website, you will have to show a pop-up screen with the consent language. It’s important that the language is very explicit about what data you collect, how you use it, and what are the parties involved in the process (e.g., Pentadata and the selected financial institution).
If you are unsure about the language, feel free to ask us, and we can provide you with templates. If you are curious, listen to the interview that our Chief Legal Counselor gave to the Digital Commerce Alliance.
The consent screen must also contain a button (or similar actionable item) that the consumer needs to click to confirm they read and understood the terms. When they do that, it’s time to implement the procedure to share the consent with us.
GET /consents/signature/77485765/banking
--header 'Authorization: Bearer ey***'
Here the integer 77485765 is the Person ID for this consumer. The string “banking” at the end of the URL is the use case you want to permission. Possible use cases are:
The response will contain a string named “signature”:
{"signature": "843nqv8583v57e957e9v75e957nve9halnthuh"}
You have to pass this string into your frontend application, and when the user clicks to accept the terms, you have to run the following request from your frontend to our API:
POST /consents
--header 'Content-Type: application/json' \
--data-raw '{
"signature": "843nqv8583v57e957e9v75e957nve9halnthuh",
"usecase": "banking",
"text": "I have read and understood the terms in the privacy policy at ..."
}'
Here the “signature” value must match the one returned by the previous call, and “text” must be the language you show to the user, or a URL to your privacy policy.
It’s very important that the second call is executed from the frontend application (web or mobile). We need to know that it's really the user clicking on the consent form, and not your servers doing it without their consent. We will save and audit the consents you send for regulatory and compliance reasons.
That’s it. The whole procedure is implemented in two API requests.
Why do I need to run the first step from the backends?
The first request that you send, the GET /consents/signature, is authenticated through JWT. As such, it must be sent from the servers, for security reasons. You should never, never put the JWT in the frontend app because a tech-savvy user of your app might notice that and use it to run API requests pretending to be you.
How is the second request safely run from the frontend application?
That’s what the signature object is for. Technically, it’s an authorization mean, like the JWT. However, unlike the JWT, the signature only allows requests to POST /consents – nothing else – and it expires after a few minutes.
Notice that this request doesn’t need the JWT header.
Why can’t I run the POST /consents, with signature, from the backends?
It would be a violation of your user privacy. We need to know it’s really them clicking on the confirmation button in your app. The request to our API must come from the location the user is at.
What data do you save?
We save the language you send in the “text” field. Feel free to add the language to a public web page and simply send the URL of that page, instead of the entire text (it saves some bandwidth!).
We also save the timestamp of the request; the use case and Person ID; and a trace of the API request that allows us to check and prove that it was the consumer sending the request.
Connect with us
Connect With Us
