What is a consent?
A consent is the customer’s explicit permission for your application to either access their financial data or make a payment from their account. Unlike traditional payment methods that rely on stored credentials, open banking requires explicit, time-bound customer authorisation for each data access or payment interaction. In Yapily’s API, a consent is an object that represents this permission. It has a status, a token, and a scope. You need a validconsent-token before calling any data or payment endpoint. No data or payment endpoint can be accessed without a valid consent token. Pass it in the Consent header on each request.
With Hosted Pages, you receive the consent token automatically at the end of the flow. With the Direct API, you manage the consent flow yourself.
AIS consent vs PIS consent
| AIS Consent (Data Access) | PIS Consent (Payment) | |
|---|---|---|
| Purpose | Access accounts, balances, transactions | Execute a payment |
| Validity | Reusable for up to 90 days (UK) or 180 days (EEA) | Single-use only |
| Scope | Covers multiple API calls to financial data endpoints | Covers one payment execution plus status checks |
| Reconfirmation | Required every 90 days in UK (new regulation) | Not applicable |
| Re-authorisation | Possible when consent expires or fails | Not applicable. Create a new consent. |
| Obtaining via Hosted | Hosted handles the flow, returns consent token | Hosted handles the entire payment including consent |
| Obtaining via API | POST /account-auth-requests | POST /payment-auth-requests |
| Token used in | GET /accounts, GET /accounts/{id}/transactions, enrichment endpoints | POST /payments, GET /payments/{id} |
Despite the differences, the authorisation flow is the same for both. See Open Banking 101 for an overview of the flow.
Consent lifecycle
A consent moves through several stages from creation to completion. The exact statuses differ between AIS and PIS consents and depend on the authorisation flow.Authorise
The user is redirected to their bank, logs in, and approves. If the
user declines, the consent is rejected. If something goes wrong
during authentication, the consent fails.
Status reference
| Status | Meaning | What to do |
|---|---|---|
AWAITING_AUTHORIZATION | Consent created, waiting for user to approve at bank | Redirect user to authorisationUrl |
AUTHORIZED | User has approved. Consent token is valid. | Use the token to make API calls |
REJECTED | User declined consent at the bank | Show user-friendly message, offer to retry |
FAILED | Error during authorisation | Check error details, may be retryable |
EXPIRED | Consent has reached its time limit | Request re-authorisation |
AWAITING_SCA_CODE | Embedded flow: waiting for SCA code from user | Submit the code via update endpoint |
AWAITING_SCA_METHOD | Embedded flow: user must select SCA method | Present options, submit selection |
AWAITING_DECOUPLING | Decoupled flow: user must approve on another device | Poll for status change |
AWAITING_RE_AUTHORIZATION | Re-authorisation in progress | Redirect user to the bank to re-authorise |
AWAITING_FURTHER_AUTHORIZATION | Consent is authorised by one of the account holders | Wait for all users complete the flow |
AWAITING_DECOUPLED_PRE_AUTHORIZATION | Decoupled flow: Authentication initiated | Redirect user to the bank |
AWAITING_PRE_AUTHORIZATION | Pre-Auth flow: Authentication initiated | Redirect user to the bank |
AWAITING_DECOUPLED_AUTHORIZATION | Decoupled flow: Authentication initiated | Wait for user to complete the flow on another device |
PRE_AUTHORIZED | Pre-Auth flow: User has approved. Consent token is valid | Continue on the Pre Auth flow steps |
CONSUMED | Payment is executed | This is a terminal state of a payment |
INVALID | Invalid consent | Check the consent details. Create a new consent if needed |
REVOKED | User revoked consent directly at their bank | Cannot be restored. Create a new consent. |
UNKNOWN | Default enum value | Should not occur in normal flows |
If you are using Hosted Pages, status transitions are managed for you. You receive the final outcome (authorised consent token, or a failure status) via webhook or polling.
Managing AIS consents
Consent expiry and re-authorisation
AIS consents have limited validity: 90 days in the UK, 180 days in the EEA. Use the re-authorisation endpoint to request the user re-approve access. Re-auth follows the same redirect flow as the original consent. Important: Re-auth is only supported for redirect flows, not embedded flows. See: Re-authorise Account ConsentReconfirmation (UK only)
FCA regulation requires UK AISPs to reconfirm consent every 90 days. This is separate from re-authorisation. Reconfirmation does not require the user to visit their bank. If using Yapily Connect: Call the Extend Consent endpoint withlastConfirmedAt to record when you last confirmed with the user that they still want data access.
If you are a regulated AISP: Capture reconfirmation in your own UI (a simple “yes, I still want you to access my data” prompt), then call the same endpoint.
Key fields:
lastConfirmedAt: Timestamp when the user last confirmedreconfirmBy: Deadline for the next reconfirmation
Historical data window
Some banks limit historical transaction access to the first 5 minutes after consent creation. This is a bank-level restriction that Yapily cannot override. Recommendation: Retrieve and store historical data immediately after receiving the consent token. Do not wait hours or days to make your first data request if you need historical transactions. See: Data RestrictionsRevoked consents
Users can revoke consent at their bank at any time, bypassing your application entirely. When this happens, the consent status may still showAUTHORIZED in Yapily’s system, but API calls will return 403 Forbidden.
If you get persistent 403 errors on an AUTHORIZED consent, the consent has likely been revoked at the bank. You cannot restore a revoked consent. Create a new consent to regain access.
Managing PIS consents
Single-use nature
PIS consent tokens are single-use. Once used to execute a payment, the token can only be used to check payment status. You cannot use the same consent token to make another payment. For each new payment, you need a new consent. This is a regulatory requirement, not a Yapily limitation.Multiple authorisations
Some business and joint accounts require more than one person to approve a payment. When this happens, the payment remains inPENDING status until all authorisations are received.
The multiAuthorisationStatus object on the payment shows progress. You can see how many authorisations are required and how many have been completed.
Additional authorisations happen offline (phone, email, SMS) and are outside Yapily’s control. You cannot trigger or expedite these. Monitor via GET /payments/{paymentId} or webhooks.
See: Payment Consents
Consent object key fields
| Field | What it means | When you’ll use it |
|---|---|---|
id | Unique identifier for this consent | Store this to manage the consent lifecycle |
consentToken | The token you pass as the Consent header in API calls | Required for every data or payment API call |
status | Current state of the consent (see status table above) | Check before making API calls |
institutionId | The bank this consent is for | A consent is bank-specific, one per institution |
featureScope | What the consent covers (e.g., ACCOUNT, ACCOUNT_TRANSACTIONS) | Determines which API endpoints you can call |
lastConfirmedAt | (AIS, UK) When the user last reconfirmed consent | Use to manage reconfirmation schedule |
reconfirmBy | (AIS, UK) Deadline for next reconfirmation | Set reminders to avoid access interruption |
createdAt | When the consent was created | Track consent age |
expiresAt | When the consent will expire | Plan re-auth before this date |
Common pitfalls
The following issues are frequently encountered during integration:- AUTHORIZED but getting 403 errors: The consent was likely revoked at the bank. Create a new consent.
- Cannot retrieve historical transactions: Many banks limit historical access to 5 minutes after consent creation. Retrieve data immediately.
- Consent expired unexpectedly: UK consents last 90 days, EEA 180 days. Re-authorise proactively before expiry.
- Multiple consent tokens returned: Some banks return one consent per account. See Multiple Consents.
- Reconfirmation vs re-authorisation: Reconfirmation (UK only) does not require bank login. Re-authorisation does.