Authentication Process

Secure Integration Steps for Merchant Authentication

TezPay - Authentication Documentation

🔐 Token-Based Authentication System

TezPay uses a JWT (JSON Web Tokens) based authentication system to secure access to protected endpoints.

📋 Process Overview

  1. Client sends credentials (client_id and client_secret) to /api/v1/tezpay/authenticate
  1. TezPay validates credentials against TezPay internally
  1. TezPay generates a JWT token valid for 12 hours
  1. Client uses the token in subsequent requests via Authorization: Bearer <token>
  1. TezPay validates the token on each protected request

🚀 Authentication Endpoint

POST /api/v1/tezpay/authenticate

Description

Obtains a JWT access token valid for 12 hours to authenticate subsequent requests.

Request Body

{
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "client_secret": "example_client_secret_key_123456789abcdef"
}

Parameters

Field
Type
Required
Description
client_id
string
✅
Unique client ID (UUID)
client_secret
string
✅
Client secret key

Success Response (200)

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZXpfYXV0aF9wb2ludF9pZCI6ImExYjJjM2Q0LWU1ZjYtNzg5MC1hYmNkLWVmMTIzNDU2Nzg5MCIsInRlel9hcGlfa2V5IjoiZXhhbXBsZV9jbGllbnRfc2VjcmV0X2tleV8xMjM0NTY3ODlhYmNkZWYiLCJpYXQiOjE3NTgxNDE2NDQsImV4cCI6MTc1ODIyODA0NH0.example_signature_here",
    "token_type": "bearer",
    "expires_in": 43200,
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Fields

Field
Type
Description
access_token
string
JWT token for authentication
token_type
string
Token type (always "bearer")
expires_in
integer
Seconds until expiration (43200 = 12 hours)
client_id
string
Authenticated client ID

Error Response (401)

{
    "detail": "Invalid credentials"
}

🔒 Protected Endpoints

The following endpoints require authentication token in the header:

POST /api/v1/tezpay/process-payment

  • Description: Process a payment through TezPay
  • Required header: Authorization: Bearer <token>

GET /api/v1/tezpay/get-status

  • Description: Get transaction status
  • Required header: Authorization: Bearer <token>

📝 Usage Examples

1. Get Token

curl -X POST "http://localhost:8001/api/v1/tezpay/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "client_secret": "example_client_secret_key_123456789abcdef"
  }'

2. Use Token in Protected Request

curl -X POST "http://localhost:8001/api/v1/tezpay/process-payment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
	    "payment_method": "IMPS_IN",
    "transaction_amount": 500,
    "merchant_reference": "PAY123456"
  }'

3. Get Transaction Status

curl -X GET "http://localhost:8001/api/v1/tezpay/get-status?transaction_id=TXN123456" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

⏰ Token Management

Token Duration

  • Validity: 12 hours (43200 seconds)
  • Renewal: Requires new authentication
  • Expiration: Token invalid after 12 hours

Handling Expired Token

{
    "detail": "Token has expired"
}
Solution: Re-authenticate with /api/v1/tezpay/authenticate

🔧 Token Configuration

Signing Algorithm

  • Algorithm: HS256 (HMAC SHA-256)
  • Secret: Configured in JWT_SECRET_KEY

Token Payload

{
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "client_secret": "example_client_secret_key_123456789abcdef",
    "iat": 1758141644,
    "exp": 1758228044
}

🛡️ Security

Best Practices

  1. Store token securely (not in localStorage)
  1. Renew token before expiration (every 11 hours)
  1. Use HTTPS in production
  1. Don't share credentials between clients

Credential Validation

  • TezPay validates credentials against TezPay Dashboard API
  • Verification of client_id and client_secret
  • Validation of active and authorized merchant

🚨 Error Codes

Code
Description
Solution
401
Invalid credentials
Verify client_id and client_secret
401
Token has expired
Re-authenticate
401
Invalid token
Verify token format
403
Access denied
Verify merchant permissions
500
Authentication service error
Contact support

📊 Authentication Flow

sequenceDiagram
    participant C as Client
    participant T as TezPay
    participant P as TezPay

    C->>T: POST /authenticate
    Note over C,T: {client_id, client_secret}

    T->>P: Validate credentials
    P-->>T: Valid merchant

    T->>T: Generate JWT (12h)
    T-->>C: {access_token, expires_in}

    Note over C: Token valid for 12 hours

    C->>T: POST /process-payment
    Note over C,T: Authorization: Bearer <token>

    T->>T: Validate token
    T->>P: Process payment
    P-->>T: Result
    T-->>C: Response

🔄 Token Renewal

Recommended Strategy

  1. Monitor expiration time
  1. Renew automatically at 11 hours
  1. Handle renewal errors
  1. Fallback to manual re-authentication

Renewal Example

// Renew token every 11 hours
setInterval(async () => {
    try {
        const response = await authenticate(clientId, clientSecret);
        updateToken(response.access_token);
    } catch (error) {
        console.error('Token renewal failed:', error);
    }
}, 11 * 60 * 60 * 1000); // 11 hours in ms

📞 Support

For authentication issues:
  1. Verify credentials in TezPay Dashboard
  1. Check TezPay logs
  1. Contact technical support