Skip to main content

​
Quickstart Guide

Get up and running with the Open Banking API in just a few minutes. This guide will walk you through registering your application, authenticating, and making your first API call.

​
Prerequisites

Before you begin, ensure you have:
  • Valid contact information (name, email address, phone number, and address)
  • A valid business email address
  • Basic knowledge of REST APIs and OAuth 2.0
  • A secure HTTPS redirect URL for OAuth 2.0 callbacks
  • A development environment ready

​
Quick Start

1

Register Application

First, Register your application using Dynamic Client Registration API and get your credentials (client id and secret)
curl -X POST ${AUTH_BASE_URL}/dcr \
  -d '{
    "username": "ciroma.chukwuma@adekunle.com",
    "password": "veryStrongPassword",
    "app_name": "Test Open Banking App",
    "app_description": "My Test Open Banking App",
    "app_developer_name": "Fantastic Fintech Ltd",
    "app_developer_address": "Plot 35, Okokomaiko Lane, Lagos",
    "app_developer_contact_email": "ciroma.chukwuma@adekunle",
    "app_developer_contact_phone": "04022404014",
    "redirect_url": "https://myapps.com/callback"
}'

const response = await fetch('${AUTH_BASE_URL}/dcr', {
  body: new Body({
    username: 'ciroma.chukwuma@adekunle.com',
    password: 'veryStrongPassword',
    app_name: 'Test Open Banking App',
    app_description: 'My Test Open Banking App',
    app_developer_name: 'Fantastic Fintech Ltd',
    app_developer_address: 'Plot 35, Okokomaiko Lane, Lagos',
    app_developer_contact_email: 'ciroma.chukwuma@adekunle.com',
    app_developer_contact_phone: '04022404014',
    redirect_url: 'https://myapps.com/callback'
  })
});

const credentials = await response.json();
console.log('Credentials:', credentials);

response = requests.get('${API_BASE_URL}/v1/openapi/accounts', data={
        'username': 'ciroma.chukwuma@adekunle.com',
        'password': 'veryStrongPassword',
        'app_name': 'Test Open Banking App',
        'app_description': 'My Test Open Banking App',
        'app_developer_name': 'Fantastic Fintech Ltd',
        'app_developer_address': 'Plot 35, Okokomaiko Lane, Lagos',
        'app_developer_contact_email': 'ciroma.chukwuma@adekunle.com',
        'app_developer_contact_phone': '04022404014',
        'redirect_url': 'https://myapps.com/callback'
    })

credentials = response.json()
print('Credentials:', credentials)
In sandbox, you’ll receive credentials immediately whereas in production, the credential status will be PENDING_APPROVAL. Once approved by Sparkle team, you will be notified, you can call the GET /dcr API to retrieve your credentials.
2

Authenticate customer and get their authorisation to access their resoruces

Authenticate customer and get their approval to access their resources (e.g. Account information resources, Payment Initiation etc). There are 4 main method for authorisation, choose whichever is most applicable:
  • Device Code Authorisation - For dumb devices i.e. where customer does not have the capability to complete Sparkle authentication on a desktop computer or smart phone i.e. they can only authenticate via USSD or SMS
  • Authorisation code - For smart devices i.e. where customer has capability to complete Sparkle authentication on a desktop computer or smart phone
  • Authorisation code with PKCE - For smart (unsafe) devices e.g. Single Page Applications
  • Client Credentials - For API resources that does not require customer consent/approval e.g. Get Biller Categories
Sample code that shows how to implement OAuth 2 authorisation

// Authorisation via PKCE challenge
const generatePKCE = () => {
  const codeVerifier = crypto.randomUUID();
  const codeChallenge = btoa(codeVerifier);
  return { codeVerifier, codeChallenge };
};

// Step 1: Redirect user to authorization URL
const { codeVerifier, codeChallenge } = generatePKCE();
const authUrl = `${AUTH_BASE_URL}/oauth/authorize?` +
  `client_id=${credentials.client_id}&` +
  `redirect_uri=${encodeURIComponent(credentials.redirect_urls[0])}&` +
  `response_type=code&` +
  `scope=accounts payments&` +
  `code_challenge=${codeChallenge}&` +
  `code_challenge_method=S256`;

window.location.href = authUrl;

// Step 2: Exchange authorization code for access token
const exchangeCodeForToken = async (code) => {
  const response = await fetch('${AUTH_BASE_URL}/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: credentials.client_id,
      client_secret: credentials.client_secret,
      code: code,
      redirect_uri: credentials.redirect_urls[0],
      code_verifier: codeVerifier
    })
  });

  const tokenData = await response.json();
  return tokenData.access_token;
};

import base64
import hashlib
import secrets
import requests

// Authorisation via PKCE challenge
def generate_pkce():
    code_verifier = secrets.token_urlsafe(32)
    code_challenge = base64.urlsafe_b64encode(
        hashlib.sha256(code_verifier.encode()).digest()
    ).decode().rstrip('=')
    return code_verifier, code_challenge

# Step 1: Generate authorization URL
code_verifier, code_challenge = generate_pkce()
auth_url = f"${AUTH_BASE_URL}/oauth/authorize?" + \
    f"client_id={credentials['client_id']}&" + \
    f"redirect_uri={credentials['redirect_urls'][0]}&" + \
    f"response_type=code&" + \
    f"scope=accounts payments&" + \
    f"code_challenge={code_challenge}&" + \
    f"code_challenge_method=S256"

print(f"Redirect user to: {auth_url}")

# Step 2: Exchange authorization code for access token
def exchange_code_for_token(code):
    response = requests.post('${AUTH_BASE_URL}/oauth/token', data={
        'grant_type': 'authorization_code',
        'client_id': credentials['client_id'],
        'client_secret': credentials['client_secret'],
        'code': code,
        'redirect_uri': credentials['redirect_urls'][0],
        'code_verifier': code_verifier
    })
    
    token_data = response.json()
    return token_data['access_token']
3

Make API call

Make your first API call to retrieve customer informationNow you can make API calls using your access token:
curl -X GET ${API_BASE_URL}/v1/openapi/accounts \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"

const response = await fetch('${API_BASE_URL}/v1/openapi/accounts', {
  headers: {
    'Authorization': `Bearer ${ACCESS_TOKEN}`,
    'idempotency_key': ${IDEMPOTENCY_KEY},
    'signature': ${SIGNATURE}
  }
});

const accounts = await response.json();
console.log('Accounts:', accounts);

response = requests.get('${API_BASE_URL}/v1/openapi/accounts', headers={
    'Authorization': f'Bearer {access_token}',
    'idempotency_key': ${IDEMPOTENCY_KEY},
    'signature': ${SIGNATURE}
})

accounts = response.json()
print('Accounts:', accounts)
4

Build your application

Build your application using our comprehensive APIs

​
Next Steps

Congratulations! You’ve successfully:
  1. ✅ Registered your application
  2. ✅ Implemented OAuth authentication
  3. ✅ Made your first API call
Now you can explore more features:
Remember to store your credentials securely and never expose them in client-side code.For Single Page Applications (SPA), use OAuth 2.0 with PKCE. Always use environment variables for sensitive information.