Getting Started

Welcome to the Hamster Bank Open Banking API. This guide will help you get up and running in minutes.

Overview

Our Open Banking APIs allow you to access account information, initiate payments, and confirm funds on behalf of your customers. We support three main services:

Account Information Service (AIS) - Read account details, balances, and transactions
Payment Initiation Service (PIS) - Initiate domestic and international payments
Confirmation of Funds (CoF) - Check if sufficient funds are available

Prerequisites

Before you begin, you'll need:

A registered Third-Party Provider (TPP) with the appropriate regulatory authorizations
A Software Statement Assertion (SSA) from a supported directory
An understanding of OAuth 2.0 and OpenID Connect

Sandbox Access

For testing purposes, you can use our sandbox environment without regulatory authorization. Register for sandbox credentials in the dashboard.

Step 1: Register Your Application

We support Dynamic Client Registration (DCR) as specified in RFC 7591. To register your application:

curl -X POST "https://api.hamsterbank.ai/register" \\
  -H "Content-Type: application/json" \\
  -d '{
    "software_statement": "<your-ssa-jwt>",
    "redirect_uris": ["https://your-app.com/callback"],
    "token_endpoint_auth_method": "private_key_jwt",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"]
  }'

A successful registration returns your client credentials:

{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_id_issued_at": 1702512000,
  "registration_access_token": "reg_token_...",
  "registration_client_uri": "/register/550e8400-e29b-41d4-a716-446655440000",
  "redirect_uris": ["https://your-app.com/callback"],
  "scope": "openid accounts transactions",
  "token_endpoint_auth_method": "private_key_jwt"
}

Step 2: Generate API Keys

After registration, log into the developer dashboard to generate API keys for sandbox and production environments.

Sandbox vs Production

Sandbox

• Test data only
• No regulatory requirements
• Rate limits: 100 req/min

Production

• Real customer data
• TPP authorization required
• Rate limits: 1000 req/min

Step 3: Authenticate

Our APIs use OAuth 2.0 with OpenID Connect. The typical flow is:

Create a consent request specifying the permissions you need
Redirect the customer to our authorization endpoint
Customer authenticates and approves the consent
Receive an authorization code at your redirect URI
Exchange the code for access and refresh tokens

# Exchange authorization code for tokens
curl -X POST "https://api.hamsterbank.ai/oauth/token" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  -d "grant_type=authorization_code" \\
  -d "code={authorization_code}" \\
  -d "redirect_uri=https://your-app.com/callback" \\
  -d "client_id={client_id}" \\
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \\
  -d "client_assertion={signed_jwt}"

See the Authentication guide for detailed instructions.

Step 4: Make Your First API Call

With your access token, you can now make API requests. Let's fetch a list of accounts:

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

The response contains a list of accounts the customer has consented to share:

{
  "data": [
    {
      "account_id": "acc_1234567890",
      "status": "enabled",
      "currency": "GBP",
      "account_type": "current",
      "nickname": "Main Account",
      "identifiers": [
        {
          "scheme": "SortCodeAccountNumber",
          "id": "608371-12345678"
        },
        {
          "scheme": "IBAN",
          "id": "GB33BUKB60837112345678"
        }
      ]
    }
  ],
  "links": {
    "self": "/accounts"
  }
}

Next Steps

Now that you've made your first API call, explore our comprehensive documentation: