August 20, 2025 - v1.2.0

Overview

This release introduces batch operation support, enhanced refund capabilities, and improved payout features. Includes one breaking change for deprecated timestamp format removal.

New Features

1. Batch Order Creation

What's New

Create multiple payment orders in a single API call:

POST /api/v1/payment-gateway/orders/batch-create

Features:

• Create up to 100 orders per request
• Automatic QR code generation for each order
• Atomic transaction support (all or nothing)
• Bulk validation before processing

Request Example:

{
  "orders": [
    {
      "store_id": "store-123",
      "amount": 100.00,
      "currency": "USD",
      "reference_id": "inv-001"
    },
    {
      "store_id": "store-123",
      "amount": 50.00,
      "currency": "USD",
      "reference_id": "inv-002"
    }
  ],
  "atomic": true
}

Impact of Feature

• Reduces API calls by up to 100x for bulk operations
• Improved performance for marketplace platforms
• Better UX for multi-item checkouts
• Simplified error handling with atomic mode

Implementation Reference

→ Documentation at /api-reference/batch-operations#create-orders

2. Automatic Refund Processing

What's New

Automated refund processing with configurable rules:

Features:

• Time-based automatic refunds (e.g., refund after 7 days)
• Condition-based refunds (order status triggers)
• Scheduled refund batches
• Configurable via merchant dashboard

Refund Rules Example:

{
  "rule_type": "time_based",
  "conditions": {
    "order_age_days": 7,
    "order_status": "pending",
    "action": "full_refund"
  }
}

Impact of Feature

• Reduces manual refund operations
• Consistent refund policy enforcement
• Improved customer satisfaction
• Automated compliance with refund policies

Implementation Reference

→ Configure in the merchant dashboard under Refund Settings

3. Partial Refund History

What's New

Detailed refund history with partial refund tracking:

New Endpoint:

GET /api/v1/payment-gateway/order/{order_id}/refund-history

Response Format:

{
  "order_id": "ord_abc123",
  "total_refunded": 75.00,
  "original_amount": 100.00,
  "refunds": [
    {
      "refund_id": "ref_xyz789",
      "amount": 50.00,
      "created_at": "2025-08-20T10:00:00Z",
      "reason": "Customer request"
    },
    {
      "refund_id": "ref_xyz790",
      "amount": 25.00,
      "created_at": "2025-08-20T14:30:00Z",
      "reason": "Partial item return"
    }
  ]
}

Impact of Feature

• Complete audit trail for refunds
• Support for multiple partial refunds
• Better customer service insights
• Improved reconciliation workflows

Implementation Reference

→ Documentation at /api-reference/refund-order#history

4. Enhanced Payout Scheduling

What's New

Advanced payout scheduling options:

Features:

• Daily, weekly, or monthly payout schedules
• Minimum payout threshold configuration
• Automatic payout to multiple bank accounts
• Hold period configuration for risk management

Payout Schedule Configuration:

{
  "schedule": "weekly",
  "day_of_week": "friday",
  "minimum_amount": 1000.00,
  "currency": "USD",
  "hold_period_days": 3
}

Impact of Feature

• Automated settlement workflows
• Better cash flow management
• Risk mitigation with hold periods
• Support for marketplace split payments

Implementation Reference

→ Documentation at /api-reference/payout#scheduling

5. Payout Batch Operations

What's New

Process multiple payouts in a single request:

POST /api/v1/payment-gateway/payouts/batch

Features:

• Process up to 50 payouts per request
• Atomic transaction support
• Bulk balance validation
• Individual payout status tracking

Impact of Feature

• Efficient bulk payout processing
• Reduced API overhead
• Better for marketplace platforms
• Simplified reconciliation

Implementation Reference

→ Documentation at /api-reference/batch-operations#payouts

Modifications

1. Refund API Enhancement

What's New

Enhanced refund endpoint with additional parameters:

New Optional Parameters:

• reason: Refund reason (for tracking)
• notify_customer: Send email notification (default: true)
• internal_notes: Internal notes (not visible to customer)
• refund_method: Specify refund method (original_method, store_credit)

Previous Request:

{
  "order_id": "ord_abc123",
  "amount": 50.00
}

Enhanced Request:

{
  "order_id": "ord_abc123",
  "amount": 50.00,
  "reason": "defective_product",
  "notify_customer": true,
  "internal_notes": "Approved by manager",
  "refund_method": "original_method"
}

Impact of Modification

• Better refund tracking and reporting
• Improved customer communication
• Enhanced internal documentation
• Flexible refund methods

What Might Cause Breaking Changes

None - All new parameters are optional. Default behavior unchanged.

2. Payout Response Enhancement

What's New

Additional fields in payout response:

New Fields:

• estimated_arrival: Estimated payout arrival time
• fee: Platform fee charged for payout
• net_amount: Amount after fees
• bank_reference: Bank transaction reference
• processing_time_seconds: Actual processing time

Previous Response:

{
  "payout_id": "pay_xyz123",
  "amount": 1000.00,
  "status": "completed"
}

Enhanced Response:

{
  "payout_id": "pay_xyz123",
  "amount": 1000.00,
  "fee": 5.00,
  "net_amount": 995.00,
  "status": "completed",
  "estimated_arrival": "2025-08-23T10:00:00Z",
  "bank_reference": "BNK20250820XYZ",
  "processing_time_seconds": 2.3
}

Impact of Modification

• Better transparency on fees
• Accurate arrival time estimates
• Improved reconciliation with bank statements
• Performance monitoring capabilities

What Might Cause Breaking Changes

None - This is purely additive. All existing fields unchanged.

3. Rate Limit Headers

What's New

Standard rate limit headers now included in all API responses:

New Response Headers:

• X-RateLimit-Limit: Request limit per minute
• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: Unix timestamp when limit resets

Example:

X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1847
X-RateLimit-Reset: 1692547200

Impact of Modification

• Better rate limit management
• Proactive throttling in applications
• Reduced 429 errors
• Improved API client implementations

What Might Cause Breaking Changes

None - Headers are informational only.

Breaking Changes

1. Removal of ISO 8601 Timestamp Support

What Changed

The X-Timestamp header no longer accepts ISO 8601 format. Only Unix timestamp is supported.

Deprecated Format (NO LONGER WORKS):

X-Timestamp: 2025-08-20T14:30:00Z

Required Format:

X-Timestamp: 1724165400

Impact of Feature

• Requests with ISO 8601 timestamps will be rejected with 401 Unauthorized
• Error message: "Invalid timestamp format. Use Unix timestamp."

What Might Cause Breaking Changes

If your application still uses ISO 8601 format for X-Timestamp, all API requests will fail immediately after upgrading.

Migration Steps:

1. Update timestamp generation:

JavaScript:

// Before (deprecated)
const timestamp = new Date().toISOString();

// After (required)
const timestamp = Math.floor(Date.now() / 1000).toString();

Go:

// Before (deprecated)
timestamp := time.Now().Format(time.RFC3339)

// After (required)
timestamp := fmt.Sprintf("%d", time.Now().Unix())

2. Test thoroughly before deploying
3. Monitor for 401 errors after deployment

Rollback Plan:

Deprecations

1. Single Payout Endpoint Deprecation Notice

What's Deprecated

The single payout endpoint will be deprecated in favor of batch operations:

Current Endpoint (will be deprecated in v2.0.0):

POST /api/v1/payment-gateway/payout

Preferred Endpoint:

POST /api/v1/payment-gateway/payouts/batch

Timeline:

• Now: Both endpoints work
• v1.3.0 (December 2025): Deprecation warning added
• v2.0.0 (June 2026): Single endpoint removed

Migration:

Use the batch endpoint even for single payouts:

{
  "payouts": [
    {
      "account_id": "acc_123",
      "amount": 1000.00,
      "currency": "USD"
    }
  ]
}

Technical Details

Performance Improvements

• Batch operations process 10x faster than individual requests
• Average payout processing time reduced from 5s to 2.3s
• Webhook delivery success rate improved to 99.5%

Infrastructure Updates

• Database connection pooling optimized
• Redis cache layer added for transaction lookups
• CDN added for QR code image delivery

Migration Checklist

• CRITICAL: Update X-Timestamp to Unix format (breaking change)
• Implement batch order creation for bulk operations (recommended)
• Add refund history tracking to admin panels (optional)
• Configure automatic refund rules (optional)
• Update payout code to use batch endpoint (prepare for v2.0.0)
• Parse new rate limit headers for better throttling (recommended)

Testing Recommendations

1. Test the timestamp format change in the staging environment first
2. Verify batch operations work with your existing workflows
3. Test refund history endpoint integration
4. Validate payout scheduling configuration
5. Monitor rate limit headers to optimize request patterns

Documentation

• Batch Operations (new)
• Refund History (updated)
• Payout Scheduling (updated)
• Rate Limits (updated)
• Migration Guide (new)