Introduction

Welcome to the Opendeck API documentation. Build powerful financial applications with our comprehensive API and developer tools.

What is Opendeck?

Opendeck is an open-finance infrastructure platform built on top of payments. We provide APIs and tools for businesses and developers to integrate financial services, including:

  • Gaming & Gambling Payments - Process payments for online casinos, sportsbooks, esports platforms, and fantasy sports
  • Pension Payments - Enable users to make pension contributions through Open Banking
  • Utilities Payments - Manage utility bill payments with ML-powered affordability checks
  • Open Banking Integration - Connect to UK banks via PSD2-compliant APIs

Our ML-first infrastructure provides real-time affordability checks, usage predictions, and payment optimization to help you build smarter financial applications.

🔒

Secure by Default

Bank-grade encryption and PSD2 compliance

⚡

Fast & Reliable

99.9% uptime SLA with sub-100ms response times

🤖

ML-Powered

AI-driven affordability checks and predictions

Quick Start

Get Started in Minutes

Get started with the Opendeck API in minutes. Our RESTful API is designed for simplicity and power.

Base URL
https://api.opendeck.co.uk
View API Docs Code Examples

Authentication

Opendeck uses JWT-based authentication. Register a user account to get started.

Getting Your API Token

  1. Register a new user account via POST /api/auth/register
  2. Login to get your access token via POST /api/auth/login
  3. Include the token in the Authorization: Bearer YOUR_TOKEN header

API Categories

Authentication

Secure JWT-based authentication with OAuth2 support.

  • • POST /api/auth/register
  • • POST /api/auth/login
  • • POST /api/auth/logout
  • • GET /api/auth/me

Gaming & Gambling

Payment processing for gaming operators and platforms.

  • • POST /api/gaming/operators
  • • POST /api/gaming/transactions
  • • GET /api/gaming/stats
  • • POST /api/gaming/affordability

Pension Payments

Manage pension contributions and accounts.

  • • GET /api/pensions/accounts
  • • POST /api/pensions/pay
  • • GET /api/pensions/payments
  • • GET /api/pensions/providers

Utilities Payments

ML-powered utility bill payments with affordability checks.

  • • GET /api/utilities/accounts
  • • POST /api/utilities/pay
  • • GET /api/utilities/payments
  • • GET /api/utilities/providers

Open Banking

Connect to UK banks via Open Banking APIs.

  • • GET /api/banks
  • • GET /api/accounts
  • • POST /api/payments
  • • GET /api/analytics/spending

Events & Entertainment

Proprietary feature: Automatic pension micro-contributions (0.01%) from event payments.

  • • POST /api/events/venues
  • • POST /api/events/
  • • POST /api/events/payments
  • • GET /api/events/contributions
✨ Proprietary

Analytics & Insights

Financial analytics and risk assessment.

  • • GET /api/risk-assessment/{id}
  • • GET /api/business-insights/{id}
  • • GET /api/products
  • • GET /api/offers/{user_id}

Admin Dashboard

Platform management and monitoring.

  • • POST /api/admin/auth/login
  • • GET /api/admin/operators
  • • GET /api/admin/revenue
  • • GET /api/admin/transactions

API Request & Response Examples

Request 

curl -X POST https://api.opendeck.co.uk/api/gaming/operators \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Example Gaming Ltd",
    "trading_name": "Example Casino",
    "contact_email": "api@example.com",
    "contact_phone": "+44 20 1234 5678",
    "company_number": "12345678",
    "uk_gambling_license": "LIC123456"
  }'

Response

200 OK 
{
  "operator_id": "123e4567-e89b-12d3-a456-426614174000",
  "api_key": "opdk_live_TZfnxh-dZlRDQ2DWbam0grXwToSXjlPZt4OQSIpF7Tc",
  "api_secret": "KhSxDRVf6ymBgHZjKVWxNkjdmHj5ggkRTIud2cxdP3DuxqtAyTDQhYrPe4IPdfKP"
}

Note: Save your API credentials immediately - they won't be shown again!

Request 

curl -X GET https://api.opendeck.co.uk/api/merchant/dashboard/overview?period=month \
  -H "X-API-Key: opdk_live_YOUR_API_KEY_HERE"

Response

200 OK 
{
  "total_volume": 125000.50,
  "total_revenue": 1875.75,
  "transaction_count": 342,
  "success_rate": 0.98,
  "active_players": 156,
  "pending_transactions": 3,
  "volume_change_percent": 12.5,
  "revenue_change_percent": 8.3,
  "period_start": "2024-11-17T00:00:00Z",
  "period_end": "2024-12-17T00:00:00Z"
}

Code Examples

Authentication (JavaScript)

// Register a new user
const response = await fetch('https://api.opendeck.co.uk/api/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securePassword123',
    firstName: 'Paul',
    lastName: 'Davis'
  })
});

const data = await response.json();
const token = data.token; // Store for authenticated requests

Authenticated Request (JavaScript)

// Make authenticated API call
const response = await fetch('https://api.opendeck.co.uk/api/accounts', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const accounts = await response.json();

Python Example

import requests

# Authenticate
response = requests.post(
    'https://api.opendeck.co.uk/api/auth/login',
    json={'email': 'user@example.com', 'password': 'password'}
)
token = response.json()['token']

# Make authenticated request
headers = {'Authorization': f'Bearer {token}'}
accounts = requests.get(
    'https://api.opendeck.co.uk/api/accounts',
    headers=headers
).json()

Gaming Transaction (cURL)

curl -X POST https://api.opendeck.co.uk/api/gaming/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operator_id": "op_123",
    "player_id": "player_456",
    "type": "deposit",
    "amount": 100.00,
    "currency": "GBP"
  }'

Register as Operator (cURL)

curl -X POST https://api.opendeck.co.uk/api/gaming/operators \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Your Company Ltd",
    "trading_name": "Your Trading Name",
    "contact_email": "contact@example.com",
    "contact_phone": "+44 20 1234 5678",
    "uk_gambling_license": "LIC123456"
  }'

Returns API key and secret - save these!

Setting Up as an Operator

For Gaming & Gambling Operators

Online casinos, sportsbooks, esports platforms, fantasy sports, and skill-based gaming

Gaming operators, casinos, sportsbooks, and esports platforms can integrate with Opendeck to process payments with ML-powered affordability checks, real-time transaction processing, and comprehensive player account management.

🔒 Security First: All connections are encrypted, authenticated, and comply with PSD2, UK Gambling Commission regulations, and GDPR. Your API credentials are hashed and never stored in plain text.

1
Register as a Gaming Operator

Start by registering your gaming operator organization with Opendeck. This creates your operator account and generates secure API credentials.

API Endpoint

POST https://api.opendeck.co.uk/api/gaming/operators
Content-Type: application/json

{
  "company_name": "Gaming Operator Ltd",
  "trading_name": "Your Casino Brand",
  "contact_email": "api@yourcasino.com",
  "contact_phone": "+44 20 1234 5678",
  "company_number": "12345678",
  "uk_gambling_license": "LIC123456",
  "website_url": "https://www.yourcasino.com",
  "webhook_url": "https://api.yourcasino.com/webhooks/opendeck"
}

Response: You'll receive your API credentials immediately:

{
  "operator_id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "opdk_live_abc123...",
  "api_secret": "opdk_secret_xyz789..."
}

⚠️ CRITICAL: Save these credentials immediately! They are only shown once and cannot be recovered.

Required Fields:

  • company_name - Your registered company name
  • trading_name - Your public-facing brand name
  • contact_email - Technical contact email
  • contact_phone - Contact phone number

Optional Fields:

  • company_number - UK Companies House number
  • uk_gambling_license - UK Gambling Commission license number (required for UK operators)
  • website_url - Your public website URL
  • webhook_url - Your webhook endpoint for real-time notifications
2
Account Activation & Verification

After registration, your operator account starts with pending status. Opendeck will review your application for compliance and activate your account.

Check Account Status

GET https://api.opendeck.co.uk/api/gaming/operators/me
X-API-Key: opdk_live_YOUR_API_KEY_HERE

Response:

{
  "operator_id": "550e8400-e29b-41d4-a716-446655440000",
  "company_name": "Gaming Operator Ltd",
  "trading_name": "Your Casino Brand",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

Activation Status: Check your account status by calling GET /api/gaming/operators/me with your API key. Status will change from pending to active when approved. Activation typically takes 1-2 business days for compliance review. You'll receive an email notification when your account is activated.

3
Create Player Accounts

Before processing transactions, create player accounts for your users. Each player account is linked to your operator and can have multiple payment methods.

Create Player Account

POST https://api.opendeck.co.uk/api/gaming/players
X-API-Key: opdk_live_YOUR_API_KEY_HERE
Content-Type: application/json

{
  "operator_id": "550e8400-e29b-41d4-a716-446655440000",
  "player_id": "player_12345",
  "email": "player@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-15",
  "country": "GB"
}

Response:

{
  "player_id": "player_12345",
  "operator_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "player@example.com",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}
4
Process Deposits & Withdrawals

Process player deposits and withdrawals with automatic affordability checks. All transactions are processed securely with real-time status updates.

Create Deposit Transaction

POST https://api.opendeck.co.uk/api/gaming/transactions
X-API-Key: opdk_live_YOUR_API_KEY_HERE
Content-Type: application/json

{
  "operator_id": "550e8400-e29b-41d4-a716-446655440000",
  "player_id": "player_12345",
  "type": "deposit",
  "amount": 100.00,
  "currency": "GBP",
  "operator_transaction_id": "CASINO-TXN-12345"
}

Response:

{
  "transaction_id": "txn_abc123",
  "operator_transaction_id": "CASINO-TXN-12345",
  "player_id": "player_12345",
  "type": "deposit",
  "amount": 100.00,
  "currency": "GBP",
  "status": "pending",
  "affordability_check": {
    "status": "approved",
    "risk_score": 0.15,
    "recommendation": "proceed"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Transaction Types:

  • deposit - Player deposits funds to their account
  • withdrawal - Player withdraws funds from their account
  • refund - Refund a previous transaction
5
ML-Powered Affordability Checks

Opendeck automatically performs ML-powered affordability checks on all transactions to ensure responsible gambling and compliance with UK Gambling Commission regulations.

Request Affordability Check

POST https://api.opendeck.co.uk/api/gaming/affordability/check
X-API-Key: opdk_live_YOUR_API_KEY_HERE
Content-Type: application/json

{
  "player_id": "player_12345",
  "amount": 500.00,
  "currency": "GBP",
  "transaction_type": "deposit"
}

Response:

{
  "affordability_status": "approved",
  "risk_score": 0.12,
  "recommendation": "proceed",
  "factors": {
    "income_verification": "verified",
    "spending_pattern": "normal",
    "deposit_frequency": "moderate"
  },
  "warnings": []
}

Affordability Status Values:

  • approved - Transaction is safe to proceed
  • warning - Proceed with caution, review recommended
  • rejected - Transaction should be declined
6
Webhook Integration

Receive real-time notifications about transaction status changes, player account updates, and affordability check results via webhooks.

Webhook Events

  • transaction.status_changed - Transaction status updated
  • transaction.completed - Transaction completed successfully
  • transaction.failed - Transaction failed
  • affordability.check_completed - Affordability check completed
  • player.account_created - New player account created

Webhook Payload Example

POST https://api.yourcasino.com/webhooks/opendeck
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...

{
  "event": "transaction.status_changed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "transaction_id": "txn_abc123",
    "operator_transaction_id": "CASINO-TXN-12345",
    "status": "completed",
    "amount": 100.00,
    "currency": "GBP"
  }
}

Security: All webhooks are signed with HMAC SHA-256. Verify the signature using your API secret to ensure the webhook is from Opendeck.

7
Access Merchant Dashboard

Access your merchant dashboard to view transaction analytics, player statistics, and account overview.

Dashboard Overview

GET https://api.opendeck.co.uk/api/merchant/dashboard/overview?period=day
X-API-Key: opdk_live_YOUR_API_KEY_HERE

Response:

{
  "period": "day",
  "total_transactions": 1250,
  "total_volume": 125000.00,
  "successful_transactions": 1180,
  "failed_transactions": 70,
  "average_transaction_value": 100.00,
  "top_players": [...]
}
Best Practices & Compliance
  • Always verify affordability checks before processing large deposits to ensure responsible gambling compliance
  • Store API credentials securely - Never commit them to version control or expose them in client-side code
  • Implement webhook signature verification to ensure webhooks are authentic and from Opendeck
  • Use idempotency keys for transaction requests to prevent duplicate processing
  • Monitor transaction status and handle failed transactions appropriately with retry logic
  • Comply with UK Gambling Commission regulations including age verification, self-exclusion, and responsible gambling measures
Need Help?

For technical support, API questions, or compliance inquiries, contact our team:

Contact Support View Full Documentation

For Pension Service Providers

Production-ready integration guide for pension providers

🔒 Security First: All connections are encrypted, authenticated, and comply with PSD2 and GDPR regulations. Your API credentials are hashed and never stored in plain text.

1
Register as a Pension Provider

Start by registering your pension provider organization with Opendeck. This creates your operator account and generates secure API credentials.

API Endpoint

POST https://api.opendeck.co.uk/api/gaming/operators
Content-Type: application/json

{
  "company_name": "NEST Corporation",
  "trading_name": "NEST Pensions",
  "contact_email": "api@nestpensions.com",
  "contact_phone": "+44 20 1234 5678",
  "company_number": "RC000727",
  "website_url": "https://www.nestpensions.org.uk",
  "webhook_url": "https://api.nestpensions.com/webhooks/opendeck"
}

Response: You'll receive your API credentials immediately:

{
  "operator_id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "opdk_live_abc123...",
  "api_secret": "opdk_secret_xyz789..."
}

⚠️ CRITICAL: Save these credentials immediately! They are only shown once and cannot be recovered.

Required Fields:

  • company_name - Your registered company name
  • trading_name - Your public-facing brand name
  • contact_email - Technical contact email

Optional Fields:

  • company_number - UK Companies House number
  • webhook_url - Your webhook endpoint for real-time notifications
  • uk_gambling_license - Not required for pension providers
2
Account Activation & Verification

After registration, your account starts with pending status. Opendeck performs compliance verification before activation.

Verification Process:

  1. Company Verification: We verify your company registration with Companies House (UK)
  2. Compliance Review: Review of pension provider regulations and applicable regulatory requirements
  3. Security Assessment: Validation of your webhook endpoint and security practices
  4. API Testing: We may request test API calls to verify integration readiness

Check Activation Status:

GET https://api.opendeck.co.uk/api/gaming/operators/me
Headers:
  X-API-Key: opdk_live_YOUR_API_KEY

Status values: pending → active

⏱️ Typical Timeline: 1-2 business days for standard verification. Complex cases may take up to 5 business days. You'll receive email notifications at each stage.

3
Establish Secure Connection

Once activated, establish a secure connection between Opendeck and your pension provider system. This enables real-time account verification and payment processing.

Connection Methods:

Option A: API Token Exchange (Recommended)

Exchange secure tokens for authenticated API access:

POST https://api.opendeck.co.uk/api/pensions/providers/connect
Headers:
  X-API-Key: opdk_live_YOUR_API_KEY
  Content-Type: application/json

Body:
{
  "provider_token": "your_secure_provider_token",
  "provider_api_endpoint": "https://api.yourpension.com/v1",
  "encryption_key": "base64_encoded_public_key"
}

Option B: OAuth 2.0 Integration

For providers with OAuth support:

POST https://api.opendeck.co.uk/api/pensions/providers/oauth/authorize
Headers:
  X-API-Key: opdk_live_YOUR_API_KEY

Body:
{
  "oauth_client_id": "your_client_id",
  "oauth_client_secret": "your_client_secret",
  "redirect_uri": "https://api.opendeck.co.uk/api/pensions/providers/oauth/callback"
}

✅ Connection Verified: Once connected, Opendeck can:

  • Verify pension account details in real-time
  • Process contribution payments securely
  • Sync account balances and transaction history
  • Send webhook notifications for payment events
4
User Account Connection Flow

When users connect their pension accounts, Opendeck securely verifies and links them to your provider system.

Connection Flow:

1

User Initiates Connection

User provides pension account details via Opendeck app/web

2

Opendeck Validates Account

Opendeck calls your API to verify account exists and is valid

3

Secure Token Exchange

Provider returns encrypted access token for future API calls

4

Account Linked

User can now make contributions through Opendeck

Provider API Endpoint (Your Side):

POST https://api.yourpension.com/v1/accounts/verify
Headers:
  Authorization: Bearer YOUR_PROVIDER_TOKEN
  X-Opendeck-Signature: HMAC_SIGNATURE

Body:
{
  "account_number": "PEN123456",
  "scheme_name": "Workplace Pension Scheme",
  "user_national_insurance": "AB123456C"
}

Response:
{
  "valid": true,
  "account_id": "ACC789",
  "account_name": "John Smith",
  "current_balance": 50000.00,
  "currency": "GBP"
}
5
Payment Processing & Webhooks

When users make pension contributions, Opendeck processes payments and notifies your system via webhooks.

Payment Flow:

  1. User initiates contribution via Opendeck (e.g., £100)
  2. Opendeck processes payment via Open Banking or wallet
  3. Opendeck sends webhook to your provider API
  4. Your system confirms receipt and updates pension account
  5. Opendeck updates payment status to completed

Webhook Payload Example:

POST https://api.yourpension.com/webhooks/opendeck
Headers:
  X-Opendeck-Event: pension.payment.completed
  X-Opendeck-Signature: HMAC_SHA256_SIGNATURE
  X-Opendeck-Timestamp: 1703123456

Body:
{
  "event_id": "evt_abc123",
  "event_type": "pension.payment.completed",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "payment_id": "pay_xyz789",
    "pension_account_id": "acc_456",
    "user_id": "usr_123",
    "amount": 100.00,
    "currency": "GBP",
    "tax_relief_amount": 25.00,
    "gross_amount": 125.00,
    "payment_source": "bank_account",
    "provider_payment_id": "PEN-2024-001234"
  }
}

Security: Always verify the X-Opendeck-Signature header using HMAC SHA256 with your webhook secret.

Webhook Events:

  • pension.payment.completed - Payment successfully processed
  • pension.payment.failed - Payment failed
  • pension.account.connected - User connected their account
  • pension.account.disconnected - User disconnected their account
Security & Best Practices

🔐 API Key Security

  • Never commit API keys to version control
  • Rotate keys immediately if compromised
  • Use environment variables for key storage
  • Implement IP whitelisting for production

🔒 Webhook Security

  • Always verify HMAC signatures
  • Check timestamp to prevent replay attacks
  • Use HTTPS for all webhook endpoints
  • Implement idempotency for payment processing

📋 Compliance

  • PSD2 compliance for payment processing
  • GDPR compliance for user data handling
  • Regulatory compliance for pension providers
  • Audit logging for all transactions
6
Integration Implementation Guide

Step-by-step guide to implement Opendeck pension integration in your system.

🚀 Quick Start Checklist

  1. Register your pension provider organization (Step 1)
  2. Wait for account activation (Step 2)
  3. Establish secure connection (Step 3)
  4. Implement account verification endpoint (Step 4)
  5. Set up webhook handler for payments (Step 5)
  6. Test in sandbox environment
  7. Go live in production

1. Implement Account Verification Endpoint

When users connect their pension accounts, Opendeck will call your API to verify account details.

Required Endpoint:

POST https://api.yourpension.com/v1/accounts/verify
Headers:
  Authorization: Bearer YOUR_PROVIDER_TOKEN
  X-Opendeck-Signature: HMAC_SHA256_SIGNATURE
  X-Opendeck-Timestamp: 1703123456
  Content-Type: application/json

Request Body:
{
  "account_number": "PEN123456",
  "scheme_name": "Workplace Pension Scheme",
  "user_national_insurance": "AB123456C",
  "user_email": "user@example.com"
}

Success Response (200 OK):
{
  "valid": true,
  "account_id": "ACC789",
  "account_name": "John Smith",
  "current_balance": 50000.00,
  "currency": "GBP",
  "scheme_name": "Workplace Pension Scheme",
  "provider_account_id": "PROV-ACC-123",
  "tax_relief_applicable": true,
  "tax_relief_rate": 20.0,
  "contribution_rate": 5.0,
  "employer_contribution_rate": 3.0
}

Error Response (400 Bad Request):
{
  "valid": false,
  "error": "Account not found",
  "error_code": "ACCOUNT_NOT_FOUND"
}

Security: Always verify the X-Opendeck-Signature header. The signature is computed as:

HMAC_SHA256(
  timestamp + request_body,
  your_webhook_secret
)

Python Example Implementation:

from flask import Flask, request, jsonify
import hmac
import hashlib
import time

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret"

def verify_signature(signature, timestamp, body):
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        (timestamp + body).encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route('/v1/accounts/verify', methods=['POST'])
def verify_account():
    # Verify signature
    signature = request.headers.get('X-Opendeck-Signature')
    timestamp = request.headers.get('X-Opendeck-Timestamp')
    
    if not verify_signature(signature, timestamp, request.data):
        return jsonify({"error": "Invalid signature"}), 401
    
    # Check timestamp (prevent replay attacks)
    if abs(time.time() - int(timestamp)) > 300:  # 5 minutes
        return jsonify({"error": "Request expired"}), 401
    
    data = request.json
    account_number = data.get('account_number')
    ni_number = data.get('user_national_insurance')
    
    # Verify account in your system
    account = verify_account_in_system(account_number, ni_number)
    
    if account:
        return jsonify({
            "valid": True,
            "account_id": account.id,
            "account_name": account.name,
            "current_balance": float(account.balance),
            "currency": "GBP",
            "scheme_name": account.scheme_name,
            "tax_relief_applicable": True,
            "tax_relief_rate": 20.0
        }), 200
    else:
        return jsonify({
            "valid": False,
            "error": "Account not found"
        }), 400

2. Implement Webhook Handler for Payments

Opendeck will send webhook notifications when payments are processed. Your system must handle these events.

Webhook Endpoint (Your Side):

POST https://api.yourpension.com/webhooks/opendeck
Headers:
  X-Opendeck-Event: pension.payment.completed
  X-Opendeck-Signature: HMAC_SHA256_SIGNATURE
  X-Opendeck-Timestamp: 1703123456
  Content-Type: application/json

Webhook Payload:
{
  "event_id": "evt_abc123",
  "event_type": "pension.payment.completed",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "payment_id": "pay_xyz789",
    "pension_account_id": "acc_456",
    "user_id": "usr_123",
    "amount": 100.00,
    "currency": "GBP",
    "tax_relief_amount": 25.00,
    "gross_amount": 125.00,
    "payment_source": "bank_account",
    "provider_payment_id": "PEN-2024-001234"
  }
}

Expected Response (200 OK):
{
  "received": true,
  "processed": true
}

Python Webhook Handler Example:

from flask import Flask, request, jsonify
import hmac
import hashlib
import time

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret"

@app.route('/webhooks/opendeck', methods=['POST'])
def handle_opendeck_webhook():
    # Verify signature
    signature = request.headers.get('X-Opendeck-Signature')
    timestamp = request.headers.get('X-Opendeck-Timestamp')
    event_type = request.headers.get('X-Opendeck-Event')
    
    if not verify_signature(signature, timestamp, request.data):
        return jsonify({"error": "Invalid signature"}), 401
    
    data = request.json
    event_type = data.get('event_type')
    event_data = data.get('data')
    
    # Handle different event types
    if event_type == 'pension.payment.completed':
        # Process payment
        payment_id = event_data.get('payment_id')
        amount = event_data.get('amount')
        account_id = event_data.get('pension_account_id')
        
        # Update pension account in your system
        result = process_pension_contribution(
            account_id=account_id,
            amount=amount,
            payment_id=payment_id
        )
        
        if result:
            return jsonify({"received": True, "processed": True}), 200
        else:
            return jsonify({"received": True, "processed": False}), 500
            
    elif event_type == 'pension.payment.failed':
        # Log failed payment
        log_failed_payment(event_data)
        return jsonify({"received": True}), 200
        
    elif event_type == 'pension.account.connected':
        # Handle account connection
        handle_account_connection(event_data)
        return jsonify({"received": True}), 200
    
    return jsonify({"received": True}), 200

⚠️ Important: Always implement idempotency. Use the event_id to prevent processing the same event twice. Store processed event IDs and check before processing.

3. Testing Your Integration

Test Account Verification:

# Use Opendeck sandbox to test account verification
curl -X POST https://sandbox-api.opendeck.co.uk/api/pensions/providers/verify-account \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "TEST123",
    "scheme_name": "Test Scheme",
    "user_national_insurance": "AB123456C",
    "provider": "nest"
  }'

Test Payment Processing:

# Create a test payment
curl -X POST https://sandbox-api.opendeck.co.uk/api/pensions/pay \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pension_account_id": "test-account-id",
    "amount": 100.00,
    "currency": "GBP",
    "payment_source": "bank_account"
  }'

Testing Webhooks: Use a tool like webhook.site or ngrok to expose your local webhook endpoint for testing.

4. Common Integration Patterns

Pattern: Batch Processing

For high-volume providers, implement batch processing of webhooks:

# Queue webhook events for batch processing
def handle_webhook(event):
    # Add to processing queue
    queue.enqueue(process_pension_payment, event.data)
    
    # Return immediately
    return {"received": True}, 200

# Process in background worker
def process_pension_payment(payment_data):
    # Batch process multiple payments
    payments = get_pending_payments()
    update_pension_accounts_batch(payments)

Pattern: Retry Logic

Implement retry logic for failed webhook processing:

def process_webhook_with_retry(event_data, max_retries=3):
    for attempt in range(max_retries):
        try:
            result = process_payment(event_data)
            return result
        except Exception as e:
            if attempt == max_retries - 1:
                # Log to error tracking system
                log_error(e, event_data)
                raise
            time.sleep(2 ** attempt)  # Exponential backoff
Testing & Support

🧪 Sandbox Environment

Test your integration in our sandbox:

https://sandbox-api.opendeck.co.uk

📚 API Documentation

Full API reference:

View Swagger Docs →

💬 Support

Need help? Contact our integration team:

integrations@opendeck.co.uk

📊 Merchant Dashboard

Monitor payments and transactions:

Access Dashboard →

Full API Documentation

Interactive API Docs

Explore all endpoints with our interactive Swagger documentation.

View Swagger Docs →

ReDoc Documentation

Beautiful, responsive API documentation with examples.

View ReDoc →

SDKs & Libraries

Official SDKs for popular programming languages.

JavaScript Python Swift Coming Soon

Webhooks

Receive real-time notifications for events.

Contact for Webhook Setup →

Built for Developers

⚡

Fast & Reliable

99.9% uptime SLA with sub-100ms response times.

🔒

Secure by Default

Bank-grade encryption and PSD2 compliance.

📚

Comprehensive Docs

Detailed guides, examples, and best practices.

For Utility Service Providers

Utility providers (electricity, gas, water, broadband, mobile) can integrate with Opendeck to enable bill payments from users with ML-powered affordability checks and usage predictions.

Step 1: Register as an Operator

Utility providers use the same operator registration endpoint as gaming operators:

POST /api/gaming/operators
Content-Type: application/json

{
  "company_name": "Utility Provider Ltd",
  "trading_name": "Your Utility Service",
  "contact_email": "api@utilityprovider.com",
  "contact_phone": "+44 20 1234 5678",
  "company_number": "12345678",
  "website_url": "https://utilityprovider.com"
}

Note: uk_gambling_license is not required for utility providers.

Step 2: Account Activation

Utility provider accounts require activation by Opendeck for compliance and verification purposes.

After registration, Opendeck will:

  • Verify your company registration
  • Review compliance requirements
  • Activate your account (typically 1-2 business days)

Activation Status: Check your account status by calling GET /api/gaming/operators/me with your API key. Status will change from pending to active when approved.

Step 3: Enable Utility Payments

Once activated, users can connect their utility accounts and make payments through Opendeck:

  • Users link their utility accounts via POST /api/utilities/accounts
  • Users make bill payments via POST /api/utilities/pay
  • ML-powered affordability checks ensure users can afford payments
  • Usage predictions help optimize payment timing
  • You receive payments and can track them via the Merchant Dashboard
Supported Utility Types

Opendeck supports payments for:

⚡

Electricity

🔥

Gas

💧

Water

📡

Broadband

📱

Mobile

📞

Landline

📺

TV

🏛️

Council Tax

ML-Powered Features

Our ML-first infrastructure provides:

  • Usage Predictions - Predict future usage based on historical patterns
  • Affordability Checks - Real-time assessment of user's ability to pay
  • Payment Optimization - Suggest optimal payment timing and amounts
  • Risk Assessment - Identify users at risk of payment default
  • Auto-Pay Recommendations - ML-driven suggestions for automatic payments

GPU Acceleration: Our infrastructure uses GPU-accelerated ML models for sub-100ms inference times, ensuring fast affordability checks even with large datasets.

Example: Creating a Utility Account
POST /api/utilities/accounts
Authorization: Bearer YOUR_USER_TOKEN
Content-Type: application/json

{
  "provider": "british_gas",
  "provider_name": "British Gas",
  "utility_type": "electricity",
  "account_number": "12345678",
  "meter_number": "1234567890",
  "property_address": "123 Main St, London, SW1A 1AA",
  "is_primary": true
}
Example: Making a Utility Payment
POST /api/utilities/pay
Authorization: Bearer YOUR_USER_TOKEN
Content-Type: application/json

{
  "utility_account_id": "account-uuid-here",
  "amount": 125.50,
  "payment_source": "bank_account",
  "bill_reference": "BG-2024-001234",
  "bill_period_start": "2024-11-01T00:00:00Z",
  "bill_period_end": "2024-11-30T23:59:59Z",
  "usage_data": {
    "kwh_used": 450,
    "days_in_period": 30,
    "average_daily_usage": 15
  }
}

The usage_data field is used by our ML models for predictions and affordability analysis.

For Event Organizers & Venues

🎭

Events & Entertainment Integration

Enable automatic pension micro-contributions (0.01% of payments) to incentivize attendance at sports events, music shows, and entertainment venues. This proprietary feature helps venues stand out while promoting financial wellness.

Proprietary Feature: This is a unique Opendeck feature that automatically contributes 0.01% of all event payments to users' chosen pension accounts.

Supported Event Types
⚽

Sports Events

🎵

Music Shows

🎭

Theater

🎪

Entertainment

Payments include tickets, concessions, merchandise, parking, and upgrades.

How It Works
  1. Register Your Venue - Create a venue account and enable micro-contributions
  2. Create Events - Register events (sports, music, theater, etc.)
  3. Process Payments - When users pay at your venue, 0.01% is automatically calculated
  4. Automatic Contribution - Micro-contributions are batched daily and sent to users' pension accounts
  5. User Benefits - Users see their contributions in real-time, incentivizing attendance
Step 1: Register a Venue
POST /api/events/venues
Authorization: Bearer YOUR_USER_TOKEN
Content-Type: application/json

{
  "name": "Wembley Stadium",
  "venue_type": "stadium",
  "address": "Wembley, London",
  "city": "London",
  "postcode": "HA9 0WS",
  "capacity": 90000,
  "description": "National football stadium",
  "contribution_rate": 0.0001
}

The contribution_rate defaults to 0.0001 (0.01%) but can be customized per venue.

Step 2: Create an Event
POST /api/events/
Authorization: Bearer YOUR_USER_TOKEN
Content-Type: application/json

{
  "name": "Premier League Match: Arsenal vs Chelsea",
  "event_type": "sports",
  "venue_id": "venue-uuid-here",
  "start_date": "2024-12-15T15:00:00Z",
  "end_date": "2024-12-15T17:00:00Z",
  "description": "Premier League football match",
  "contribution_rate": 0.0001
}
Step 3: Process Event Payment with Micro-Contribution
POST /api/events/payments
Authorization: Bearer USER_TOKEN
Content-Type: application/json

{
  "event_id": "event-uuid-here",
  "payment_type": "ticket",
  "amount": 75.00,
  "pension_account_id": "pension-account-uuid",
  "payment_source": "open_banking",
  "currency": "GBP",
  "operator_transaction_id": "VENUE-TXN-12345"
}

Automatic Calculation: For a £75 payment, the system automatically calculates £0.0075 (0.01%) as a micro-contribution to the user's pension account. This happens seamlessly with every payment.

Viewing Micro-Contributions

Users can view their pension micro-contributions from events:

GET /api/events/contributions
Authorization: Bearer USER_TOKEN

Response:
{
  "contributions": [
    {
      "id": "contrib-uuid",
      "event_payment_id": "payment-uuid",
      "pension_account_id": "pension-uuid",
      "amount": 0.0075,
      "currency": "GBP",
      "status": "completed",
      "created_at": "2024-12-15T15:30:00Z"
    }
  ],
  "total_contributed": 0.0525,
  "total_count": 7
}
Benefits for Venues
  • Marketing Advantage - Unique value proposition to attract attendees
  • Social Impact - Demonstrates commitment to financial wellness
  • Competitive Differentiation - Stand out from competitors
  • Low Integration Cost - Minimal setup, automatic processing
  • User Engagement - Users see real-time contributions, increasing loyalty
Example Payment Flow

User buys: Match ticket (£50) + Food & drinks (£25) = £75 total

Micro-contribution: £0.0075 (0.01% of £75)

Result: Payment processed normally, micro-contribution automatically added to user's pension account

User sees: Real-time notification of contribution in their Opendeck dashboard