> ## Documentation Index
> Fetch the complete documentation index at: https://docs-sandbox.sparkle.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical Guide

> Technical reference for Open Banking Nigeria API including data types, authentication, and best practices

## 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

| Type             | Format                                  | Example                    | Description                                          |
| ---------------- | --------------------------------------- | -------------------------- | ---------------------------------------------------- |
| **String**       | UTF-8 encoded string                    | `"The Quick Brown Fox"`    | Text data with UTF-8 encoding                        |
| **Number**       | Decimal notation (max 4 decimal places) | `1.0004`                   | Numeric values with precision up to 4 decimal places |
| **Date**         | ISO8601 format                          | `2025-05-07T12:34:56.789Z` | UTC timestamps in ISO8601 standard                   |
| **Country**      | ISO 3166-1 alpha-2                      | `"NG"`                     | Two-letter country codes                             |
| **Currency**     | ISO 4217 alpha code                     | `"NGN"`                    | Three-letter currency codes                          |
| **Phone Number** | E.164 Standard                          | `"+2348022223333"`         | International phone number format                    |

### Data Length

| Type               | Description                   | Length                    |
| ------------------ | ----------------------------- | ------------------------- |
| **Text fields**    | string                        | max-length 255 characters |
| **BVN**            | integers starting with 1 or 2 | 11 digits                 |
| **Account Number** | integers                      | 10 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.

| Field           | Type   | Description                                     |
| --------------- | ------ | ----------------------------------------------- |
| **id**          | string | A unique identifier for the extra field         |
| **description** | string | A description of the extra field                |
| **type**        | string | A type of field but defined by the API Consumer |
| **value**       | string | The 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)

<Accordion title="Example Implementation">
  ```bash cURL theme={null}
          curl -X GET ${AUTH_BASE_URL}/accounts \
            -H "idempotency-key: xxxxx-xxxxx-xxxx-xxxx" \
            -H "signature: xxxxx-xxxxx-xxxx-xxxx"
  ```
</Accordion>

<Note>
  Idempotency ensures data consistency and prevents duplicate transactions, making the API more reliable for financial operations.
</Note>

## 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

<Accordion title="How to Calculate sample codes">
  <CodeGroup>
    ```javascript Javascript theme={null}
    // Example signature calculation
    const clientSecret = "your_client_secret_here";
    const idempotencyKey = "unique_request_id_123";
    const signatureInput = clientSecret + ";" + idempotencyKey;
    const signature = sha256(signatureInput);
    ```

    ```java Java theme={null}
    // example signature calculation
    import java.nio.charset.StandardCharsets;
    import java.security.MessageDigest;
    import java.util.Base64;

    public class SignatureCalculator {


        static String computeSignature(String clientSecret, String idempotencyKey) throws Exception {
            String toSign = clientSecret + ";" + idempotencyKey;

            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] hash = digest.digest(toSign.getBytes(StandardCharsets.UTF_8));

            return Base64.getEncoder().encodeToString(hash);
        }
        
        // Usage example
        public static void main(String[] args) {
            String clientSecret = "your_client_secret_here";
            String idempotencyKey = "unique_request_id_123";
            String signature = calculateSignature(clientSecret, idempotencyKey);
            System.out.println("Signature: " + signature);
        }
    }
    ```
  </CodeGroup>
</Accordion>

## URLS

| SERVICE               | SANDBOX                                                                                  | PRODUCTION                                                             |
| --------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Authentication Server | [https://identity-sandbox.sparkle.fyi](https://identity-sandbox.sparkle.fyi)             | [https://identity.sparkle.ng](https://identity.sparkle.ng)             |
| API Server            | [https://api-sandbox.sparkle.fyi/openapi/v1](https://api-sandbox.sparkle.fyi/openapi/v1) | [https://api.sparkle.ng/openapi/v1](https://api.sparkle.ng/openapi/v1) |

<Accordion title="How to Use Signature Implementation">
  ```bash cURL theme={null}
          curl -X GET ${AUTH_BASE_URL}/accounts \
            -H "idempotency-key: xxxxx-xxxxx-xxxx-xxxx" \
            -H "signature: xxxxx-xxxxx-xxxx-xxxx"
  ```
</Accordion>

<Note>
  This signature calculation is required for secure API authentication and helps prevent request tampering.
</Note>

## 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