API Standards

Our APIs support multiple Open Banking standards out of the box. Request responses in the format your region requires—UK OBIE, EU Berlin Group, US FDX, and more.

Overview

Rather than maintaining separate API endpoints for each standard, Hamster Bank provides a unified API that can respond in different formats based on your request. This simplifies integration for TPPs operating across multiple jurisdictions.

Default Format

If no standard is specified, responses use the UK Open Banking (OBIE) format as the default.

Supported Standards

UK Open Banking (OBIE)

obie

UK Open Banking Implementation Entity standard
Read/Write API v3.1.x compliant
Sort Code + Account Number identifiers
GBP as primary currency

Berlin Group (PSD2)

berlin

NextGenPSD2 framework compliant
IBAN-based account identification
Multi-currency EUR support
ASPSP consent model

Financial Data Exchange (FDX)

fdx

FDX API standard v5.x
ABA routing number format
USD as primary currency
Section 1033 compliant

Payments NZ

nz

API Centre standards compliant
BECS bank-branch-account format
NZD as primary currency
NZ-specific consent types

Consumer Data Right (CDR)

cdr

Australian CDR compliant
BSB + Account Number format
PayID support
AUD as primary currency

Requesting a Format

Specify your desired response format using either an HTTP header or query parameter:

Option 1: HTTP Header (Recommended)

Set the X-Open-Banking-Standard header on your request:

curl -X GET "https://api.hamsterbank.ai/open-banking/v1/accounts" \\
  -H "Authorization: Bearer {access_token}" \\
  -H "X-Consent-ID: {consent_id}" \\
  -H "X-Open-Banking-Standard: berlin"

Option 2: Query Parameter

Alternatively, add the standard as a query parameter:

curl -X GET "https://api.hamsterbank.ai/open-banking/v1/accounts?standard=fdx" \\
  -H "Authorization: Bearer {access_token}" \\
  -H "X-Consent-ID: {consent_id}"

Standard Values

Value	Standard	Region
`obie`	UK Open Banking	United Kingdom
`berlin`	Berlin Group NextGenPSD2	European Union
`fdx`	Financial Data Exchange	United States
`nz`	Payments NZ API Centre	New Zealand
`cdr`	Consumer Data Right	Australia

Response Format Differences

Each standard has different conventions for field names, data structures, and identifiers:

Account Response Example

OBIEUK Open Banking

{
  "Data": {
    "Account": [
      {
        "AccountId": "acc_1234567890",
        "Status": "Enabled",
        "StatusUpdateDateTime": "2024-01-15T10:30:00Z",
        "Currency": "GBP",
        "AccountType": "Personal",
        "AccountSubType": "CurrentAccount",
        "Nickname": "Main Account",
        "Account": [
          {
            "SchemeName": "UK.OBIE.SortCodeAccountNumber",
            "Identification": "608371-12345678",
            "Name": "John Doe"
          }
        ]
      }
    ]
  },
  "Links": {
    "Self": "/accounts"
  }
}

BerlinEU PSD2

{
  "accounts": [
    {
      "resourceId": "acc_1234567890",
      "iban": "GB82HMBK60837112345678",
      "currency": "GBP",
      "name": "Main Account",
      "product": "Current Account",
      "cashAccountType": "CACC",
      "status": "enabled",
      "_links": {
        "balances": "/accounts/acc_1234567890/balances",
        "transactions": "/accounts/acc_1234567890/transactions"
      }
    }
  ]
}

FDXUS

{
  "accounts": [
    {
      "accountId": "acc_1234567890",
      "accountType": "CHECKING",
      "accountNumber": "12345678",
      "routingTransitNumber": "608371",
      "accountNickname": "Main Account",
      "status": "OPEN",
      "currency": {
        "currencyCode": "GBP"
      },
      "fiAttributes": [
        {
          "name": "accountHolderName",
          "value": "John Doe"
        }
      ]
    }
  ],
  "page": {
    "nextOffset": null,
    "total": 1
  }
}

Account Identifier Schemes

Different regions use different account identification schemes:

Scheme	Format	Region	Example
`UK.OBIE.SortCodeAccountNumber`	6-digit sort code + 8-digit account	UK	`608371-12345678`
`IBAN`	International Bank Account Number	EU/Global	`GB82HMBK60837112345678`
`BBAN`	Basic Bank Account Number	Various	`HMBK60837112345678`
`NZ.BECS`	Bank-Branch-Account-Suffix	NZ	`01-1234-1234567-00`
`AU.BSB`	BSB + Account Number	AU	`012-345 123456789`
`AU.PayID`	PayID (email, mobile, ABN)	AU	`john@example.com`
`US.ABA`	ABA Routing + Account	US	`021000021-123456789`

Transaction Type Mapping

Transaction types are mapped to each standard's terminology:

Internal Type	OBIE	Berlin	FDX
Credit	`Credit`	`CRDT`	`CREDIT`
Debit	`Debit`	`DBIT`	`DEBIT`
Standing Order	`StandingOrder`	`PMNT`	`RECURRING`
Direct Debit	`DirectDebit`	`DDEP`	`DIRECTDEBIT`
Card Payment	`CardPayment`	`CARD`	`CARDPAYMENT`
ATM Withdrawal	`CashWithdrawal`	`CWDL`	`ATMWITHDRAWAL`

Balance Type Mapping

Balance types vary by standard:

Type	OBIE	Berlin	FDX
Available Balance	`InterimAvailable`	`interimAvailable`	`AVAILABLE`
Booked Balance	`InterimBooked`	`interimBooked`	`LEDGER`
Expected Balance	`Expected`	`expected`	`CURRENT`
Credit Line	`CreditLine`	`creditLimit`	`CREDITLINE`

Response Headers

The response includes headers indicating which standard was used:

Header	Description	Example
`X-Open-Banking-Standard`	The standard used for the response	`berlin`
`X-Open-Banking-Version`	Version of the standard	`1.3.6`

Best Practices

1. Choose One Standard Per Integration

While you can mix standards, it's cleaner to choose one standard per application or user base. This simplifies your data handling and reduces mapping complexity.

2. Store Data in Canonical Form

If you support multiple markets, store data using our internal canonical format and transform to region-specific formats only when displaying to users or syncing with regional systems.

3. Handle All Identifier Formats

Your application should gracefully handle different account identifier schemes. An account may have multiple identifiers (e.g., both IBAN and Sort Code) depending on the standard.

4. Set Standard at Client Level

Consider configuring the default standard during TPP registration. This way you don't need to specify it on every request—just override when needed.

Error Handling

If you request an unsupported standard, you'll receive an error:

{
  "code": "INVALID_STANDARD",
  "message": "Unsupported Open Banking standard: 'xyz'. Supported values: obie, berlin, fdx, nz, cdr",
  "path": "X-Open-Banking-Standard"
}

The API returns HTTP 400 Bad Request with this error. Check the supported standards table above and ensure your header or query parameter value is correct.