Xend Finance Member API Documentation

General API Response

All API responses follow a standardized JSON structure. This ensures consistency and predictability when you interact with our endpoints.

Response Object Structure

{
  "data": {},
  "status": "success",
  "statusCode": 200,
  "message": "Action Completed",
  "action": null,
  "messageLanguageCode": "app_001",
  "details": null,
  "cacheTTL": 20
}

Field Descriptions

Field Description
data The main content returned by the API. Can be an object, array, or null.
status Indicates the outcome of the request. Possible values are 'success' or 'failed'.
statusCode The standard HTTP response status code.
message A human-readable message to be displayed to the end-user (e.g., "Registration completed").
messageLanguageCode A unique code for the message, which can be used by frontend clients for translations.
action A specific action the frontend should take, e.g., 'load_2fa_screen'. See action documentation for details.
details Contains detailed debug messages or error logs for the developer. This field is not returned in production environments.
cacheTTL Time-To-Live in seconds. Indicates how long the response is cached on the server. You may use this to manage your own caching logic.

API Authentication

Our API uses a multi-layered authentication approach: an initial API key for general authorization, followed by a dynamic HMAC signature for user-specific requests.

Authorization Flow

  1. API Key Authorization: Every request must be authorized with a public API key sent in the x-api-key header. This key is available in your environment as `HTTP_AUTHORIZATION_KEY`.
  2. User Login: When a user logs in via the API, we return a temporary JWT (accessToken) and a corresponding HMAC key (accessSecret).
  3. HMAC Signature: For all subsequent authenticated requests, you must use the accessSecret to generate an HMAC signature and include it in the x-hmac-signature header.

Login Response & Token Expiry

Upon successful login, the API returns your `accessToken`, `accessSecret`, and `sessionExpiryTime`. The `sessionExpiryTime` (e.g., "2h") indicates the token's lifespan, after which you will need to re-authenticate or refresh the token. Note: You can find detailed response samples for all endpoints in the Swagger documentation.

{
  "data": {
    "user": { ... },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "accessSecret": "random-secret-string",
    "sessionExpiryTime": "2h",
    "twoFactorSecret": { ... }
  },
  "status": "success",
  "statusCode": 200,
  ...
}

HMAC Signature Generation

The HMAC signature is created from a SHA256 hash of the request timestamp and payload, using your `accessSecret` as the key. Include the signature and timestamp in the request headers.

// Node.js Example
const crypto = require('crypto');

const generateHmacSignature = (secret, timestamp, payload) => {
  const message = `${timestamp}:${payload}`;
  return crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
};

const timestamp = Date.now();
const payload = JSON.stringify({ /* your request body */ });
const accessSecret = 'your_access_secret_from_login';
const hmacSignature = generateHmacSignature(accessSecret, timestamp, payload);

HTTPS Request Samples

Below are sample code examples showing how to make authenticated HTTPS requests to the Member API. These examples demonstrate the proper headers and authentication flow required for all member endpoints.

Required Headers

All member API requests require the following headers for authentication and security:

Header Type Description Example
Accept string Content type for the response application/json
x-api-key string API key for general authorization your_api_key_here
Authorization string Bearer token for user authentication Bearer your_access_token_here
x-hmac-signature string HMAC signature for request integrity generated_hmac_signature
x-request-timestamp number Current timestamp in milliseconds 1703123456789
x-nonce-string string Unique string to prevent replay attacks random_32_char_string

Request Sample Code

Here's a complete example of how to make authenticated requests to the Member API using the makeMemberRequest function pattern:

// Node.js Example - makeMemberRequest function
const request = require('supertest');
const crypto = require('crypto');

const generateHmacSignature = (secret, timestamp, payload) => {
  const message = `${timestamp}:${payload}`;
  return crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
};

const makeMemberRequest = async (
  app,
  method,
  url,
  payload,
  accessToken,
  accessSecret
) => {
  try {
    const timestamp = Date.now();
    const payloadString = JSON.stringify(payload);
    
    const hmacSignature = generateHmacSignature(
      accessSecret,
      timestamp,
      payloadString
    );

    const response = await request(app.info.uri)
      [method](url)
      .set('Accept', 'application/json')
      .set('x-api-key', process.env.HTTP_AUTHORIZATION_KEY || '')
      .set('Authorization', `Bearer ${accessToken}`)
      .set('x-hmac-signature', hmacSignature)
      .set('x-request-timestamp', timestamp.toString())
      .set('x-nonce-string', crypto.randomBytes(16).toString('hex'))
      .send(payload);

    return response;
  } catch (error) {
    console.error(`Error during request to ${url}:`, error);
    throw error;
  }
};

// Example usage
const exampleRequest = async () => {
  const app = require('./app'); // Your app instance
  const accessToken = 'your_access_token_from_login';
  const accessSecret = 'your_access_secret_from_login';
  
  // Example: Get member profile
  const response = await makeMemberRequest(
    app,
    'get',
    '/api/Member/profile',
    {},
    accessToken,
    accessSecret
  );
  
  console.log('Response:', response.body);
};

Header Explanations

Authentication Headers

  • x-api-key: General API authorization key required for all requests
  • Authorization: Bearer token containing the user's access token from login
  • x-hmac-signature: SHA256 HMAC signature for request integrity verification

Security Headers

  • x-request-timestamp: Current timestamp in milliseconds to prevent replay attacks
  • x-nonce-string: Unique random string for each request to ensure uniqueness
  • Accept: Specifies the expected response format (application/json)

Pagination

Endpoints that return a list of items are paginated. You can control the pagination using the following parameters in your request payload.

Pagination Payload

Parameter Type Description
pageId number The page number you want to retrieve. Starts at 1.
perPage number The number of items to return per page.
sort string The sort order. Accepts ASC for ascending or DESC for descending.

Pagination Response

The response for a paginated endpoint will contain the list of items and a `paginator` object with metadata about the pagination state.

{
  "data": {
    "itemsList": [
      {
        "id": "61dd646ca6845a8eb613a7f8",
        "name": "Xend Finance",
        "version": "0.0.2",
        "platform": "android",
        "status": "active",
        "createdAt": "2022-01-11T11:05:25.249Z",
        "updatedAt": "2022-01-11T11:05:25.249Z"
      }
    ],
    "paginator": {
      "itemCount": 9,
      "perPage": 2,
      "pageCount": 5,
      "currentPage": 3,
      "slNo": 5,
      "hasPrevPage": true,
      "hasNextPage": true,
      "prev": 2,
      "next": 4
    }
  }
}

UI Suggestions

To maintain brand consistency and ensure a high-quality user experience, we recommend using the following fonts in your user interface.

Heading Font

Use Agu Display for all major headings to provide a distinct and elegant feel.

Get Agu Display Font →

Body Font

Use Inter for all body text, paragraphs, and labels to ensure maximum readability.

Get Inter Font →

Example Usage

This is a Main Heading

This is the body paragraph text. It's clean, legible, and perfect for longer-form content, descriptions, and UI labels. Using this ensures a consistent experience for all users interacting with Xend Finance services.

Technical Documentation

This is the confidential technical documentation for Xend Finance. It provides deeper technical insights, architectural overviews, and best practices. Please request access to view the full document.

Swagger Documentation

For a complete and interactive API reference, including all endpoints, request/response models, and the ability to try out API calls directly, please visit our Swagger documentation pages.

Copied to clipboard!