Surepass Encrypted API Integration Guide

📋 Overview

This guide provides comprehensive instructions for integrating with the Surepass Encrypted API, which uses RSA-2048 + AES-256-GCM encryption to secure all data transmission between your application and our services.

Prerequisites

Before starting your integration, ensure you have:

Valid Surepass API credentials (Bearer token)

Your assigned Client ID

RSA key pair provided by Surepass

Basic understanding of HTTP APIs and encryption concepts

🔑 Security Keys Setup

Your Surepass representative will provide three essential components:

client-id: your-company@surepass.io

client-private-key.pem - Your private key (keep secure!)

surepass-public-key.pem - Surepass public key (for encryption)

Important: Never commit private keys to version control or log them in your application.

Environment Configuration

Store your credentials securely using environment variables:

Environment	API Base URL
Sandbox	https://sandbox-encrypted.surepass.app
Production	https://kyc-api-encrypted.surepass.app
Superflow Sandbox	https://superflow-sandbox-encrypted.surepass.app
Superflow Prod	https://superflow-encrypted.surepass.app

API Flow Comparison

Encrypted API Flow

Your App → Encrypt Request → HTTPS → Decrypt → Surepass API
                                                              ↓
Your App ← Decrypt Response ← HTTPS ← Encrypt ← Response

Enhanced security with end-to-end encryption using RSA + AES hybrid encryption.

Request Format Structure

Prepare Your Data

Create your request payload as usual (JSON, form-data, etc.)

Encrypt the Payload

Generate random AES-256 key and IV

Encrypt your data with AES-256-GCM

Encrypt the AES key with Surepass's RSA public key

Combine into encrypted payload format

Set Required Headers

Send Encrypted Request

The request body contains the encrypted payload string in the format:
encrypted_aes_key:iv:encrypted_data:auth_tag

Response Handling

📥 Decryption Process

Receive encrypted response (HTTP 200)

Extract AES key, IV, data, and auth tag from response

Decrypt AES key using your RSA private key

Decrypt response data using AES-256-GCM

Parse the decrypted JSON data

Language-Specific Integration

Python

Node.js

Java

Installation

Basic Implementation

Testing Your Integration

Test PAN Verification

{
  "pan_number": "ABCDE1234F"
}

Expected response should return PAN details with success status.

Test File Upload (PAN OCR)

Upload a sample PAN card image to test OCR functionality.
Expected response should include extracted PAN information with confidence scores.

Verify Response Format

Ensure decrypted responses match the standard API format:

{
  "success": true,
  "status_code": 200,
  "data": { ... },
  "message": null,
  "message_code": "success"
}

Encryption Public Keys

Public Key Description	Link	URL
Superflow Production Public Key	Link	https://cdn.surepass.app/public-keys/superflow-production-at-surepass.app-public-key.pem
Superflow Sandbox Public Key	Link	https://cdn.surepass.app/public-keys/superflow-sandbox-at-surepass.app-public-key.pem
Surepass Production Public Key	Link	https://cdn.surepass.app/public-keys/surepass-production-at-surepass.app-public-key.pem
Surepass Sandbox Public Key	Link	https://cdn.surepass.app/public-keys/surepass-sandbox-at-surepass.app-public-key.pem

Security Best Practices

🔒 Security Guidelines

Never log private keys or decrypted sensitive data

Validate certificates during HTTPS requests

Use secure key storage (environment variables, key vaults)

Rotate keys regularly as advised by Surepass

Implement proper error handling without exposing sensitive information

Performance Optimization

⚡ Performance Tips

Cache key objects instead of re-importing PEM keys for each request

Reuse HTTP connections for multiple requests

Consider async/parallel processing for batch operations

Implement connection pooling for high-volume applications

Common Issues & Solutions

Encryption Errors

Network Issues

Key Management

Issue: Decryption fails or returns garbled data
Solutions:

Verify client ID matches registered public key

Ensure private key corresponds to registered public key

Check AES key generation and IV handling

Validate auth tag extraction and verification

Support Resources

📚 Additional Resources

API Documentation: https://app.surepass.app/docs/kyc

Support Portal: support@surepass.io

Example Code Repository: Github link

For technical support or integration assistance, please contact your Surepass representative or visit our support portal.

🔑 Security

Surepass Encrypted API Integration Guide#

Prerequisites#

Environment Configuration#

API Flow Comparison#

Request Format Structure#

Response Handling#

Language-Specific Integration#

Installation#

Basic Implementation#

Testing Your Integration#

Encryption Public Keys#

Security Best Practices#

Performance Optimization#

Common Issues & Solutions#

Support Resources#