Integrations
Overview
The Integrations module connects SynthesQ to external payment processors and communication providers. Rather than hard-coding a single gateway into your workflows, you register one or more provider integrations per tenant and the platform routes each operation - payment initiations, SMS sends, WhatsApp messages - to the correct provider at runtime based on configurable routing rules.
The module is built around a three-tier architecture: Integration Categories (Payment, Communication) group related Integration Providers (Stripe, Twilio, etc.), each of which exposes a set of Integration Capabilities (Initiate Payment, Send SMS, etc.). When you configure an integration, you choose which capabilities to enable. This lets a single Twilio integration serve both SMS and WhatsApp without duplicating credentials.
All provider operations are executed asynchronously. When your application triggers a payment or sends a message, the platform queues the operation, delivers it to the provider, and tracks the outcome through a series of delivery statuses. Retries are handled automatically. This async model keeps your API response times fast and your application decoupled from transient provider failures.
Supported Providers
| Provider | Category | Capabilities |
|---|---|---|
| Stripe | Payment | Initiate Payment, Process Refund, Verify Payment |
| PayPal | Payment | Initiate Payment, Process Refund |
| PhonePe | Payment | Initiate Payment |
| Cashfree | Payment | Initiate Payment, Process Refund |
| Twilio | Communication | Send SMS, Send WhatsApp |
| Plivo | Communication | Send SMS |
| TextLocal | Communication | Send SMS |
| WA Business | Communication | Send WhatsApp |
Quick Start
Discover available providers - call
GET /api/v1/integrations/providersto list all providers with their capabilities and credential schemas. Theis_configuredflag on each provider indicates whether your tenant already has an integration set up for it.Configure an integration - call
POST /api/v1/integrationswith the provider name, your credentials, and the capabilities you want to enable. The system will begin async credential verification immediately.Wait for verification - the integration starts in
pending_verifystatus. Once the async verification job completes, it transitions toactive(success) orerror(failure). PollGET /api/v1/integrations/{id}or wait for your application to receive the status change notification.Set up routing rules - call
POST /api/v1/routing-rulesto define which integration handles each capability. Rules support conditions (region, currency, amount thresholds) and a fallback integration for resilience.
Integration Lifecycle
Once configured, an integration moves through a defined set of statuses:
| Status | Description | Possible Transitions |
|---|---|---|
| pending_verify | Configured and awaiting async credential check | → active (verified), → error (failed) |
| active | Verified and eligible to receive routing | → inactive (manually disabled) |
| inactive | Manually disabled, no operations routed to it | → active (re-enabled) |
| error | Verification failed or runtime error detected | → pending_verify (after credential update) |
Async Verification
Credential verification happens in the background. Do not attempt to create routing rules for an integration until it reaches active status - routing rules that reference a non-active integration will not be selected during evaluation.
In This Section
- Managing Integrations - Configure providers, manage credentials, and control integration status.
- Routing Rules - Define which integration handles each capability and under what conditions.
- Delivery Tracking - Monitor async delivery attempts, understand retry behaviour, and investigate failures.