Authentication Overview

BIEASES Payment API uses a multi-layered security approach combining RSA digital signatures and AES encryption to ensure the highest level of security for payment transactions.

Security Architecture

Two-Layer Security Model

1. RSA Digital Signatures - Ensures request authenticity and integrity
2. AES Encryption - Protects sensitive payment data in transit

Authentication Flow

Required Credentials

For Sandbox Environment

Credential Type	Purpose	Security Level
Merchant ID	Unique merchant identifier	Public
RSA Private Key	Sign outgoing requests	Confidential
RSA Public Key	Verify BIEASES responses	Public
AES Key	Encrypt/decrypt message body	Confidential
IV String	AES initialization vector	Confidential

For Production Environment

Production credentials follow the same structure but are issued separately after sandbox testing completion.

Authentication Headers

Every API request must include these parameters:

{
  "merchantId": "your_merchant_id",
  "method": "api_method_name",
  "format": "json",
  "charset": "utf-8", 
  "encryptType": "AES",
  "signType": "RSA",
  "sign": "generated_signature",
  "timestamp": 1706585572074,
  "body": "encrypted_request_body"
}

Security Requirements

Key Management

• Private Keys - Store securely, never share or commit to version control
• Key Rotation - Contact support for key rotation when needed
• Environment Isolation - Use separate keys for sandbox and production

Request Validation

• Timestamp Validation - Requests must be within ±5 minutes of current time
• Signature Verification - All requests must include valid RSA signature
• Encryption - Sensitive data must be AES encrypted

Network Security

• HTTPS Only - All API calls must use TLS 1.2 or higher
• IP Whitelisting - Production requires IP address whitelisting
• Rate Limiting - Requests are subject to rate limits (see Rate Limiting)

Getting Credentials

Sandbox Access

1. Complete merchant registration and KYB verification
2. Email support@bieases.com with your merchant ID
3. Receive sandbox credentials within 24 hours
4. Test integration in sandbox environment

Production Access

1. Complete and verify sandbox integration
2. Request production credentials from your account manager
3. Complete security review and IP whitelisting
4. Receive production credentials and go live

Common Authentication Errors

Error Code	Description	Solution
44000	Merchant Certificate not found	Verify merchant ID and credentials
44001	Signature verification failed	Check signature generation process
44003	Body decryption failed	Verify AES key and encryption method
40000	Parameter error	Check required fields and format

Best Practices

Development

• Use Sandbox First - Always test in sandbox before production
• Validate Responses - Always verify response signatures from BIEASES
• Error Handling - Implement proper error handling for auth failures
• Logging - Log authentication events for debugging

Security

• Secure Storage - Use secure key management systems
• Environment Variables - Store credentials in environment variables
• Access Control - Limit access to credentials on need-to-know basis
• Monitoring - Monitor for authentication failures and suspicious activity

Performance

• Cache Keys - Cache parsed keys to avoid repeated parsing
• Connection Pooling - Use HTTP connection pooling for better performance
• Timeout Handling - Implement appropriate timeouts for API calls

---

Next Steps: Learn how to sign requests and verify signatures or explore the API reference.