Order Number Rules

Order numbers are unique identifiers used to track transactions in the SmilePayz payment system. Following the correct format ensures successful transaction processing and proper record management.

📋 Requirements

Character Length

• Minimum: 6 characters
• Maximum: 32 characters
• Recommended: 16-24 characters for optimal readability

Allowed Characters

• Numbers: 0-9
• Letters: A-Z, a-z (case-insensitive)
• Special Characters: Not allowed

Uniqueness

• Each order number must be globally unique within your merchant account
• Duplicate order numbers will result in transaction rejection
• Order numbers cannot be reused across different transactions

🚫 Restrictions

• No spaces or special symbols (e.g., !@#$%^&*())
• No hyphens or underscores
• No Unicode or non-ASCII characters
• Cannot start with reserved prefixes used by the system

💡 Best Practices

Recommended Format

[PREFIX][TIMESTAMP][RANDOM]

Example: ORD20241201123456789ABC

Naming Conventions

• Use meaningful prefixes (e.g., PAY, ORD, TXN)
• Include timestamp for chronological ordering
• Add random characters for uniqueness
• Keep consistent format across your application

📝 Implementation Examples

{
  "merchantId": "sandbox-20001",
  "orderNo": "T37484Fx383ksd90383",
  "amount": 1000.00,
  "currency": "THB",
  "paymentMethod": "QRPAY"
}

{
  "merchantId": "20001",
  "orderNo": "37484Fx383ksd90383",
  "amount": 1000.00,
  "currency": "THB",
  "paymentMethod": "QRPAY"
}

⚠️ Common Mistakes

❌ Invalid Examples

"orderNo": "123"           // Too short (less than 6 characters)
"orderNo": "ORDER-123"     // Contains hyphen
"orderNo": "ORDER_123"     // Contains underscore
"orderNo": "ORDER@123"     // Contains special character
"orderNo": "ORDER 123"     // Contains space

✅ Valid Examples

"orderNo": "ORDER123456"   // Valid format
"orderNo": "TXN20241201123456789ABC"  // With timestamp
"orderNo": "PAYMENT001"    // Simple format
"orderNo": "1234567890ABCDEF"  // Alphanumeric

🔍 Validation

The system automatically validates order numbers and will return an error if:

• Length is less than 6 or greater than 32 characters
• Contains invalid characters
• Order number already exists in the system
• Format violates any of the specified rules

📊 Error Response

If an invalid order number is provided, the API will return:

{
  "code": "INVALID_ORDER_NO",
  "message": "Order number format is invalid or already exists",
  "data": null
}

---

Note: Always generate unique order numbers for each transaction to ensure proper tracking and avoid conflicts in the payment system.