Documentation

Integration Guide

Everything you need to integrate Corridorly into your application

Step-by-stepPractical examplesQuick start

Overview

This guide walks you through integrating Corridorly into your application, from creating your account to executing your first symphony in production. You'll learn how to configure symphonies, make API calls, handle webhooks, and monitor executions.

Estimated time: 15-30 minutes to complete your first integration

What you'll learn

  • • Create and manage API keys
  • • Subscribe to marketplace symphonies
  • • Execute symphonies via API
  • • Configure webhooks for events
  • • Monitor execution history

Prerequisites

  • • A Corridorly account
  • • Basic API/REST knowledge
  • • HTTP client (curl, Postman, etc.)
  • • Optional: Webhook endpoint URL

Getting Started

1

Create Your Account

If you haven't already, sign up for a Corridorly account at corridorly.com. You'll receive immediate access to the dashboard and marketplace.

2

Create an API Key

Navigate to Settings → API Keys in your dashboard and create a new API key. This key authenticates your API requests.

Dashboard Navigation
  1. 1.Click Settings in the sidebar
  2. 2.Select API Keys
  3. 3.Click Create API Key
  4. 4.Give it a descriptive name (e.g., "Production API")
  5. 5.Copy and securely store the key (shown only once!)

Security Best Practices

  • • Never commit API keys to version control
  • • Store keys in environment variables or secret managers
  • • Use separate keys for sandbox and production environments
  • • Rotate keys periodically

Subscribe to Symphonies

Before you can execute a symphony, you need to subscribe to it from the Corridorly Marketplace. Subscriptions give you access to pre-built workflows that you can configure for your needs.

1

Browse Available Symphonies

Explore the available symphonies in your dashboard's marketplace section. Each symphony is designed for specific use cases like payment routing, compliance checks, or approval workflows. Contact your account manager to learn about symphonies available for your organization.

2

Subscribe to a Symphony

Click Subscribe on the symphony you want to use. This adds it to your Subscriptions page in the dashboard where you can configure it.

3

Review Input Requirements

Each symphony documents what data it needs in the context object. Check the symphony's documentation or test page to understand required fields.

Example: Smart Global Router Symphony
Required fields:
• amount (number) - Transaction amount
• currency (string) - ISO 4217 currency code (e.g., "USD")
• sourceCurrency (string) - Source currency code
• destinationCurrency (string) - Destination currency code
• sourceCountry (string) - ISO 3166-1 alpha-2 (e.g., "US")
• destinationCountry (string) - ISO 3166-1 alpha-2 (e.g., "GB")
• urgency (string) - "immediate", "standard", or "flexible"
• settlementPreference (string) - "fastest", "same-day", "balanced", or "next-day"

Optional fields:
• subClientId (string) - Sub-client identifier
• preferredRail (string) - Preferred payment rail (e.g., "fps", "sepa_instant")
• intendedExecutionTime (string) - ISO 8601 datetime
• beneficiaryBankCountry (string) - Bank country code

Configure Your Symphony

After subscribing, configure the symphony's behavior to match your requirements. Navigate to Subscriptions in your dashboard and select the symphony you subscribed to.

Settings Page

Each symphony has a Settings page where you can configure its behavior. Configuration options vary by symphony, but typically include:

Routing Configuration

Provider selection, weighting strategies, and routing logic that determines how requests are processed and routed.

Business Rules

Amount thresholds, currency corridors, and operational constraints that define how the symphony operates.

Integration Settings

External service credentials and API configurations for third-party integrations your symphony requires.

Monitoring & Alerts

Success rate thresholds, alert triggers, and notification preferences for monitoring symphony performance.

Check your specific symphony's documentation or Settings page to see which configuration options are available.

Test Your Configuration

Use the Test tab to execute the symphony with sample data before integrating it into your application.

Interactive Testing
  1. 1.Navigate to your symphony's Test page
  2. 2.Fill in the context with test data
  3. 3.Click Execute Symphony
  4. 4.Review the execution results and timing
  5. 5.Adjust settings if needed and test again

Make Your First API Call

Now that you have an API key and a configured symphony, you're ready to execute it from your application.

Authentication

Every API request requires two headers:

X-Api-Key:your_api_key_here
X-Tenant-Id:your_tenant_id

You can find your Tenant ID in your account settings or contact support

Execute a Symphony

Use the symphony execution endpoint to run your configured workflow:

POST /symphony/execute/marketplace/:symphonyId
curl -X POST https://orchestrate.corridorly.com/symphony/execute/marketplace/smart_global_router \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Tenant-Id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "amount": 50000,
      "currency": "USD",
      "sourceCurrency": "USD",
      "destinationCurrency": "GBP",
      "sourceCountry": "US",
      "destinationCountry": "GB",
      "urgency": "standard",
      "settlementPreference": "balanced"
    }
  }'

Tip: Replace smart_global_router with your symphony's ID, found on the subscription details page.

Understanding the Response

The API returns detailed execution results including decisions from each stage:

Response Structure
{
  "executionId": "exec_abc123def456",
  "symphonyId": "smart_global_router",
  "status": "success",
  "stages": [
    {
      "stageNumber": 1,
      "stageName": "route_selection",
      "status": "complete",
      "executionTimeMs": 156,
      "decisions": {
        "providerId": "wise",
        "rail": "swift",
        "estimatedCost": 45.50,
        "estimatedCostCurrency": "USD",
        "estimatedSettlementTime": 86400,
        "confidence": 92,
        "reasoning": [
          "Cost-optimized route selected",
          "Provider supports USD-GBP corridor",
          "Standard urgency allows 24h settlement"
        ]
      }
    },
    {
      "stageNumber": 2,
      "stageName": "validation",
      "status": "complete",
      "executionTimeMs": 45,
      "decisions": {
        "corridorSupported": true,
        "amountWithinLimits": true,
        "providerActive": true
      }
    }
  ],
  "context": {
    "amount": 50000,
    "currency": "USD",
    "sourceCurrency": "USD",
    "destinationCurrency": "GBP",
    "sourceCountry": "US",
    "destinationCountry": "GB",
    "urgency": "standard",
    "settlementPreference": "balanced"
  },
  "totalExecutionMs": 201
}
executionId

Unique identifier for this execution, used for tracking and debugging

status

Overall result: success, failed, or partial

stages

Results from each stage with timing and decisions

Set Up Webhooks

Webhooks allow Corridorly to notify your application when events occur, such as symphony completions, payment status changes, or approval decisions.

Configure Your Webhook Endpoint

Dashboard Setup
  1. 1.Navigate to Settings → Webhooks
  2. 2.Click Add Webhook Endpoint
  3. 3.Enter your webhook URL (must be HTTPS in production)
  4. 4.Select which events to receive
  5. 5.Save and copy your webhook signing secret

Verify Webhook Signatures

All webhooks include an X-Corridorly-Signature header containing an HMAC-SHA256 signature. Verify this to ensure the webhook came from Corridorly.

Signature Verification (Node.js)
import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/corridorly', (req, res) => {
  const signature = req.headers['x-corridorly-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook
  const event = req.body;
  console.log('Received event:', event.type);

  res.status(200).send('OK');
});

For detailed verification examples in other languages, see the Webhooks documentation.

Event Types

symphony.execution.completed

Fired when a symphony execution finishes successfully

symphony.execution.failed

Fired when a symphony execution fails

payment.status.updated

Payment status changed (e.g., succeeded, failed, pending)

approval.decision.made

An approval decision was made (approved or rejected)

Team Management

Invite team members and control their access to your Corridorly organization.

Invite Team Members

Settings → Team
  1. 1.Navigate to Settings → Team
  2. 2.Click Invite Member
  3. 3.Enter email address and select role
  4. 4.Send invitation - they'll receive an email to join

Roles & Permissions

Admin

Full access to all features, settings, and team management

Developer

Can manage API keys, configure symphonies, view executions

Viewer

Read-only access to executions and analytics

Monitor & Debug

Track your symphony executions, understand routing decisions, and debug issues using the Corridorly dashboard.

Execution History

Navigate to Executions in your dashboard to view a complete history of all symphony executions. Click any execution to see detailed stage-by-stage results.

Execution Details

  • • Complete stage-by-stage timeline
  • • Decisions made at each step
  • • Execution time per stage
  • • Full request and response context
  • • Error details if any stage failed

Filtering & Search

  • • Filter by symphony type
  • • Filter by status (success/failed)
  • • Search by execution ID
  • • Filter by date range
  • • Filter by customer ID or metadata

Understanding Routing Decisions

Each execution shows exactly why routing decisions were made:

Example: Routing Stage Details
Selected Provider: Stripe
Reason: Cost optimized (lowest total fee)
Alternatives Considered: Adyen, PayPal
Factors: USD currency, amount $100, US billing

Debugging Failed Executions

When an execution fails, the dashboard shows:

  • Which stage failed and why
  • Error code and message
  • Context data that was passed to the failing stage
  • Results from previous successful stages

Going to Production

Before going live with Corridorly in production, follow these best practices:

Sandbox vs Production

Corridorly provides separate sandbox and production environments. Use the sandbox environment for development and testing to avoid real charges and external API calls.

Environment URLs
Sandbox
https://orchestrate.sandbox.corridorly.com
Production
https://orchestrate.corridorly.com

Use separate API keys for each environment. Sandbox transactions won't process real payments.

Separate API Keys Per Environment

Create separate API keys for sandbox and production environments. Never use sandbox keys in production or vice versa. Store all keys in secure secret management systems (AWS Secrets Manager, Vault, etc.).

Configure Production Settings

Ensure your symphony settings reflect production requirements:

  • • Production payment provider credentials
  • • Appropriate risk thresholds
  • • Real webhook endpoints (HTTPS required)
  • • Notification channels configured

Monitor Production Traffic

Set up alerts for failed executions, monitor success rates, and review execution times regularly. Use the dashboard analytics to track performance.

Security Checklist

  • API keys stored in environment variables
  • Webhook signatures verified on every request
  • HTTPS used for all webhook endpoints
  • Team member access follows principle of least privilege