Migration Guide

Migrating to Corridorly

A comprehensive guide for migrating your payment infrastructure to Corridorly's intelligent orchestration platform. Follow our proven strategies to minimise risk and ensure a smooth transition.

Introduction

Migrating payment infrastructure is a critical undertaking that requires careful planning and execution. This guide provides a battle-tested approach for migrating to Corridorly from direct payment provider integrations or other orchestration platforms.

Timeline

Typical migration: 2-4 weeks from planning to full cutover

Risk Level

Low with parallel running and gradual rollout

Testing Phase

1-2 weeks of parallel testing recommended

Migration Paths

Choose the migration strategy that best fits your current setup:

Path 1: Direct Provider Integration → Corridorly

You're currently integrating directly with payment providers in your application code.

Simplest migration path

Provider relationships remain intact

Can start with single provider, add more later

Path 2: Another Orchestrator → Corridorly

You're using another payment orchestration platform and want to migrate to Corridorly's symphony-based approach.

Parallel running reduces risk

Map existing routing rules to symphonies

Requires careful webhook migration

Path 3: Multi-Provider Manual Routing → Corridorly

You've built custom routing logic with multiple providers and want to replace it with intelligent orchestration.

Immediate routing improvement

Reduce maintenance burden

Preserve existing provider relationships

Pre-Migration Checklist

Complete these steps before beginning your migration:

Audit Current Payment Flow

Document all payment providers, transaction volumes, success rates, and average response times

Map Routing Logic

Document your current routing rules, fallback logic, and special cases

Review Webhook Handlers

List all webhook endpoints and the events they handle from current providers

Set Up Corridorly Environments

Configure Sandbox and Production environments with your Corridorly account manager

Generate API Keys

Create API keys for both Sandbox and Production environments in the Corridorly dashboard

Define Success Criteria

Establish metrics: success rate, latency, error rate thresholds for go-live

Migrating from Direct Provider Integration

Step-by-step guide for migrating from direct payment provider integrations to Corridorly's orchestration layer.

Understand Your Current Flow

Typical Direct Integration Flow:

1. Customer initiates payment in your app

2. Your backend calls payment provider API directly

3. Provider returns payment result

4. Provider sends webhook to your endpoint

5. Your app updates invoice/subscription status

Key consideration: Identify all code paths where you call provider APIs (payment creation, refunds, disputes, etc.)

Replace Provider API Calls

Replace direct provider API calls with Corridorly symphony execution:

Before: Direct Provider Call

// Old: Direct provider integration
const payment = await paymentProvider.createPayment({
  amount: 9900,
  currency: 'GBP',
  customerId: customerId,
  paymentMethodId: paymentMethodId,
  metadata: {
    invoiceId: 'INV-12345',
    customerId: 'CUST-789',
  },
});

After: Corridorly Orchestration

// New: Corridorly smart routing
const response = await fetch(
  'https://orchestrate.corridorly.com/symphony/execute/marketplace/smart_global_router',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': process.env.CORRIDORLY_API_KEY,
      'X-Tenant-Id': process.env.CORRIDORLY_TENANT_ID,
    },
    body: JSON.stringify({
      context: {
        amount: 9900,
        currency: 'GBP',
        customer: {
          id: customerId,
          email: customerEmail,
          country: 'GB',
        },
        paymentMethod: {
          type: 'card',
          token: paymentMethodToken,
        },
      },
    }),
  }
);

const { executionId, status, context } = await response.json();

Configure Corridorly Webhooks

Corridorly sends webhooks about symphony execution results. Configure your webhook endpoint to receive these events:

Key Corridorly Webhook Events:

Symphony Execution Completed- When symphony finishes successfully

Symphony Execution Failed- When symphony encounters an error

Payment Event- When payment orchestration completes

Important: Webhook Security

All Corridorly webhooks are signed with HMAC-SHA256. Always verify the X-Corridorly-Signature header to ensure authenticity. See the Webhooks documentation for implementation details.

Test in Sandbox Environment

Sandbox URL: https://orchestrate.sandbox.corridorly.com
Production URL: https://orchestrate.corridorly.com

Use your Corridorly Sandbox environment and API keys
Execute test transactions through the smart router
Verify webhook delivery and signature verification
Test failure scenarios (declined payments, network errors)
Confirm execution logs match expected behaviour

Parallel Running Strategy

Run Corridorly alongside your existing integration to validate behaviour before full cutover.

Shadow Mode Testing

Send the same transaction to both your existing integration and Corridorly, but only use the result from your existing integration:

Parallel Execution Pattern

// Execute both integrations in parallel
const [legacyResult, corridorlyResult] = await Promise.all([
  // Existing integration (production)
  processPaymentLegacy(paymentData),

  // Corridorly integration (shadow mode)
  processPaymentCorridorly(paymentData).catch(err => {
    // Log errors but don't fail the request
    logger.error('Corridorly shadow mode error:', err);
    return null;
  }),
]);

// Use legacy result for now
if (legacyResult.success) {
  // Compare results in background for validation
  if (corridorlyResult) {
    compareResults(legacyResult, corridorlyResult);
  }
  return legacyResult;
}

Zero risk: Production traffic still uses existing integration

Validation: Compare provider selection, response times, success rates

Confidence building: Run for 1-2 weeks before cutover

Percentage-Based Rollout

Gradually increase traffic to Corridorly:

Week 11% Traffic

Send 1% of production traffic through Corridorly. Monitor closely for errors.

Week 210% Traffic

Increase to 10% if Week 1 metrics look good (success rate, latency).

Week 350% Traffic

Ramp to 50%. Corridorly should now be handling significant volume.

Week 4100% Traffic

Full cutover. Decommission old integration after monitoring period.

Testing & Validation

Comprehensive testing checklist before production cutover:

Functional Tests

Successful payment processing
Declined payment handling
Network timeout scenarios
Provider failover behaviour
Refund processing
Webhook delivery and retry

Performance Tests

Latency compared to baseline
Throughput under peak load
Success rate parity
Provider selection accuracy
Symphony execution time
Concurrent request handling

Security Tests

Webhook signature validation
API key rotation procedure
HTTPS enforcement
Sensitive data handling
Access control (RBAC)
Audit log validation

Integration Tests

Order management system sync
Accounting system integration
Customer notification delivery
Analytics/reporting pipeline
Fraud detection system
Subscription management

Cutover Plan

Execute the final migration during a low-traffic window:

Recommended Cutover Timeline

T - 24h

Final Preparation

• Notify team of cutover window
• Verify Corridorly API keys are active in Production
• Test rollback procedure one final time

T - 0

Begin Cutover

• Enable feature flag for Corridorly routing
• Start with 1% traffic as final sanity check

T + 15m

Monitor Initial Traffic

• Check error rates, success rates, latency
• Verify webhook delivery
• If all metrics green, increase to 10%

T + 1h

Ramp to 100%

• If 10% traffic stable for 30 min, increase to 50%
• After 15 min, increase to 100%
• Keep legacy integration code in place for rollback

T + 24h

Post-Cutover Review

• Compare metrics to pre-migration baseline
• Review any incidents or errors
• If stable, schedule legacy code removal

Stop/Rollback Criteria

Immediately rollback if you observe:

• Success rate drops below 99% (or your baseline threshold)
• P95 latency increases by more than 50%
• Error rate exceeds 0.5%
• Webhook delivery failures spike above 1%
• Any payment provider connection issues

Rollback Strategy

Always have a tested rollback plan ready during migration:

Quick Rollback Procedure

1
Disable Corridorly Feature Flag
Immediately route traffic back to legacy integration via feature flag toggle
2
Verify Legacy System Health
Confirm legacy integration is processing payments successfully
3
Notify Corridorly Support
Alert your account manager with rollback reason and diagnostics
4
Root Cause Analysis
Work with Corridorly team to identify and fix the issue before retry

Rollback Testing

Test your rollback procedure in Sandbox environment before production cutover. Ensure you can revert traffic in under 60 seconds.

Post-Migration

Tasks to complete after successful cutover:

Week 1 Post-Migration

Monitor daily metrics: success rate, latency, error rate
Review Corridorly execution logs for anomalies
Verify all webhook events are being received
Keep legacy integration code in place (don't delete yet)

Week 2-4 Post-Migration

Compare month-over-month payment success rates
Analyse routing decisions and optimisation opportunities
Review cost savings from intelligent routing
Schedule decommissioning of legacy payment code

Long-term Optimisations

Explore custom routing rules for specific use cases
Add additional payment providers to increase routing options
Create instance symphonies for advanced workflows
Leverage Corridorly analytics for business insights

Common Pitfalls

Avoid these common mistakes during migration:

Skipping Parallel Running Phase

Going straight to production cutover without shadow mode testing significantly increases risk. Always run in parallel first.

Not Testing Webhook Signatures

Failing to implement HMAC-SHA256 webhook signature verification leaves your system vulnerable to replay attacks.

Inadequate Error Handling

Not handling Corridorly-specific error responses properly can cause silent failures. Always check the status field in responses.

Using Production API Keys in Sandbox

Using production Corridorly API keys in your Sandbox environment can process real transactions. Always use separate Sandbox API keys for testing.

No Rollback Plan

Not having a tested rollback procedure means you can't quickly revert if issues arise. Always test your rollback in Sandbox.

Migrating During Peak Hours

Attempting cutover during high-traffic periods increases risk. Always migrate during your lowest-traffic window.

Need Migration Assistance?

Our migration team is here to help ensure a smooth transition. Enterprise customers receive dedicated support throughout the migration process.

Contact Migration Team View Best Practices