Data consents authorise ongoing access to customer account information. This page covers consent status, duration, and management.
| Status | Description | Terminal? |
|---|---|---|
GatewayAwaitingSubmission | Waiting for customer to begin approval | No |
AwaitingAuthorisation | Waiting for customer approval at bank | No |
Authorised | Customer approved - data can be accessed | No |
Consumed | The consented action is complete: the consent period ended at its expiration_date_time. Retrieving data never consumes a Data consent | Yes |
GatewayTimeout | Gateway session expired (after 15 minutes) before a bank was chosen | Yes (Failure) |
Rejected | Declined by the customer or bank, or the authorisation window elapsed | Yes (Failure) |
Revoked | Consent revoked by you (DELETE) or by the customer at their bank | Yes (Failure) |
| From State | To State | Cause |
|---|---|---|
GatewayAwaitingSubmission | AwaitingAuthorisation | Customer chose their bank at the Gateway |
GatewayAwaitingSubmission | Rejected | Customer declined at the Gateway |
GatewayAwaitingSubmission | GatewayTimeout | Gateway session cutoff elapsed before bank selection |
AwaitingAuthorisation | Authorised | Customer approved |
AwaitingAuthorisation | Rejected | Customer or bank declined, or the authorisation window elapsed |
Authorised | Consumed | expiration_date_time reached |
GatewayAwaitingSubmission | Revoked | Revoked by you (DELETE) before the customer chose a bank |
AwaitingAuthorisation | Revoked | Revoked by you (DELETE) before the customer finished |
Authorised | Revoked | Revoked by you (DELETE) or by the customer at their bank |
Only Gateway Flow consents reach GatewayAwaitingSubmission.
Terminal statuses (Consumed, GatewayTimeout, Rejected, Revoked) are permanent. A terminal consent can't be used to access accounts or retrieve data, can't be reused and can't be recovered - create a new consent.
GET /v1/consents/{consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}
Polling guidance:
callback_url and check thenThe response carries status, status_update_date_time, creation_date_time, flow, permissions, the three date-time fields below, approved_requests and hashed_customer_identifier; see Check the Consent Status for an example.
Data consents use three date-time fields:
| Field | Description |
|---|---|
start_date_time | Start of the window of data the consent covers: the earliest transactions and statements you can retrieve |
end_date_time | End of the window of data the consent covers: the latest transactions and statements you can retrieve |
expiration_date_time | When access ends and the consent becomes Consumed. Optional; omit it for a consent that doesn't expire |
start_date_time and end_date_time limit which data you can read; expiration_date_time limits how long you can read it. Your transaction and statement date filters must sit inside the start-to-end window. How far back you can read transactions is set by start_date_time; if you leave it out, the customer's bank decides how much history it returns.
All date-time fields must be ISO 8601 format with timezone offset: 2026-03-20T15:30:00+13:00. When you create a consent, start_date_time can't be in the future, end_date_time must be after today (New Zealand date; leave it out to read up to the latest available transaction), and the two must fall on different dates (New Zealand time). expiration_date_time can't fall on the day the consent is created, or before start_date_time or end_date_time. A consent that breaks one of these rules is rejected with 400; the codes are on the Error Codes page.
Duration Notes
start_date_time no more than 2 years back| Flow | Timeout |
|---|---|
| Gateway Flow | 15 minutes (by default) while the customer is still choosing a bank. Once they choose one, that bank's redirect or decoupled window applies |
| Redirect Flow | Set per bank, up to 10 minutes |
| Decoupled Flow | Set per bank, from about 4 minutes |
The redirect and decoupled windows are configured per bank and change as banks change their own limits, so treat them as per-bank values rather than hard-coding a timeout — see Timeouts and Deadlines.
A consent that is never authorised at the bank ends as Rejected. A Gateway Flow consent abandoned before the customer picks a bank ends as GatewayTimeout instead.
To read new data later, for example each night or whenever the customer opens your app, call the data endpoints again with the same consent_id. The customer doesn't need to do anything: an Authorised consent can be used as often as you need until it expires or is revoked. Transactions booked since the customer authorised are included, up to end_date_time if you set one; without it, new transactions keep becoming readable.
Once the consent is Consumed (its expiration_date_time has passed) or Revoked, or the bank ends it (data calls then fail with 403), create a new consent and ask the customer to authorise it again.
When consent expires: Create a new consent. Attempting to use an expired consent returns a 403 error (BDT412).
Detecting expiry or revocation:
Retrieve the consent with GET /v1/consents/{consent_id} to see its current status. A data call on a consent that isn't Authorised fails with a code that says why (for example revoked or expired); create a new consent. See 403 Forbidden for the codes.
You must provide customers with the ability to view and revoke active consents through the same channel(s) where consent was created:
Revoke (cancel) a consent:
DELETE /v1/consents/{consent_id} HTTP/1.1
Host: sandbox.data.blinkpay.co.nz
Authorization: Bearer {access_token}
Which statuses accept a revoke:
A revoke applies to a consent that hasn't reached a final status (GatewayAwaitingSubmission, AwaitingAuthorisation or Authorised) and returns 204 No Content. A consent in a final status can't be revoked: the call returns an error and the status is unchanged. See Error Codes for the codes.