Documentation
Quick Start

Get Started in 8 Minutes

From login to your first intelligent payment routing in under 8 minutes. This guide walks you through accessing your account, getting your API keys, and executing your first smart router payment.

~8 minutesBeginner friendlycURL examples

What You'll Build

By the end of this guide, you'll have executed your first intelligent payment routing—a smart router call that automatically selects the optimal payment provider based on multiple factors like geography, cost, and success rates.

Learning Outcomes

Access your Corridorly dashboard
Generate and manage API keys securely
Understand how the smart router works
Execute an intelligent payment routing via API
Configure webhooks for real-time updates
Understand routing decision factors

Prerequisites

Before you begin, ensure you have the following:

Account Credentials

Login credentials provided by Corridorly during onboarding

Command Line

Access to a terminal with cURL installed (or any HTTP client like Postman)

8 Minutes

Set aside uninterrupted time to complete the full setup

Account Setup: Your Corridorly account, including your genesis user credentials and initial configuration, is created for you during the onboarding process after contract signing. This guide assumes you've already received your login details from the Corridorly team.

1

Access Your Account1 min

Log in to your Corridorly dashboard using the credentials provided by the Corridorly team during onboarding.

First Login

1.1

Navigate to Login

Visit the Corridorly platform and click "Log In".

Go to login
1.2

Enter Genesis User Credentials

Use the email and temporary password provided by Corridorly in your welcome email. You'll be prompted to set a new secure password on first login.

1.3

Explore Your Dashboard

Once logged in, you'll see your dashboard with your pre-configured tenant and development environment. Your account has admin privileges to manage API keys, team members, and settings.

Logged in! You're now ready to generate API keys and start using the Corridorly platform.

2

Generate API Keys1 min

API keys authenticate your requests to Corridorly. You'll need both a public key (for client-side operations) and a secret key (for server-side API calls).

Create Your API Keys

2.1

Navigate to Settings

From your dashboard, navigate to API key management:
  1. 1.Click Settings in the sidebar
  2. 2.Select API Keys
  3. 3.Ensure you're in the Development environment (check the environment selector)
2.2

Create New API Key

Click "Create API Key" and fill in the details:
  • Name: "Development Testing" (or similar)
  • Permissions: Select "Full Access" for testing
  • Expiry: Set to 90 days (or "Never" for development)
2.3

Save Your Secret Key

After creation, you'll see both keys. Copy and save your secret key immediately—it won't be shown again.

Security Warning: Never commit your secret key to version control or expose it client-side. Store it securely in environment variables.
Your API Keys
Public Key (safe to expose client-side)
pk_dev_1234567890abcdefghijklmnop
Secret Key (keep secure, server-side only)
sk_dev_abcdefghijklmnopqrstuvwxyz1234567890

Ready to authenticate! You now have API keys to make requests to Corridorly.

3

Understand the Smart Router1 min

The Smart Router is Corridorly's intelligent payment routing engine that automatically selects the optimal payment provider for each transaction based on multiple factors.

Multi-Factor Optimization

Evaluates all payment providers simultaneously, scoring each against cost, success rates, geographic performance, and compliance requirements.

Real-Time Decisions

Makes routing decisions in milliseconds based on current provider health, transaction characteristics, and your business rules.

How Smart Routing Works

1

Geographic Optimization

Providers are scored based on their performance in the customer's region. Local providers often have higher success rates and lower costs.

2

Cost Efficiency

Compares provider fees, currency conversion costs, and cross-border charges to minimize total transaction cost.

3

Historical Success Rates

Analyzes past transaction data to identify which providers have the highest approval rates for similar transactions.

4

Provider Health

Monitors real-time provider status, latency, and error rates to avoid routing to degraded systems.

5

Compliance & Currency Support

Ensures the selected provider supports the transaction currency and meets regional compliance requirements (SCA, PSD2, etc.).

The Result: Every payment is automatically routed to the provider with the best combination of cost, success probability, and compliance—no manual if-statements required.

4

Execute Your First Smart Routed Payment3 min

Now for the exciting part—execute an intelligent payment routing via the REST API. This single request triggers the smart router to select the optimal provider and process the payment.

Make Your First API Call

API Endpoint

POST /symphony/execute/marketplace/:symphonyIdREST API
https://api.corridorly.com/symphony/execute/marketplace/smart_global_router

The smart_global_router symphony ID is used to execute intelligent payment routing.

Request Headers

Content-Type: application/json
X-Api-Key: sk_dev_your_secret_key
X-Tenant-Id: your_tenant_id

Replace sk_dev_your_secret_key with your actual secret key from Step 2, and your_tenant_id with your tenant ID from your dashboard.

Request Body

JSON Payload
{
  "context": {
    "amount": 9900,
    "currency": "GBP",
    "customer": {
      "id": "cust_12345",
      "email": "user@example.com",
      "country": "GB"
    },
    "paymentMethod": {
      "type": "card",
      "token": "pm_test_card_visa"
    },
    "metadata": {
      "orderId": "order_789",
      "product": "Professional Plan - Monthly"
    }
  }
}

The context object contains all transaction details. The smart router uses these details to automatically select the optimal payment provider.

Complete cURL Command

Copy and execute in terminal
curl -X POST https://api.corridorly.com/symphony/execute/marketplace/smart_global_router \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_dev_your_secret_key" \
  -H "X-Tenant-Id: your_tenant_id" \
  -d '{
    "context": {
      "amount": 9900,
      "currency": "GBP",
      "customer": {
        "id": "cust_12345",
        "email": "user@example.com",
        "country": "GB"
      },
      "paymentMethod": {
        "type": "card",
        "token": "pm_test_card_visa"
      },
      "metadata": {
        "orderId": "order_789",
        "product": "Professional Plan - Monthly"
      }
    }
  }'

Expected Response

200 OK - Success ResponseSuccess
{
  "executionId": "exec_abc123def456",
  "symphonyId": "smart_global_router",
  "status": "success",
  "stages": [
    {
      "stageName": "payment_classifier",
      "recipeId": "recipe_payment_classifier",
      "status": "success",
      "executionTimeMs": 45,
      "output": {
        "paymentType": "card",
        "riskScore": 0.15,
        "region": "GB"
      }
    },
    {
      "stageName": "uk_router",
      "recipeId": "recipe_uk_payment_router",
      "status": "success",
      "executionTimeMs": 230,
      "output": {
        "selectedProvider": "stripe",
        "routingScore": 0.985,
        "routingFactors": {
          "geographicMatch": 0.98,
          "costEfficiency": 0.92,
          "successRate": 0.985,
          "providerHealth": 1.0,
          "complianceSupport": 1.0
        }
      }
    },
    {
      "stageName": "compliance_check",
      "recipeId": "recipe_compliance_validator",
      "status": "success",
      "executionTimeMs": 78,
      "output": {
        "compliant": true,
        "scaRequired": true,
        "psd2Compliant": true
      }
    }
  ],
  "context": {
    "amount": 9900,
    "currency": "GBP",
    "customer": {
      "id": "cust_12345",
      "email": "user@example.com",
      "country": "GB"
    },
    "paymentMethod": {
      "type": "card",
      "token": "pm_test_card_visa"
    },
    "selectedProvider": "stripe",
    "routingScore": 0.985,
    "compliant": true
  },
  "totalExecutionMs": 353
}

Understanding the Response

executionId:

Unique identifier for this symphony execution

symphonyId:

The symphony that was executed (smart_global_router)

status:

Execution status (success, failed, partial)

stages:

Array of all stages executed with their results and timing

context:

Final execution context with enriched data from all stages

totalExecutionMs:

Total time taken to execute the entire symphony

Congratulations! You've successfully executed your first smart router symphony. The system classified the payment, routed it through the UK router which selected Stripe with a score of 0.985 (98.5% optimal), validated compliance, and completed in 353ms.

5

Set Up Webhooks2 min

Webhooks let you receive real-time notifications when symphonies complete, payments succeed or fail, and other important events occur.

Configure Webhook Endpoints

5.1

Navigate to Webhook Settings

From your dashboard:
  1. 1.Go to Settings → Webhooks
  2. 2.Click "Add Webhook Endpoint"
5.2

Configure Your Endpoint

Enter your webhook URL and select events to receive:

Webhook Configuration
Endpoint URL
https://your-app.com/api/webhooks/corridorly
Events to Subscribe
symphony.execution.completed
symphony.execution.failed
payment.succeeded
payment.failed
5.3

Test Your Webhook

Use the "Send Test Event" button to verify your endpoint is receiving webhooks correctly. You should see a 200 OK response.

Pro tip: Use webhook testing tools like webhook.site or ngrok during local development to inspect webhook payloads.
5.4

Verify Webhook Signatures

For security, always verify webhook signatures. Here's a Node.js example:

Signature Verification (Node.js)
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

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

// In your webhook handler
app.post('/api/webhooks/corridorly', (req, res) => {
  const signature = req.headers['x-corridorly-signature'];
  const webhookSecret = process.env.CORRIDORLY_WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }

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

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

Webhooks configured! You'll now receive real-time notifications for symphony executions and payment events.

What's Next?

You've completed the quickstart! Here are recommended next steps to deepen your integration and explore advanced features.

Complete Integration Guide

Deep dive into production-ready integration patterns, error handling, idempotency, and best practices.

15-30 min read

API Reference

Explore all available endpoints, request/response schemas, authentication methods, and error codes.

Interactive docs

B2B SaaS Use Cases

Learn how to solve trial conversions, usage billing, global expansion, dunning, and more with real examples.

Real scenarios

Routing Engine Deep Dive

Understand how Corridorly's multi-factor routing engine optimises payment provider selection.

Technical

Additional Resources

Dashboard Tour: Explore executions, recipes, rules, and analytics in the UI
Team Management: Invite team members with role-based access control
Configure Providers: Connect Stripe, Adyen, and other payment processors
Production Checklist: Security, rate limits, monitoring before going live

Troubleshooting

Common issues and their solutions when getting started with Corridorly.

401 Unauthorized - Authentication Failed

Cause: Invalid or missing API key in the X-Api-Key header.

Solution:

  • Verify you're using the secret key (starts with sk_dev_), not the public key
  • Check the X-Api-Key header format: X-Api-Key: sk_dev_...
  • Ensure the API key hasn't been revoked or expired
  • Confirm you're in the correct environment (dev/staging/prod)

400 Bad Request - Invalid Symphony ID

Cause: The symphony_id doesn't exist or isn't available in your environment.

Solution:

  • Double-check the symphony ID from the marketplace
  • Verify the symphony is enabled for your tenant
  • Ensure you're using the correct environment-specific ID

422 Unprocessable Entity - Missing Required Fields

Cause: The execution_context is missing required fields for the symphony.

Solution:

  • Review the symphony documentation for required fields
  • Check the error response for specific missing field names
  • Validate field types match the schema (strings, numbers, objects)

Webhook Not Receiving Events

Cause: Webhook endpoint is unreachable or returning errors.

Solution:

  • Use "Send Test Event" to verify endpoint connectivity
  • Check webhook endpoint logs for incoming requests
  • Ensure your server responds with 200 OK within 5 seconds
  • For local development, use ngrok or webhook.site for testing
  • Verify firewall rules allow Corridorly webhook IPs

Symphony Execution Failed

Cause: A stage within the symphony failed (compliance, routing, payment).

Solution:

  • Check the stages_executed array in the response
  • Review the failed stage's error message and reason
  • Common causes: payment provider credentials, insufficient balance, blocked transaction
  • View execution details in Dashboard → Executions for full logs

Need More Help?

If you're still experiencing issues, we're here to help:

Contact SupportBrowse Documentation

You're All Set!

You've successfully completed the Corridorly quickstart. You can now execute symphonies, receive webhooks, and build production-ready payment orchestration.

Go to DashboardExplore Marketplace