Consent Lifecycle

Consents in BlinkPay follow a defined lifecycle from creation through authorisation to completion or termination. Understanding these states is crucial for proper error handling and user experience.

Consent States Overview

Consents progress through these states, and the starting state depends on your flow:

• Gateway Flow: GatewayAwaitingSubmission → AwaitingAuthorisation → Authorised → Consumed
• Redirect and Decoupled Flow: AwaitingAuthorisation → Authorised → Consumed
• Card payments authenticate with 3DS instead of at a bank, so they skip AwaitingAuthorisation: GatewayAwaitingSubmission → Authorised → Consumed
• Alternative endings: Rejected or Revoked - plus GatewayTimeout for a Gateway Flow consent abandoned before the customer picks a bank

State Descriptions

GatewayAwaitingSubmission

Initial state for Gateway Flow consents

The consent has been created and is waiting for the customer to be redirected to the Blink Gateway. This is a transient state that occurs immediately after consent creation.

Typical duration: Seconds (until redirect)

Next states:

• AwaitingAuthorisation - Customer selected their bank at the Gateway and was sent to it to authorise
• Authorised - Card payment only: 3DS authentication succeeded
• Rejected - Card payment only: 3DS authentication failed
• GatewayTimeout - The Gateway session cutoff elapsed before the customer chose a bank - see Authorisation timeouts

Merchant actions:

• Redirect customer to the redirect_uri returned in the consent response
• Display loading state or instruction to customer

AwaitingAuthorisation

Consent is waiting for customer approval at their bank

The consent has reached the customer's bank and is waiting for them to authenticate and approve the request. All three flows use this state, and they reach it differently:

• Redirect flow - the customer has been redirected to their bank's authorisation page
• Decoupled flow - the request has been pushed to the customer's banking app; there is no redirect
• Gateway flow - the customer has chosen their bank at the Gateway and has been sent on to it

Typical duration: 1-5 minutes, bounded by the authorisation window for that bank and flow - see Authorisation timeouts

Next states:

• Authorised - Customer approved the consent
• Rejected - Customer declined, the bank rejected it, or the authorisation window elapsed

Merchant actions:

• Display waiting/processing state to customer
• Don't poll while the customer is at their bank; read the consent when they return (every second if it isn't terminal yet). In the direct decoupled flow with no callback, poll every 5 seconds
• Have fallback for timeout scenarios

If the customer comes back to your site or app before the consent has left this state, don't revoke it or treat it as failed: they may still approve it in their banking app. Keep checking until the authorisation window ends, then reconcile.

Authorised

Customer has approved the consent

The customer successfully authenticated with their bank and approved the consent. The consent is now ready to be used for payments (single or enduring) or data access.

For single consents:

• Transitions to Consumed once the bank settles its payment, or rejects the payment after accepting it
• If the bank refuses the payment outright, the payment is Rejected and the consent stays Authorised, so you can create the payment again with a new idempotency-key
• For a bank quick payment, retrieve it with GET as soon as the customer returns (the gateway normally does this for you); that call completes the payment
• Must be paid within 48 hours of authorisation. After that it transitions to Rejected and can no longer be used, so create a new consent. A card payment holding a reservation is the exception: the reservation is released automatically instead

For enduring consents:

• Remains in Authorised state
• Can be used for multiple payments
• May transition to Revoked if customer or merchant cancels

For data consents:

• Remains in Authorised state
• Can be used to retrieve account data
• May transition to Revoked or expire naturally

Merchant actions:

• Create payment(s) using the consent_id
• For enduring consents, store the consent_id securely
• Detect revocation by reading the consent before each payment: a consent revoked at the bank shows as Revoked, and POST /payments returns 422 BP015. See Notifications

Consumed

The consented action is complete (Final state)

The consent cannot be used for further payments.

Applicable to:

• Single consents and quick payments - once the bank has made its final decision on the payment: it settled, or the bank rejected it after accepting it
• Enduring consents - once expiry_timestamp has passed

Consumed does not mean the payment has settled. It means the consented action is complete. A single consent whose payment the bank rejected after accepting it is also Consumed, with a Rejected payment. Use payment.status = AcceptedSettlementCompleted as the only signal that funds have settled. See the payment lifecycle settlement guide for details.

Merchant actions:

• Track the associated payment status via the embedded payments[] array or the payment endpoint
• No further actions possible with this consent
• Create new consent for additional payments

Rejected

The consent was declined, was never authorised in time, or was not paid in time (Final state)

The consent was rejected either by:

• Customer declining at the bank
• Bank rejecting due to validation errors
• Insufficient permissions or account issues
• Authentication failures
• The authorisation window elapsing before the customer approved it

Common reasons:

• Customer clicked "Cancel" or "Decline"
• Customer never completed authorisation - see Authorisation timeouts
• A single consent was not paid within 48 hours of authorisation
• Customer failed authentication too many times
• Account doesn't support requested operation
• Insufficient funds (for payment consents)
• Technical issues at the bank

Merchant actions:

• Display appropriate error message to customer
• Offer to retry with new consent
• Don't retry automatically (customer explicitly declined)

For quick payments, a rejected consent also creates a payment record with status: Rejected in the embedded payments[] array, so the payment status reflects the outcome for both authorised and rejected quick payments.

GatewayTimeout

Gateway session expired before the customer chose a bank (Final state)

The customer didn't select a bank within the Gateway session cutoff - see Authorisation timeouts. This state applies only while a Gateway Flow consent is still at the Gateway. Once the customer has reached a bank, an unauthorised consent ends as Rejected instead.

Common causes:

• Customer abandoned the flow before choosing a bank
• Customer closed the browser or app at the Gateway
• Technical issues prevented bank selection

Merchant actions:

• Inform customer the session expired
• Offer to restart the payment process
• Create new consent for retry

Revoked

Consent was cancelled (Final state)

The consent was explicitly revoked by either:

• The customer (through their bank or your application)
• The merchant (via API)
• The bank (due to account closure, etc.)

Revocation sources:

• Customer action at bank
• Merchant calling DELETE /payments/v1/single-consents/{consent_id} or DELETE /payments/v1/enduring-consents/{consent_id}
• Automatic revocation (account closure, etc.)

Merchant actions:

• Stop any scheduled payments using this consent
• Mark the consent revoked in your records (keep the ID for reconciliation)
• Notify customer if revoked by merchant
• Offer to create new consent if needed

A revocation made at the customer's bank is not pushed to you: it shows as Revoked when you next read the consent or attempt a payment. If the consent has an active Fixed Recurring Payment, the schedule is cancelled and you receive a fixed-recurring-payment-cancelled webhook.

Authorisation Timeouts

Every timer on both products is listed in Timeouts and Deadlines.

The time a customer has to authorise a consent is set per bank and per flow, not a single platform-wide figure. Windows currently run from about four to ten minutes, and are not always a whole number of minutes. Decoupled windows are usually the shorter of the two at a given bank, though not always. Read the live value for the bank you're sending the customer to from the bank metadata endpoint rather than assuming a fixed figure. Applying your own shorter cutoff is reasonable if it suits your checkout — just reconcile the consent afterwards rather than assuming it failed, since the customer may still authorise it.

Gateway Flow consents have a second, earlier cutoff - 15 minutes by default - that applies while the consent is still at the Gateway and the customer hasn't chosen a bank yet. Gateway Flow has no authorisation window of its own: once the customer picks a bank, that bank's redirect or decoupled window applies.

If the customer never returns, the consent ends as Rejected - or as GatewayTimeout if it was a Gateway Flow consent still waiting on bank selection. No payment is created and no funds move, so create a new consent if the customer wants to retry.

Status Changes

These are the status changes you can expect to observe, and what causes each one:

Only Gateway Flow consents reach GatewayAwaitingSubmission, so the first four rows never apply to a redirect or decoupled integration.

Terminal states (Consumed, Rejected, GatewayTimeout, Revoked) are permanent - a consent never moves out of one. You can't reuse a consumed single consent, reauthorise a rejected one, revive a timed-out one, or un-revoke a revoked one, so always create a new consent for retries.

Checking Consent Status

API Polling

Retrieve consent status via the GET endpoint:

GET /payments/v1/single-consents/{consent_id} HTTP/1.1
Host: sandbox.debit.blinkpay.co.nz
Authorization: Bearer {access_token}

Polling recommendations:

• Don't poll while the customer is at their bank. Use their return to your redirect URI, or the decoupled flow's callback_url, to know when to look, then read the consent and poll every second if it isn't terminal yet. In the direct decoupled flow with no callback, poll every 5 seconds.
• The consent-authorisation phase typically completes within a few minutes, bounded by the authorisation window for that bank and flow — see Authorisation timeouts.
• Once that window has elapsed, authorisation won't succeed. Ideally poll until the consent reaches a terminal state, since that is what confirms the outcome. If you'd rather stop at a cutoff of your own, make it at least as long as the bank's window and reconcile the consent afterwards rather than treating it as failed.
• Once a payment exists, poll it every second until it is AcceptedSettlementCompleted or Rejected, within your polling window.
• Consent status changes, including revocation, do not emit webhooks. See Notifications and Webhooks.

Callbacks (Decoupled Flow)

For Decoupled Flow, you can provide a callback_url in the consent request. BlinkPay calls it when the customer authorises, the bank rejects the consent, or the authorisation window times out. It is an unsigned GET with the consent ID as cid and no status, and it can arrive more than once or not at all, so always fetch the consent to read the outcome. See Consent Authorisation Callback.

Handling Terminal States

Enduring Consent Lifecycle

Enduring consents (AutoPay) have a different lifecycle pattern than single consents:

1. Create - Enduring consent created with period limits and optional expiry
2. Authorise - Customer approves the consent
3. Use - Create multiple payments over time (consent stays Authorised)
4. End - Consent transitions to Consumed once its expiry date has passed, or Revoked if cancelled

Key difference from single consents: Enduring consents remain in Authorised state for multiple payments until expiry or revocation.

Expiry Behaviour

• With expiry_timestamp: after that time the consent is Consumed, and a payment against it is rejected with 422 BP003
• Without expiry_timestamp: Consent remains Authorised indefinitely until explicitly revoked

A consent cannot be renewed or extended: to keep taking payments, create a new consent and ask the customer to authorise it. Payment limits apply per period, counted from from_timestamp; see Period Calculation.

Best Practices

• Always check consent status before creating a payment - verify it's Authorised
• Handle all terminal states (Consumed, Rejected, GatewayTimeout, Revoked) gracefully
• Create new consents for retries - never try to reuse terminal state consents
• Store consent IDs securely for enduring consents to enable future payments