Consents API

The Consents API allows you to create and manage customer consent requests. Consents are required before accessing any customer data or initiating payments.

Overview

Open Banking requires explicit customer consent for all data access and payment operations. The consent lifecycle involves:

1
Create Consent
TPP creates a consent request specifying required permissions
2
Customer Authorization
Customer is redirected to authorize the consent
3
Use Consent
Pass consent ID in X-Consent-ID header for API requests
4
Manage Lifecycle
Monitor expiry, handle revocation

Consent Types

There are four types of consents, each for different use cases:

Type	Code	Purpose	Max Duration
Account Access	`account-access`	Read account details, balances, transactions	90 days
Payment	`payment`	Initiate a single payment	Single use
Funds Confirmation	`funds-confirmation`	Check if funds are available	90 days
Enduring Payment	`enduring-payment`	Multiple payments to fixed beneficiary (NZ)	As specified

Create Consent

Create a new consent request. The consent starts in awaiting_authorization status until the customer authorizes it.

Account Access Consent

POST/consents

Create an account access consent for reading account data.

Request

{
  "consent_type": "account-access",
  "permissions": [
    "ReadAccounts",
    "ReadBalances",
    "ReadTransactions"
  ],
  "expiration_date": "2024-03-15T00:00:00Z",
  "transaction_from_date": "2023-01-01T00:00:00Z",
  "transaction_to_date": "2024-12-31T23:59:59Z"
}

Response

{
  "consent_id": "consent_ais_abc123",
  "consent_type": "account-access",
  "status": "awaiting_authorization",
  "permissions": [
    "ReadAccounts",
    "ReadBalances",
    "ReadTransactions"
  ],
  "expiration_date": "2024-03-15T00:00:00Z",
  "transaction_from_date": "2023-01-01T00:00:00Z",
  "transaction_to_date": "2024-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z",
  "authorization_url": "https://api.hamsterbank.ai/oauth/authorize?consent_id=consent_ais_abc123&..."
}

Payment Consent

POST/consents

Create a payment consent for initiating a single payment.

Request

{
  "consent_type": "payment",
  "payment_details": {
    "instructed_amount": {
      "amount": "100.00",
      "currency": "GBP"
    },
    "creditor_account": {
      "scheme": "SortCodeAccountNumber",
      "id": "123456-87654321",
      "name": "Jane Smith"
    },
    "remittance_information": {
      "reference": "Invoice-123"
    }
  }
}

Response

{
  "consent_id": "consent_pis_xyz789",
  "consent_type": "payment",
  "status": "awaiting_authorization",
  "payment_details": {
    "instructed_amount": {
      "amount": "100.00",
      "currency": "GBP"
    },
    "creditor_account": {
      "scheme": "SortCodeAccountNumber",
      "id": "123456-87654321",
      "name": "Jane Smith"
    }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "expiration_date": "2024-01-16T10:30:00Z",
  "authorization_url": "https://api.hamsterbank.ai/oauth/authorize?consent_id=consent_pis_xyz789&..."
}

Funds Confirmation Consent

POST/consents

Create a consent for checking funds availability.

Request

{
  "consent_type": "funds-confirmation",
  "permissions": ["FundsConfirmation"],
  "expiration_date": "2024-03-15T00:00:00Z"
}

Response

{
  "consent_id": "consent_cof_def456",
  "consent_type": "funds-confirmation",
  "status": "awaiting_authorization",
  "permissions": ["FundsConfirmation"],
  "created_at": "2024-01-15T10:30:00Z",
  "expiration_date": "2024-03-15T00:00:00Z",
  "authorization_url": "https://api.hamsterbank.ai/oauth/authorize?consent_id=consent_cof_def456&..."
}

Get Consent

Retrieve the current status and details of a consent.

GET/consents/{consentId}

Get consent details by ID.

Request

GET /consents/consent_ais_abc123
Authorization: Bearer {access_token}

Response

{
  "consent_id": "consent_ais_abc123",
  "consent_type": "account-access",
  "status": "authorized",
  "tpp_client_id": "tpp_12345",
  "customer_id": "cust_67890",
  "permissions": [
    "ReadAccounts",
    "ReadBalances",
    "ReadTransactions"
  ],
  "account_ids": [
    "acc_111",
    "acc_222"
  ],
  "expiration_date": "2024-03-15T00:00:00Z",
  "transaction_from_date": "2023-01-01T00:00:00Z",
  "transaction_to_date": "2024-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z",
  "authorized_at": "2024-01-15T10:35:00Z"
}

Delete Consent

Revoke a consent. This immediately invalidates the consent and any tokens associated with it.

DELETE/consents/{consentId}

Revoke a consent.

Request

DELETE /consents/consent_ais_abc123
Authorization: Bearer {access_token}

Response

HTTP/1.1 204 No Content

Consent Revocation

Customers can also revoke consents directly through their banking app or online banking. Your application should handle 403 errors gracefully in case a consent has been revoked.

Consent Status

Consents transition through the following statuses:

Status	Description	Usable
awaiting_authorization	Consent created, waiting for customer approval	No
authorized	Customer has approved the consent	Yes
rejected	Customer declined the consent	No
revoked	Consent revoked by customer or TPP	No
expired	Consent has passed its expiration date	No
consumed	Single-use consent has been used (payment consents)	No

Permissions Reference

Available permissions for account-access consents:

Account Permissions

Permission	Description	Grants Access To
`ReadAccounts`	View account list and details	List Accounts, Get Account
`ReadAccountsBasic`	View basic account information only	List Accounts (limited fields)
`ReadAccountsDetail`	View full account details	Get Account with all fields

Balance Permissions

Permission	Description	Grants Access To
`ReadBalances`	View account balances	Get Balances, Get All Balances

Transaction Permissions

Permission	Description	Grants Access To
`ReadTransactions`	View transaction history	Get Transactions, Get All Transactions
`ReadTransactionsBasic`	View basic transaction info	Transactions without merchant details
`ReadTransactionsDetail`	View full transaction details	Transactions with all fields

Other Permissions

Permission	Description	Grants Access To
`ReadStandingOrders`	View standing orders	Get Standing Orders
`ReadDirectDebits`	View direct debit mandates	Get Direct Debits
`ReadBeneficiaries`	View saved payees	Get Beneficiaries
`ReadProducts`	View product information	Get Products
`FundsConfirmation`	Check funds availability	Confirm Funds (CoF consents only)

Best Practices

Request only the permissions you need - customers are more likely to approve minimal scopes
Store consent IDs securely and associate them with customer sessions
Implement consent expiry monitoring and prompt re-authorization before expiry
Handle consent revocation gracefully - check for 403 errors on every API call
For AIS consents, cache the account list to reduce unnecessary API calls
Use webhooks (when available) to be notified of consent status changes

Error Responses

Common error responses for the Consents API:

400

invalid_request

Missing or invalid request parameters

400

invalid_permissions

Requested permissions not valid for consent type

401

invalid_client

Client authentication failed

403

unauthorized_client

Client not authorized for this consent type

404

consent_not_found

Consent does not exist

409

consent_already_authorized

Cannot modify an authorized consent