> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Consents

> How consents work in open banking, their lifecycle, status transitions, and management for data access and payments.

## 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 valid `consent-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}`              |

<Info>
  Despite the differences, the authorisation flow is the same for both. See [Open Banking 101](/concepts/open-banking-101) for an overview of the flow.
</Info>

## 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](/open-banking-flow/user-authorisation/overview).

<Steps>
  <Step title="Create">
    Your app requests a consent (for data access or a payment).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Receive token">
    On success, you receive a consent token to use in API calls.
  </Step>

  <Step title="Use">
    Pass the token in the Consent header to access data or execute a payment.
  </Step>

  <Step title="Consent ends">
    AIS consents expire after 90 days (UK) or 180 days (EEA). PIS consents
    are single-use. Users can revoke at any time.
  </Step>
</Steps>

AIS and PIS consents follow different status paths after authorisation. See the detailed lifecycles:

* [Payment Consent lifecycle](/payments/payment-resources/payment-consents#authorisation-status)
* [Data Consent lifecycle](/data/financial-data-resources/financial-data-consents#status-transitions)

### 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                          |

<Note>
  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.
</Note>

## 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 Consent](/api-reference/authorisations/re-authorise-account-consent)

### Reconfirmation (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 with `lastConfirmedAt` 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 confirmed
* `reconfirmBy`: Deadline for the next reconfirmation

<Warning>
  If reconfirmation is not received by the `reconfirmBy` date, Yapily will block further data access for Yapily Connect customers. Reconfirm before this deadline to avoid interruption.
</Warning>

**Learn more:**

* [Extend Consent](/api-reference/consents/extend-consent)
* [90 Day AIS Consent Changes](/data/financial-data-resources/uk-data-consent-changes)

### 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 Restrictions](/data/financial-data-resources/data-restrictions)

### Revoked consents

Users can revoke consent at their bank at any time, bypassing your application entirely. When this happens, the consent status may still show `AUTHORIZED` 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 in `PENDING` 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](/payments/payment-resources/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                   |

<Tip>
  For the complete field-by-field schema, see the [Consent object in the API Reference](/api-reference/consents/get-consent).
</Tip>

## 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](/open-banking-flow/user-authorisation/multiple-consents).
* **Reconfirmation vs re-authorisation:** Reconfirmation (UK only) does not require bank login. Re-authorisation does.

## Related documentation

* [Financial Data Consents (detailed AIS)](/data/financial-data-resources/financial-data-consents)
* [Payment Consents (detailed PIS)](/payments/payment-resources/payment-consents)
* [User Authorisation Flows](/open-banking-flow/user-authorisation/overview)
* [90 Day AIS Consent Changes (UK)](/data/financial-data-resources/uk-data-consent-changes)
* [Multiple Consents](/open-banking-flow/user-authorisation/multiple-consents)
* [Hosted Pages Data Tutorial](/tools-and-services/hosted-pages/payment-tutorial-hosted-data)