​
Overview

This technical guide provides detailed information about the Open Banking Nigeria API, including data types, and technical specifications.

​
Data Types

All Open Banking Nigeria API responses are returned in JSON format. The following data types are used throughout the API:

​
Core Data Types

TypeFormatExampleDescription
StringUTF-8 encoded string"The Quick Brown Fox"Text data with UTF-8 encoding
NumberDecimal notation (max 4 decimal places)1.0004Numeric values with precision up to 4 decimal places
DateISO8601 format2025-05-07T12:34:56.789ZUTC timestamps in ISO8601 standard
CountryISO 3166-1 alpha-2"NG"Two-letter country codes
CurrencyISO 4217 alpha code"NGN"Three-letter currency codes
Phone NumberE.164 Standard"+2348022223333"International phone number format

​
Data Length

TypeDescriptionLength
Text fieldsstringmax-length 255 characters
BVNintegers starting with 1 or 211 digits
Account Numberintegers10 digits

​
Custom Properties

Custom properties allow API consumers to include additional metadata with their requests and responses. These fields are flexible and can be used for various purposes such as tracking, categorization, or additional context.
FieldTypeDescription
idstringA unique identifier for the extra field
descriptionstringA description of the extra field
typestringA type of field but defined by the API Consumer
valuestringThe value of the extra field

​
Amount

Amounts are in major denomination i.e. 100 means 100.00.

​
Idempotency

All Open Banking APIs shall support idempotency for safely retrying transactions without accidentally performing the same operation twice. This is useful when an API call is disrupted or does not receive a response. For example, request_time_out or response_received_too_late. Therefore, if a developer does not get a response message for a transaction, they can retry the request with the same idempotency key, and are guaranteed that no more than one transaction would be posted.

​
How Idempotency Works

  1. Unique Key Generation: Generate a unique idempotency key for each transaction
  2. Request Header: Include the idempotency key in the request headers
  3. Server Processing: The server checks if the key has been used before
  4. Response Handling:
    • First Request: Process normally and return response
    • Duplicate Request: Return the original response without processing again

​
Idempotency Key Requirements

  • Uniqueness: Each key must be unique across all transactions
  • Format: String format, typically UUID or timestamp-based
  • Length: Maximum 255 characters
  • Persistence: Keys are stored for a configurable period (typically 24-48 hours)
cURL
        curl -X GET ${AUTH_BASE_URL}/accounts \
          -H "idempotency-key: xxxxx-xxxxx-xxxx-xxxx" \
          -H "signature: xxxxx-xxxxx-xxxx-xxxx"
Idempotency ensures data consistency and prevents duplicate transactions, making the API more reliable for financial operations.

​
Calculating Signature

The API uses SHA-256 hashing for request signature calculation to ensure data integrity and authenticity.

​
Signature Formula

SHA-256(CLIENT_SECRET + ";" + idempotency_key_header)

​
How to Calculate

  1. Concatenate: Combine your CLIENT_SECRET with a semicolon (;) and the idempotency_key_header
  2. Hash: Apply SHA-256 hashing algorithm to the concatenated string
  3. Result: The resulting hash is your request signature
// Example signature calculation
const clientSecret = "your_client_secret_here";
const idempotencyKey = "unique_request_id_123";
const signatureInput = clientSecret + ";" + idempotencyKey;
const signature = sha256(signatureInput);

​
URLS

SERVICESANDBOXPRODUCTION
Authentication Serverhttps://identity-sandbox.sparkle.fyihttps://identity.sparkle.ng
API Serverhttps://api-sandbox.sparkle.fyi/openapi/v1https://api.sparkle.ng/openapi/v1
cURL
        curl -X GET ${AUTH_BASE_URL}/accounts \
          -H "idempotency-key: xxxxx-xxxxx-xxxx-xxxx" \
          -H "signature: xxxxx-xxxxx-xxxx-xxxx"
This signature calculation is required for secure API authentication and helps prevent request tampering.

​
Best Practices

​
Data Validation

  • Always validate data types before processing API responses
  • Handle null/undefined values gracefully
  • Use appropriate data type conversions when needed

​
Date Handling

  • Always use Lagos West Africa timezone (WAT) for consistency
  • Parse dates using ISO8601 standard libraries
  • Consider timezone differences in your application

​
Number Precision

  • Respect the 4 decimal place limit for monetary values
  • Use appropriate decimal precision for calculations
  • Avoid floating-point arithmetic for financial calculations

​
String Encoding

  • Ensure UTF-8 encoding for all string data
  • Handle special characters and emojis properly
  • Validate string length limits where applicable
⌘I