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

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.

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.Click Settings in the sidebar
2.Select API Keys
3.Click Create API Key
4.Give it a descriptive name (e.g., "Production API")
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 development, staging, and production
• Rotate keys periodically

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 tab where you can configure:

Routing Rules

Configure which payment providers to use, priority ordering, and routing criteria like geography or amount thresholds.

Thresholds

Set risk score thresholds, amount limits, and other parameters that control symphony behavior.

Provider Credentials

Add API keys and credentials for third-party services the symphony integrates with (payment providers, KYC services, etc.).

Notifications

Configure when to send notifications, which events trigger alerts, and notification channels.

Test Your Configuration

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

Interactive Testing

1.Navigate to your symphony's Test page
2.Fill in the context with test data
3.Click Execute Symphony
4.Review the execution results and timing
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

Your Tenant ID is displayed in Settings → General

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/payment_router \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Tenant-Id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "amount": 10000,
      "currency": "USD",
      "paymentMethod": "card",
      "customerId": "cust_123",
      "billingCountry": "US"
    }
  }'

Tip: Replace payment_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": "payment_router",
  "status": "success",
  "stages": [
    {
      "stageNumber": 1,
      "stageName": "compliance",
      "status": "complete",
      "executionTimeMs": 245,
      "decisions": {
        "kycApproved": true,
        "riskLevel": "low",
        "sanctionsMatch": false
      }
    },
    {
      "stageNumber": 2,
      "stageName": "routing",
      "status": "complete",
      "executionTimeMs": 156,
      "decisions": {
        "selectedProvider": "stripe",
        "routingReason": "cost_optimized",
        "estimatedFee": 29
      }
    },
    {
      "stageNumber": 3,
      "stageName": "payment",
      "status": "complete",
      "executionTimeMs": 892,
      "decisions": {
        "transactionId": "txn_xyz789",
        "providerStatus": "succeeded",
        "processingFee": 29
      }
    }
  ],
  "context": {
    "amount": 10000,
    "currency": "USD",
    "stages": {
      "compliance": { "kycApproved": true, "riskLevel": "low" },
      "routing": { "selectedProvider": "stripe" },
      "payment": { "transactionId": "txn_xyz789" }
    }
  },
  "totalExecutionMs": 1293
}

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.Navigate to Settings → Webhooks
2.Click Add Webhook Endpoint
3.Enter your webhook URL (must be HTTPS in production)
4.Select which events to receive
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.Navigate to Settings → Team
2.Click Invite Member
3.Enter email address and select role
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:

Test Mode vs Production

Use test mode during development by setting testMode: true in your request metadata. This prevents real charges and external API calls.

{
  "context": { /* your data */ },
  "metadata": {
    "testMode": true
  }
}

Use Production API Keys

Create separate API keys for production and never use development keys in production. Store production keys in secure secret management systems.

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

Next Steps

You're ready to integrate Corridorly! Here are some helpful resources:

Technical Documentation

Deep dive into how the routing engine works

Webhooks Guide

Complete webhook implementation guide

API Reference

Full API documentation with examples

Browse Marketplace

Discover pre-built symphonies