API Integration Examples

This page provides practical examples for integrating with the Asenso Banking API, including code samples in multiple programming languages.

Quick Start

Before making API calls, ensure you have the required authentication headers:

const headers = {
  'X-API-KEY': 'your-api-key-here',
  'X-Hmac-Timestamp': new Date().toISOString(),
  'X-Hmac-Nonce': generateUUID(),
  'X-Hmac-Signature': generateHMACSignature(),
  'User-Agent': 'YourApp/1.0',
  'Content-Type': 'application/json'
}

User Information Retrieval

JavaScript/Node.js

async function getUserInfo(clientId) {
  const response = await fetch(`${API_BASE_URL}/user/info`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({
      clientid: clientId
    })
  });
  
  return await response.json();
}

// Usage
const userInfo = await getUserInfo("10000016");
console.log(userInfo);

Python

import requests
import json

def get_user_info(client_id):
    url = f"{API_BASE_URL}/user/info"
    payload = {"clientid": client_id}
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Usage
user_info = get_user_info("10000016")
print(user_info)

cURL

curl -X POST "${API_BASE_URL}/user/info" \
  -H "X-API-KEY: your-api-key" \
  -H "X-Hmac-Timestamp: 2025-08-17T10:15:30Z" \
  -H "X-Hmac-Nonce: unique-nonce-value" \
  -H "X-Hmac-Signature: hmac-signature" \
  -H "User-Agent: YourApp/1.0" \
  -H "Content-Type: application/json" \
  -d '{"clientid": "10000016"}'

Savings Account Operations

Get Account Balance

async function getAccountBalance(savingsId) {
  const response = await fetch(`${API_BASE_URL}/savings/details`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({
      savingsid: savingsId
    })
  });
  
  const result = await response.json();
  return result.data.currentbalance1;
}

Get Transaction History

def get_transaction_history(savings_id, page=1, limit=10):
    url = f"{API_BASE_URL}/savings/transaction-list"
    payload = {
        "savingsid": savings_id,
        "page": page,
        "limit": limit,
        "sorDirection": "desc"
    }
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Get last 20 transactions
transactions = get_transaction_history("10000016", limit=20)

Fund Transfer

Intra-bank Transfer

async function transferFunds(transferData) {
  const response = await fetch(`${API_BASE_URL}/banktransfer/intra-fund-transfer`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({
      customerId: transferData.customerId,
      sourceAccount: transferData.sourceAccount,
      destinationAccount: transferData.destinationAccount,
      amount: transferData.amount,
      fee: transferData.fee || "0.00",
      description: transferData.description,
      referenceNumber: generateReferenceNumber(),
      type: "transfer",
      channel: "intrabank"
    })
  });
  
  return await response.json();
}

// Usage
const transfer = await transferFunds({
  customerId: "1697225",
  sourceAccount: "10000016",
  destinationAccount: "10000024",
  amount: "100.00",
  fee: "10.00",
  description: "Payment for services"
});

Account Validation

Validate Account Before Transaction

def validate_account(savings_id):
    url = f"{API_BASE_URL}/accounts/validation"
    payload = {"savingsid": savings_id}
    
    response = requests.post(url, headers=headers, json=payload)
    result = response.json()
    
    return result['data']['rc'] == 201  # 201 indicates valid partner account

# Validate before processing transaction
if validate_account("10000016"):
    # Proceed with transaction
    pass
else:
    # Handle invalid account
    pass

Security Best Practices

HMAC Signature Generation

const crypto = require('crypto');

function generateHMACSignature(method, url, payload, timestamp, nonce, secretKey) {
  const message = `${method}\n${url}\n${JSON.stringify(payload)}\n${timestamp}\n${nonce}`;
  return crypto.createHmac('sha256', secretKey).update(message).digest('hex');
}

function generateUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    const r = Math.random() * 16 | 0;
    const v = c === 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}

Error Handling

JavaScript Example with Error Handling

async function safeApiCall(endpoint, payload) {
  try {
    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(payload)
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const result = await response.json();
    
    if (result.code !== 200 && result.code !== 201) {
      throw new Error(`API Error: ${result.status || 'Unknown error'}`);
    }
    
    return result;
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

Response Format

All API responses follow this standard format:

{
  "code": 200,
  "status": "Success",
  "data": {
    // Response-specific data here
  }
}

Development Environment

For testing and development, use the sandbox environment with proper test credentials provided upon registration.

Rate Limiting

API calls are rate-limited to prevent abuse. Implement proper retry logic with exponential backoff for production applications.