RSA Key Generation Guide

RSA (Rivest-Shamir-Adleman) key pairs are essential for secure API communication with SmilePayz. This guide explains how to generate and manage your RSA keys for both sandbox and production environments.

🔐 Key Types

Private Key

• Usage: Used for signing API requests
• Storage: Must be stored securely by the merchant
• Security: Never share or expose your private key
• Format: PEM format (Base64 encoded)

Public Key

• Usage: Uploaded to SmilePayz for request verification
• Format: Must be without prefixes and suffixes
• Storage: Stored securely on SmilePayz servers

Security Best Practice

For enhanced security, use different key pairs for sandbox and production environments to prevent cross-environment access.

🚀 Generation Process

Step 1: Access Merchant Backend

1. Navigate to Merchant Backend
2. Log in with your merchant credentials
3. Locate the Configuration section

Step 2: Generate RSA Keys

1. Find the "Generate RSA Keys" button
2. Click the button to initiate key generation
3. The browser will automatically download a key pair file
4. The public key will be automatically populated in the input field

Step 3: Save Configuration

1. Review the generated public key
2. Click "Save" to store the public key on SmilePayz servers
3. Keep the downloaded file containing your private key secure

📁 Key File Structure

The downloaded file contains:

-----BEGIN PRIVATE KEY-----
[Your Private Key Content]
-----END PRIVATE KEY-----

-----BEGIN PUBLIC KEY-----
[Your Public Key Content]
-----END PUBLIC KEY-----

🔧 Implementation Examples

Sandbox Environment

Production Environment

📹 Video Tutorial

For visual guidance, refer to our Setting Video Tutorial.

⚠️ Security Requirements

Critical Security Notice

RSA keys with less than 2048 bits are no longer considered secure for encryption or digital signatures. Always use 2048-bit or higher RSA keys.

Security Checklist

• ✅ Use 2048-bit or higher RSA keys
• ✅ Store private keys securely (encrypted at rest)
• ✅ Use different keys for sandbox and production
• ✅ Never share private keys
• ✅ Regularly rotate keys (recommended: annually)
• ✅ Monitor key usage and access logs

🔍 Key Validation

Private Key Requirements

• Algorithm: RSA
• Key Size: Minimum 2048 bits
• Format: PEM (Privacy Enhanced Mail)
• Encoding: Base64

Public Key Requirements

• Algorithm: RSA
• Key Size: Minimum 2048 bits
• Format: PEM without headers/footers
• Content: Only the key content, no extra characters

🛠️ Troubleshooting

Common Issues

Issue	Solution
Key size too small	Generate new 2048-bit or higher key
Invalid format	Ensure PEM format without extra characters
Upload failure	Check public key format and remove prefixes
API signature errors	Verify private key is correctly stored

Error Messages

{
  "code": "INVALID_RSA_KEY",
  "message": "RSA key format is invalid or key size is insufficient",
  "data": null
}

📋 Best Practices

Key Management

• Backup: Keep secure backups of your private keys
• Rotation: Plan for regular key rotation
• Access Control: Limit access to private keys
• Monitoring: Monitor for unauthorized key usage

Development Workflow

1. Generate sandbox keys for testing
2. Test thoroughly with sandbox keys
3. Generate production keys for live deployment
4. Never use sandbox keys in production

---

Note: RSA key generation is a one-time setup process. Once configured correctly, your keys will be used for all API communications with SmilePayz.