1. Authentication

Endpoint: /auth

Request Method: POST

Content-Type: application/json; charset=utf-8

Request Headers

• X-VC-Client-ID: The unique client ID.
• X-VC-Client-TS: Timestamp of the request.
• X-VC-Client-Signature: Signature generated for security validation.

Request Body

{
  userToken: string,       // User token for authentication
  currency: string         // Currency code (e.g., "ETB")
}
      

Response Codes

• 200: Successful authentication.
• 401: Invalid token.
• 403: Expired token.

Response Body (Success)

{
  code: 200,
  message: "",
  data: {
    userId: string,         // Unique identifier of the user
    username: string,       // Username of the authenticated user
    balance: number,             // Current balance
    currency: string        // Currency code (e.g., "ETB")
  }
}
      

2. Withdraw

Endpoint: /withdraw

Request Method: POST

Content-Type: application/json; charset=utf-8

Request Headers

• X-VC-Client-ID: The unique client ID.
• X-VC-Client-TS: Timestamp of the request.
• X-VC-Client-Signature: Signature generated for security validation.

Request Body

{
  amount: number,                // Amount to withdraw
  currency: string,         // Currency code (e.g., "ETB")
  userToken: string,        // User token
  game: string,             // Game identifier
  userId: string,           // User ID
  providerTxId: string      // Transaction ID from the provider
}
      

Response Codes

• 200: Successful withdrawal.
• 401: Invalid token.
• 402: The user does not have enough balance.
• 403: Access forbidden.
• 409: The transaction already exists.

Response Body (Success)

{
  code: 200,
  message: "",
  data: {
    clientTxId: string,       // Unique client transaction ID
    providerTxId: string,     // Provider's transaction ID
    newBalance: number,            // User's new balance after the transaction
    oldBalance: number,            // User's balance before the transaction
    userId: string,           // User ID
    currency: string          // Currency code (e.g., "ETB")
  }
}
      

3. Deposit

Endpoint: /deposit

Request Method: POST

Content-Type: application/json; charset=utf-8

Request Headers

• X-VC-Client-ID: The unique client ID.
• X-VC-Client-TS: Timestamp of the request.
• X-VC-Client-Signature: Signature generated for security validation.

Request Body

{
  amount: number,                // Amount to deposit
  currency: string,         // Currency code (e.g., "ETB")
  userToken: string,        // User token
  game: string,             // Game identifier
  userId: string,           // User ID
  providerTxId: string      // Transaction ID from the provider
}
      

Response Codes

• 200: Successful deposit.
• 401: Invalid token.
• 403: Access forbidden.
• 409: The transaction already exists.

Response Body (Success)

{
  code: 200,
  message: "",
  data: {
    clientTxId: string,       // Unique client transaction ID
    providerTxId: string,     // Provider's transaction ID
    newBalance: number,            // User's new balance after the transaction
    oldBalance: number,            // User's balance before the transaction
    userId: string,           // User ID
    currency: string          // Currency code (e.g., "ETB")
  }
}
      

4. Rollback

Endpoint: /rollback

Request Method: POST

Content-Type: application/json; charset=utf-8

Request Headers

• X-VC-Client-ID: The unique client ID.
• X-VC-Client-TS: Timestamp of the request.
• X-VC-Client-Signature: Signature generated for security validation.

Request Body

{
  amount: number,                // Amount to rollback
  currency: string,         // Currency code (e.g., "ETB")
  userToken: string,        // User token
  game: string,             // Game identifier
  userId: string,           // User ID
  providerTxId: string,     // Original transaction ID
  "rollbackProviderTxId": string // Transaction ID to be rolled back
}
      

Response Codes

• 200: Successful rollback.
• 401: Invalid token.
• 403: Access forbidden.
• 408: Transaction not found.
• 409: The rollback transaction already exists.

Response Body (Success)

{
  code: 200,
  message: "",
  data: {
    clientTxId: string,       // Unique client transaction ID
    providerTxId: string,     // Provider's transaction ID
    newBalance: number,            // User's new balance after the rollback
    oldBalance: number,            // User's balance before the rollback
    userId: string,           // User ID
    currency: string          // Currency code (e.g., "ETB")
  }
}
      

4. Currency Codes

• ETB: Ethiopian Birr
• DEMO: Demo currency (for testing purposes)

5. Security

To ensure the integrity of the data being sent, clients must generate a signature for each API request and check validity. This signature verifies that the request data is authentic and has not been tampered with.

Example Code for Generating Signature

import * as crypto from 'crypto';

function createSignature(url, timestamp, body) {
  const { pathname, search } = new URL(url);
  body = body ? JSON.stringify(body) : '';
  const data = `${timestamp}${pathname}${search}${body}`;
  const secret = getSecret(); // get secret key
  const hash = crypto.createHmac('sha256', secret).update(data).digest('hex');
  return hash;
}
      

Parameters for Signature Generation:

• url: The full URL of the request (including the query string).
• timestamp: The timestamp when the request was made.
• body: The body of the request, serialized into a JSON string.

This signature must be included in the request header as X-VC-Client-Signature to ensure the integrity of the request and prevent tampering.