Sandbox Environment Guide

Overview

The Zebec Partner Service provides a sandbox environment in development and test deployments that allows partners to test their integrations without connecting to the real card processing backend. This sandbox mode simulates all the expected behaviors of the production API while providing predictable responses based on test data patterns.

Availability

Environment: Development (NODE_ENV=development) and Test (NODE_ENV=test)
URL: Same as development API endpoints
Authentication: Same HMAC authentication as production
API Versions: Both v1 (Standard) and v2 (Premium) endpoints are supported in sandbox mode

How It Works

Automatic Activation

The sandbox mode is automatically activated when the service runs in development or test environment. No special configuration or API changes are required - simply use the same endpoints and authentication as production.

Request Processing

Validation: All standard validations are enforced (balance checking, request format, authentication)
Status Determination: Order status is determined by the recipient's email address pattern
Database Operations: Orders are saved to the database just like in production
Balance Management: Client balance is updated according to the order status

Email-Based Response Patterns

The sandbox determines the order outcome based on the recipient's email address:

Success Orders (Default)

Pattern: Any email that doesn't match the special patterns below
Status: SUCCESS
Examples:

john.doe@example.com
test.user@company.co.uk
partner.integration@domain.org

Response Includes:

Mock card details (masked card number, expiry, security code)
Activation instructions
Estimated delivery timeframe

Pending Orders

Pattern: Email addresses ending with .pending
Status: PENDING
Examples:

test.user@example.pending
compliance.check@domain.pending
VERIFICATION@TEST.PENDING (case-insensitive)

Response Includes:

Reason for pending status
Estimated completion timeframe
Next steps information

Failed Orders

Pattern: Email addresses ending with .failed
Status: FAILED
Examples:

invalid.address@example.failed
compliance.reject@domain.failed
TEST@EXAMPLE.FAILED (case-insensitive)

Response Includes:

Failure reason and error code
Retry eligibility flag
Suggested corrective actions

Example Usage

Testing Success Flow

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": {
    "participantId": "TEST001",
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    // ... other recipient fields
  },
  "amount": {
    "amount": 100.00,
    "currencyCode": "USD"
  }
}

Response:

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SUCCESS",
  "cardDetails": {
    "cardNumber": "**** **** **** 1234",
    "expiryDate": "12/26",
    "securityCode": "***"
  },
  "activationInstructions": "Card will be activated within 24 hours",
  "deliveryMethod": "email",
  "estimatedDelivery": "2024-01-02T12:00:00.000Z"
}

Testing Pending Flow

{
  "recipient": {
    "emailAddress": "compliance.review@example.pending",
    // ... other fields
  }
}

Response:

{
  "status": "PENDING",
  "reason": "Additional verification required",
  "estimatedCompletion": "2024-01-03T12:00:00.000Z",
  "nextSteps": "Awaiting manual review by compliance team"
}

Testing Failure Flow

{
  "recipient": {
    "emailAddress": "bad.address@example.failed",
    // ... other fields
  }
}

Response:

{
  "status": "FAILED",
  "reason": "Recipient address validation failed",
  "errorCode": "ADDR_VALIDATION_ERROR",
  "canRetry": true,
  "suggestions": [
    "Verify the recipient address is complete and accurate",
    "Ensure the postal code matches the city and state"
  ]
}

v2 Premium Endpoint Sandbox Behavior

The v2 Premium endpoints (GET /v2/cards/{orderId}, GET /v2/cards/{orderId}/balance, POST /v2/cards/{orderId}/transactions) also respect the same email pattern conventions. The sandbox behavior is determined by the recipient email used during order creation.

💎 Active Card (Default Email Pattern)

Order Created With: john.doe@example.com (or any normal email)

v2 Card Details Response:

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "cardId": "abc-123-def-456",
  "status": "ACTIVE",
  "cardNumber": "**** **** **** 1234",
  "balance": {
    "available": 100.00,
    "pending": 0,
    "currency": "USD"
  },
  "cardholder": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}

v2 Transactions Response: Returns 10 mock transactions (purchases and refunds at various merchants)

⏳ Pending Card (.pending Email Pattern)

Order Created With: compliance@example.pending

v2 Card Details Response:

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "cardId": "abc-123-def-456",
  "status": "PENDING",
  "cardNumber": "**** **** **** 1234",
  "balance": {
    "available": 0,
    "pending": 100.00,
    "currency": "USD"
  },
  "cardholder": {
    "name": "John Doe",
    "email": "compliance@example.pending"
  }
}

v2 Transactions Response:

{
  "transactions": [],
  "page": 1,
  "totalPages": 0,
  "totalCount": 0,
  "message": "Card is pending activation - no transactions yet"
}

❌ Suspended Card (.failed Email Pattern)

Order Created With: rejected@example.failed

v2 Card Details Response:

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "cardId": "abc-123-def-456",
  "status": "SUSPENDED",
  "cardNumber": "**** **** **** 1234",
  "balance": {
    "available": 0,
    "pending": 0,
    "currency": "USD"
  },
  "cardholder": {
    "name": "John Doe",
    "email": "rejected@example.failed"
  }
}

v2 Transactions Response:

{
  "transactions": [],
  "page": 1,
  "totalPages": 0,
  "totalCount": 0,
  "message": "Card is suspended - no transactions available"
}

Testing v2 Endpoints

Complete Test Flow:

Create order with specific email pattern (e.g., test@example.pending)
Order succeeds and orderId is returned
Call v2 endpoints with the orderId
Observe card status, balance, and transactions match the email pattern

Example Test Sequence:

# 1. Create order with .pending email
POST /orders/create
{
  "recipient": { "emailAddress": "kyc@example.pending", ... }
}

# 2. Get card details - should show PENDING status
GET /v2/cards/{orderId}
→ Returns status: "PENDING", balance.available: 0, balance.pending: 100

# 3. Get balance - should show pending balance
GET /v2/cards/{orderId}/balance
→ Returns balance: 0, pending: 100

# 4. Get transactions - should be empty
POST /v2/cards/{orderId}/transactions
→ Returns empty array with message about pending activation

Important Behaviors

✅ What Still Works Like Production

Authentication: Full HMAC signature validation
Balance Validation: Real balance checking against deposits/purchases
Request Validation: All DTOs and business rules enforced
Database Operations: Orders saved, balance updated, transaction integrity
Error Handling: Proper HTTP status codes and error responses

🎭 What's Different in Sandbox

External Calls: No calls made to real card processing backend
Processing Time: Simulated delays (0.5-5 seconds based on status)
Card Details: Mock card information in successful responses
Status Determination: Based on email patterns, not real processing

💰 Balance Impact

SUCCESS: Order amount is deducted from balance
PENDING: Order amount is deducted from balance
FAILED: Order amount is NOT deducted (no charge for failed orders)

Integration Testing Strategy

Recommended Test Cases

Happy Path Testing

Email: success.test@company.com
Expected: SUCCESS status with card details

Compliance Workflow Testing

Email: kyc.review@company.pending
Expected: PENDING status with review information

Error Handling Testing

Email: invalid.data@company.failed
Expected: FAILED status with error details

Balance Validation Testing

Order amount > Available balance
Expected: 400 Bad Request with insufficient balance error

Authentication Testing

Invalid/missing HMAC headers
Expected: 401 Unauthorized

Automated Testing

Use different email patterns to test all workflows:

const testCases = [
  { email: "success@example.com", expectedStatus: "SUCCESS" },
  { email: "pending@example.pending", expectedStatus: "PENDING" },
  { email: "failed@example.failed", expectedStatus: "FAILED" },
  { email: "MIXED@CASE.PENDING", expectedStatus: "PENDING" } // Case insensitive
];

Production Differences

When your integration moves to production:

Same API endpoints and authentication
Real card processing with external providers
Actual processing times (may take minutes/hours)
Real card details in successful responses
No email pattern-based status determination

Support and Debugging

Sandbox Indicators

All sandbox responses include a sandbox: true flag in the card server response data for easy identification during debugging.

Logging

The sandbox service logs all operations with the [SANDBOX] prefix for easy filtering:

[SANDBOX] Processing card order abc-123 for client TestClient
[SANDBOX] Email test@example.pending → Status: PENDING
[SANDBOX] Order abc-123 completed with status PENDING

Common Issues

Unexpected Status: Check email pattern exactly (case-insensitive matching)
Balance Errors: Verify sufficient deposits vs. purchase history
Authentication Errors: Same HMAC validation as production - check signature generation

For additional support, contact the development team or check the main API documentation.

Development Notes

The sandbox implementation:

Uses the same validation logic as production
Maintains database consistency
Provides realistic response structures
Includes appropriate processing delays
Handles all edge cases and error scenarios

This ensures that integrations tested in sandbox will work seamlessly in production with minimal changes required.