API Endpoints Migration - Saber Money

This document describes the migration of API endpoints to the api.saber.money domain. We organize endpoints by service and provide migration paths, request/response formats, and error code mappings.

Base URL: https://api.saber.money

Migration Overview

This migration involves two types of changes for 9 client-related endpoints:

Change 1: Python to Go User Service Migration

2 endpoints currently in Python User Service (/api/user_services/v1/*) migrate to Go User Service.

Affected Endpoints:

1. POST /api/user_services/v1/user_kyc/v2/bank_account
2. GET /api/user_services/v1/user_kyc/bank_status

Migration Path:

• Step 1: Python endpoint → Go User Service endpoint with /client_user segment
• Step 2: Remove /client_user segment (path sanitization)

Change 2: Path Sanitization (Remove /client_user)

7 endpoints with /client_user in the path have this segment removed for cleaner, more RESTful URLs.

Path Pattern:

• Before: /api/v1/user/client_user/*
• After: /api/v1/user/*

Affected Endpoints:

1. GET /api/v1/user/client_user
2. POST /api/v1/user/client_user
3. POST /api/v1/user/client_user/kyc/initiate
4. GET /api/v1/user/client_user/kyc
5. POST /api/v1/user/client_user/kyc/upload_document
6. POST /api/v1/user/client_user/bank_account
7. DELETE /api/v1/user/client_user/bank_account

User Services Endpoints (Python → Go User Service Migration)

1. Bank Account (v2)

Current Endpoint:

• Python User Service: POST /api/user_services/v1/user_kyc/v2/bank_account

Migration Path:

Final Endpoint:

• Go User Service: POST /api/v1/user/bank_account

Description: Adds or updates a bank account for KYC verification.

Headers:

m-account-id: <user_uuid>
m-organization-id: <client_uuid>
Content-Type: application/json

Current Request Body:

{
  "action": "add",
  "bank_account_details": {
    "account_number": "1234567890",
    "ifsc_code": "SBIN0001234",
    "type": "SAVINGS",
    "bank_id": "<uuid>"
  }
}

New Request Body (After Migration):

{
  "account_number": "1234567890",
  "bank_code": "SBIN0001234",
  "country_iso3": "IND",
  "account_holder_name": "John Doe",
  "bank_name": "State Bank of India",
  "routing_type": "IFSC"
}

Current Response (Success - 200):

{
  "success": true,
  "data": {
    "message": "The user bank account added successfully, awaiting for verification"
  }
}

New Response (Success - 200):

{
  "success": true,
  "data": "Bank account added successfully, awaiting for verification"
}

Current Error Codes:

• 3001 - PARAMETERS_MISSING
• 3003 - INCORRECT_PARAMETERS (Invalid IFSC)
• 3005 - DUPLICATE_ERROR
• 6094 - BAD_PARAMETERS
• 6103 - THIRD_PARTY_FAILURE
• 6104 - OUT_OF_FLOW
• 6111 - FIELD_CANNOT_BE_EMPTY
• 6119 - LIMIT_EXCEEDED
• 6127 - BANK_ACCOUNT_REQUIRED_VALIDATION_FAILED
• 5997 - REQUESTS_ERROR
• 5999 - UNKNOWN

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request
• 403001 - Invalid Request: Invalid request data or transaction parameters (invalid account number, bank code, country, etc.)

403 Forbidden:

• 404001 - Limits Validation Failed: Transaction limits validation failed (bank account limit exceeded - maximum 10 accounts)

404 Not Found:

• 405001 - Invalid User for Client: User does not exist or does not belong to the specified client

409 Conflict:

• 403004 - Duplicate Transaction ID: Duplicate bank account (bank account already exists in approved/pending/rejected status)

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

503 Service Unavailable:

• 6103 - Third Party Failure: External service failure (penny drop verification, validation services, etc.)

Error Code Mapping:

2. Bank Status

Current Endpoint:

• Python User Service: GET /api/user_services/v1/user_kyc/bank_status

Migration Path:

Final Endpoint:

• Go User Service: GET /api/v1/user/bank_status

Description: Retrieves the status of the user's bank account verification.

Headers:

m-account-id: <user_uuid>
m-organization-id: <client_uuid>

Query Parameters:

• bank_updation (boolean, optional): Check bank updation eligibility status, defaults to false

Current Response (Success - 200):

{
  "success": true,
  "data": {
    "account_number": "1234567890",
    "masked_account_number": "****7890",
    "account_holder_name": "John Doe",
    "ifsc_code": "SBIN0001234",
    "account_type": "SAVINGS",
    "validation_status": "VERIFIED",
    "message": "Bank account verified successfully",
    "is_name_verified": true,
    "name_match_score": 95.5,
    "is_nre": false,
    "uuid": "<bank_account_uuid>",
    "updated_at": "2024-01-15T10:30:00Z",
    "updation_status": false,
    "updation_message": "Maximum bank update attempts reached"
  }
}

New Response (Success - 200): (Same structure)

Current Error Codes:

• 6111 - FIELD_CANNOT_BE_EMPTY
• 5999 - UNKNOWN
• 5998 - DB_ERROR
• 5997 - REQUESTS_ERROR

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request

404 Not Found:

• 405001 - Invalid User for Client: User does not exist or does not belong to the specified client

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

Error Code Mapping:

User Services Endpoints (Path Sanitization - /api/v1/user/client_user/*)

These endpoints are already in Go User Service and require path sanitization from /api/v1/user/client_user/* to /api/v1/user/*.

1. Get User

Current Endpoint:

• Go User Service: GET /api/v1/user/client_user

After Migration:

• Go User Service: GET /api/v1/user

Description: Retrieves client user information including user details, KYC status, and bank accounts.

Headers:

m-account-id: <user_uuid>
m-organization-id: <client_uuid>

Request: No request body (GET endpoint)

Response (Success - 200):

{
  "success": true,
  "data": {
    "user_uuid": "<user_uuid>",
    "client_user_id": "CLIENT_USER_123",
    "kyc_status": "Verified",
    "bank_accounts": [
      {
        "account_number": "****7890",
        "ifsc_code": "SBIN0001234",
        "account_type": "SAVINGS",
        "validation_status": "VERIFIED"
      }
    ],
    "is_nri": false,
    "email": "user@example.com",
    "phone": "+1234567890",
    "phone_country": {
      "name": "India",
      "iso2": "IN"
    },
    "kyc_country": {
      "name": "India",
      "iso2": "IN"
    }
  }
}

Current Error Codes:

• 5004 - User details not found (HTTP 404)
• HTTP 500 - Internal server error

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request

404 Not Found:

• 405001 - Invalid User for Client: User does not exist or does not belong to the specified client

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

Error Code Mapping:

2. Add User

Current Endpoint:

• Go User Service: POST /api/v1/user/client_user

After Migration:

• Go User Service: POST /api/v1/user

Description: Creates a new client user.

Headers:

m-organization-id: <client_uuid>
Content-Type: application/json

Request Body:

{
  "user_uuid": "<user_uuid>",
  "client_user_id": "CLIENT_USER_123",
  "email": "user@example.com",
  "phone": "+1234567890"
}

Response (Success - 200):

{
  "success": true,
  "data": {
    "user_id": "<user_uuid>",
    "client_user_id": "CLIENT_USER_123"
  }
}

Current Error Codes:

• 5999 - Unknown error
• 5004 - Email/Phone is required, Email is not valid, Error registering user
• 6092 - Invalid User UUID, User Already Exist

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request (email/phone required, invalid email format, invalid UUID format)

403 Forbidden:

• 404001 - Limits Validation Failed: Transaction limits validation failed (max user cap reached)

409 Conflict:

• 403004 - Duplicate Transaction ID: User already exists (duplicate user_uuid, client_user_id, email, or phone)

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

Error Code Mapping:

3. Initiate KYC

Current Endpoint:

• Go User Service: POST /api/v1/user/client_user/kyc/initiate

After Migration:

• Go User Service: POST /api/v1/user/kyc/initiate

Description: Initiates KYC verification for a user.

Headers:

m-account-id: <user_uuid>
m-organization-id: <client_uuid>
Content-Type: application/json

Request Body:

{
  "country": "India",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-01",
  "address": {
    "line1": "123 Main St",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001",
    "country": "India"
  },
  "user_nationality_iso2": "IN"
}

Response (Success - 200):

{
  "success": true,
  "data": "KYC initiated successfully"
}

Current Error Codes:

• 5999 - Unknown error
• HTTP 400 - Invalid User UUID or Org UUID, Invalid date of birth format, Invalid country passed, User KYC already initiated/approved/rejected/under review

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request (invalid UUID, invalid date format, invalid country, age < 18)

403 Forbidden:

• 403001 - Invalid Request: User KYC already initiated, approved, rejected, or under review

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

503 Service Unavailable:

• 6103 - Third Party Failure: External service failure (KYC provider services)

Error Code Mapping:

4. Get KYC

Current Endpoint:

• Go User Service: GET /api/v1/user/client_user/kyc

After Migration:

• Go User Service: GET /api/v1/user/kyc

Description: Retrieves KYC information for a user.

Headers:

m-account-id: <user_uuid>
m-organization-id: <client_uuid>

Query Parameters:

• user_id (uuid, required): User UUID to get KYC info

Request: No request body (GET endpoint)

Response (Success - 200):

{
  "success": true,
  "data": {
    "user_uuid": "<user_uuid>",
    "client_user_id": "CLIENT_USER_123",
    "kyc_status": "Verified",
    "bank_accounts": [],
    "is_nri": false,
    "email": "user@example.com",
    "phone": "+1234567890",
    "phone_country": {
      "name": "India",
      "iso2": "IN"
    },
    "kyc_country": {
      "name": "India",
      "iso2": "IN"
    }
  }
}

Current Error Codes:

• HTTP 400 - Bad request (Invalid user_id provided)
• HTTP 500 - Internal server error

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request (invalid user_id UUID format)

404 Not Found:

• 405001 - Invalid User for Client: User does not exist or does not belong to the specified client

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

Error Code Mapping:

5. Upload KYC Document

Current Endpoint:

• Go User Service: POST /api/v1/user/client_user/kyc/upload_document

After Migration:

• Go User Service: POST /api/v1/user/kyc/upload_document

Description: Uploads KYC document (Aadhar XML) for verification.

Headers:

m-account-id: <user_uuid>
m-organization-id: <client_uuid>
Content-Type: multipart/form-data

Request Body (Form Data):

file: <xml_file>

Response (Success - 200):

{
  "success": true,
  "data": {
    "message": "Document uploaded successfully"
  }
}

Current Error Codes:

• 5999 - Unknown error
• 5004 - User is required, Invalid file format, Invalid Aadhar XML format, User KYC details not found, User already verified

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request (user required, invalid file format, invalid XML format)

403 Forbidden:

• 403001 - Invalid Request: User already verified

404 Not Found:

• 405001 - Invalid User for Client: User KYC details not found

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

503 Service Unavailable:

• 6103 - Third Party Failure: External service failure (S3 upload, document processing services)

Error Code Mapping:

6. Add Bank Account

Current Endpoint:

• Go User Service: POST /api/v1/user/client_user/bank_account

After Migration:

• Go User Service: POST /api/v1/user/bank_account

Description: Adds a bank account for the user.

Headers:

m-account-id: <user_uuid>
m-organization-id: <client_uuid>
Content-Type: application/json

Request Body:

{
  "account_number": "1234567890",
  "bank_code": "SBIN0001234",
  "country_iso3": "IND",
  "account_holder_name": "John Doe",
  "bank_name": "State Bank of India",
  "routing_type": "IFSC"
}

Response (Success - 200):

{
  "success": true,
  "data": "Bank account added successfully, awaiting for verification"
}

Current Error Codes:

• 5999 - Unknown error (validation errors, invalid country, etc.)

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request
• 403001 - Invalid Request: Invalid request data or transaction parameters (invalid account number, bank code, country, account type, etc.)

403 Forbidden:

• 404001 - Limits Validation Failed: Transaction limits validation failed (bank account limit exceeded)

404 Not Found:

• 405001 - Invalid User for Client: User does not exist or does not belong to the specified client

409 Conflict:

• 403004 - Duplicate Transaction ID: Duplicate bank account (bank account already exists)

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

503 Service Unavailable:

• 6103 - Third Party Failure: External service failure (penny drop, validation services, etc.)

Error Code Mapping:

7. Delete Bank Account

Current Endpoint:

• Go User Service: DELETE /api/v1/user/client_user/bank_account

After Migration:

• Go User Service: DELETE /api/v1/user/bank_account

Description: Deletes a bank account for the user.

Headers:

m-account-id: <user_uuid>
m-organization-id: <client_uuid>
Content-Type: application/json

Request Body:

{
  "bank_account_uuid": "<bank_account_uuid>",
  "message": "Account deleted by user"
}

Response (Success - 200):

{
  "success": true,
  "data": {
    "message": "The user bank account deleted successfully."
  }
}

Current Error Codes:

• 5999 - Unknown error, bank_id cannot be empty, Invalid user, Invalid bank_id format, No matching bank account found
• HTTP 404 - Not found (bank account not found)

New Standard Error Codes (Based on apis/error-codes):

400 Bad Request:

• 400001 - Missing or Invalid Parameters: Missing or invalid parameters in the request (bank_id cannot be empty, invalid bank_id format)

404 Not Found:

• 405001 - Invalid User for Client: User does not exist or bank account not found

500 Internal Server Error:

• 499999 - General Internal Server Error: Generic system error used for masked 5xx responses

Error Code Mapping:

Endpoints Migration Summary

Endpoints Requiring Python → Go User Service Migration (2 endpoints)

Endpoints Requiring Only Path Sanitization (Already in Go User Service - /api/v1/user/client_user/*)

These endpoints are already in Go User Service and only require path sanitization (removing /client_user segment):

Standard HTTP Status Codes

All endpoints use the following standard HTTP status codes:

• 200 OK: Request succeeded
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request parameters or format
• 401 Unauthorized: Authentication required or failed
• 403 Forbidden: Valid request but operation not allowed
• 404 Not Found: Resource not found
• 409 Conflict: Resource conflict (duplicate, already exists)
• 422 Unprocessable Entity: Valid format but semantic errors
• 423 Locked: Resource is locked (validation pending, etc.)
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error
• 503 Service Unavailable: Service temporarily unavailable

Path Sanitization Summary

The following paths have been sanitized:

From /api/v1/user/client_user/* to /api/v1/user/*:

1. GET /api/v1/user/client_user → GET /api/v1/user
2. POST /api/v1/user/client_user → POST /api/v1/user
3. POST /api/v1/user/client_user/kyc/initiate → POST /api/v1/user/kyc/initiate
4. GET /api/v1/user/client_user/kyc → GET /api/v1/user/kyc
5. POST /api/v1/user/client_user/kyc/upload_document → POST /api/v1/user/kyc/upload_document
6. POST /api/v1/user/client_user/bank_account → POST /api/v1/user/bank_account
7. DELETE /api/v1/user/client_user/bank_account → DELETE /api/v1/user/bank_account

Migration Status

✅ Completed

• Path sanitization documentation for all affected endpoints
• Error code standardization based on apis/error-codes
• Migration plan documentation
• Request/response documentation for key endpoints
• Interservice call identification
• Current error code to standard error code mapping

⚠️ Pending

Python to Go User Service Migration (2 endpoints only)

1. POST /api/user_services/v1/user_kyc/v2/bank_account → POST /api/v1/user/bank_account
2. GET /api/user_services/v1/user_kyc/bank_status → GET /api/v1/user/bank_status

Path Sanitization (All endpoints with /client_user)

• All /api/v1/user/client_user/* endpoints → Remove /client_user segment
• This includes 7 endpoints already in Go User Service:
  1. GET /api/v1/user/client_user → GET /api/v1/user
  2. POST /api/v1/user/client_user → POST /api/v1/user
  3. POST /api/v1/user/client_user/kyc/initiate → POST /api/v1/user/kyc/initiate
  4. GET /api/v1/user/client_user/kyc → GET /api/v1/user/kyc
  5. POST /api/v1/user/client_user/kyc/upload_document → POST /api/v1/user/kyc/upload_document
  6. POST /api/v1/user/client_user/bank_account → POST /api/v1/user/bank_account
  7. DELETE /api/v1/user/client_user/bank_account → DELETE /api/v1/user/bank_account

Notes

• All endpoints use the base URL: https://api.saber.money
• Authentication headers are required for most endpoints (varies by endpoint)
• Error responses follow a consistent format with success: false and errors array
• Success responses follow a consistent format with success: true and data object
• All error codes follow the standard error code framework from apis/error-codes documentation
• HTTP status codes align with the error type (400 for client errors, 500 for server errors, etc.)
• Migration Timeline: Python endpoints are deprecated after Go User Service migration is complete
• Backward Compatibility: Old endpoints may be maintained for a transition period before full deprecation
• Only 2 endpoints require Python → Go User Service migration: All other endpoints are already in Go User Service and only need path sanitization
• Interservice Calls: Some endpoints make interservice calls to portfolio-services, darwin services, and auth-services. These are highlighted in the endpoint documentation.
• Error Code Migration: All current error codes have been mapped to standard error codes from apis/error-codes. See error code mapping tables in each endpoint section.