Balance

Endpoint Overview

GET /api/v1/utils/usage/balance

Description

This API endpoint allows you to retrieve the remaining balance in your Surepass account. It provides real-time information about your available credits, helping you monitor your usage and plan for replenishment before reaching critical levels. The balance information includes details about your current credit status, allowing for effective resource management and budget planning.

Key Benefits

Real-time visibility into your account balance

Proactive monitoring to prevent service interruptions

Simplified budget tracking and resource allocation

Automated integration with your internal systems for balance alerts

Use Cases

Financial Services

FinTech

Enterprise

Monitor KYC verification credits to ensure uninterrupted customer onboarding

Automate balance checks to trigger purchase orders when credits fall below threshold

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <your_token>`
Content-Type	Yes	Set to `application/json`

Request Body

This endpoint does not require a request body.

Process Response

Response Parameters

Parameter	Type	Description
success	Boolean	Indicates if the request was successful
balance	Number	The remaining balance (credits) in the account
message	String	A descriptive message about the balance status

Example Successful Response

{
  "success": true,
  "balance": 5000,
  "message": "Your current balance is 5000 credits"
}

Possible Error Responses

Authentication Error

Server Error

{
  "success": false,
  "error": "unauthorized",
  "message": "Invalid or expired token"
}

This error occurs when the provided JWT token is invalid, expired, or missing.

Integration Best Practices

Security Recommendations

Store API credentials securely using environment variables or a secrets manager

Implement token refresh mechanisms to handle token expiration gracefully

Limit access to balance information to authorized personnel only

User Experience Guidelines

Implement visual indicators when balance falls below certain thresholds

Schedule automated balance checks during off-peak hours

Cache balance information with appropriate TTL to reduce API calls

Code Samples

cURL

Python

Node.js

Related APIs

Usage History API: Retrieve detailed usage history for your account

Credit Purchase API: Add more credits to your account

Usage Alerts API: Configure notifications for low balance thresholds

Compliance and Legal Considerations

Balance information is considered sensitive account data. Ensure that access to this information is restricted to authorized personnel only. Implement appropriate access controls and audit logging when integrating this API into your systems.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Balance

Balance#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Balance

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples